{ "openapi": "3.0.0", "paths": { "/v2/jobtypes": { "get": { "description": "Retrieves a paginated list of Job Types.", "operationId": "findAll", "parameters": [ { "name": "pageSize", "required": false, "in": "query", "description": "Number of records to return per page.", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "The page index.", "schema": { "example": 1, "type": "number" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A paginated list of Job Types.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseJobTypesV2Dto" } } } }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Retrieve a list of Job Types", "tags": [ "JobTypes" ] }, "post": { "description": "Creates a new Job Type and returns the created Job Type object.", "operationId": "create", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": true, "description": "The Job Type data to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobTypeV2Dto" } } } }, "responses": { "201": { "description": "The created Job Type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseJobTypeV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." }, "409": { "description": "A job type with that name already exists." } }, "summary": "Create a new Job Type", "tags": [ "JobTypes" ] } }, "/v2/jobtypes/{id}": { "get": { "description": "Retrieves a single Job Type by its ID.", "operationId": "findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The job type ID (prefix `JT-`).", "schema": { "example": "JT-8718036049ec4c4d", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "The requested Job Type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseJobTypeV2Dto" } } } }, "400": { "description": "The provided ID is not a valid job type ID." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Job Type not found." } }, "summary": "Retrieve a single Job Type", "tags": [ "JobTypes" ] }, "put": { "description": "Updates an existing Job Type and returns the updated Job Type.", "operationId": "update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The job type ID (prefix `JT-`).", "schema": { "example": "JT-8718036049ec4c4d", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": false, "description": "The Job Type fields to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateJobTypeV2Dto" } } } }, "responses": { "200": { "description": "The updated Job Type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseJobTypeV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Job Type not found." }, "409": { "description": "A job type with that name already exists." } }, "summary": "Update an existing Job Type", "tags": [ "JobTypes" ] }, "delete": { "description": "Disables a Job Type by its ID.", "operationId": "delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The job type ID (prefix `JT-`).", "schema": { "example": "JT-8718036049ec4c4d", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "204": { "description": "Job Type disabled successfully." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Job Type not found." } }, "summary": "Disable a Job Type", "tags": [ "JobTypes" ] } }, "/v2/adgroups": { "get": { "description": "Retrieves a paginated list of Ad Groups.", "operationId": "findAll", "parameters": [ { "name": "pageSize", "required": false, "in": "query", "description": "Number of records to return per page.", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "The page index.", "schema": { "example": 1, "type": "number" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A paginated list of Ad Groups.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseAdGroupsV2Dto" } } } }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Retrieve a list of Ad Groups", "tags": [ "AdGroups" ] }, "post": { "description": "Creates a new Ad Group and returns the created Ad Group object.", "operationId": "create", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": true, "description": "The Ad Group data to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdGroupV2Dto" } } } }, "responses": { "201": { "description": "The created Ad Group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseAdGroupV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." }, "409": { "description": "An ad group with that name already exists." } }, "summary": "Create a new Ad Group", "tags": [ "AdGroups" ] } }, "/v2/adgroups/{id}": { "get": { "description": "Retrieves a single Ad Group by its ID.", "operationId": "findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The ad group ID (prefix `AG-`).", "schema": { "example": "AG-71b8d7310acbf8cc", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "The requested Ad Group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseAdGroupV2Dto" } } } }, "400": { "description": "The provided ID is not a valid ad group ID." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Ad Group not found." } }, "summary": "Retrieve a single Ad Group", "tags": [ "AdGroups" ] }, "put": { "description": "Updates an existing Ad Group and returns the updated Ad Group.", "operationId": "update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The ad group ID (prefix `AG-`).", "schema": { "example": "AG-71b8d7310acbf8cc", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": false, "description": "The Ad Group fields to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdGroupV2Dto" } } } }, "responses": { "200": { "description": "The updated Ad Group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseAdGroupV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Ad Group not found." }, "409": { "description": "An ad group with that name already exists." } }, "summary": "Update an existing Ad Group", "tags": [ "AdGroups" ] }, "delete": { "description": "Disables an Ad Group by its ID.", "operationId": "delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The ad group ID (prefix `AG-`).", "schema": { "example": "AG-71b8d7310acbf8cc", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "204": { "description": "Ad Group disabled successfully." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Ad Group not found." } }, "summary": "Disable an Ad Group", "tags": [ "AdGroups" ] } }, "/v2/event": { "get": { "description": "Retrieves a paginated list of Events.", "operationId": "findAll", "parameters": [ { "name": "pageSize", "required": false, "in": "query", "description": "Number of records to return per page.", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "The page index.", "schema": { "example": 1, "type": "number" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A paginated list of Events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseEventsV2Dto" } } } }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Retrieve a list of Events", "tags": [ "Events" ] }, "post": { "description": "Creates a new Event and returns the created Event object.", "operationId": "create", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": true, "description": "The Event data to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventV2Dto" } } } }, "responses": { "201": { "description": "The created Event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseEventV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Tech not found" } }, "summary": "Create a new Event", "tags": [ "Events" ] } }, "/v2/event/{id}": { "get": { "description": "Retrieves a single Event by its ID.", "operationId": "findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The event ID (prefix `EVT-`).", "schema": { "example": "EVT-Dxgp7NRjo6kXb5eG", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "The requested Event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseAttachEventV2Dto" } } } }, "400": { "description": "The provided ID is not a valid event ID." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Event not found." } }, "summary": "Retrieve a single Event", "tags": [ "Events" ] }, "put": { "description": "Updates an existing Event and returns the updated Event.", "operationId": "update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The event ID (prefix `EVT-`).", "schema": { "example": "EVT-Dxgp7NRjo6kXb5eG", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": false, "description": "The Event fields to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEventV2Dto" } } } }, "responses": { "200": { "description": "The updated Event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseEventV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Event not found." } }, "summary": "Update an existing Event", "tags": [ "Events" ] }, "delete": { "description": "Deletes an Event by its ID.", "operationId": "delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The event ID (prefix `EVT-`).", "schema": { "example": "EVT-Dxgp7NRjo6kXb5eG", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "204": { "description": "Event deleted successfully." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Event not found." } }, "summary": "Delete an Event", "tags": [ "Events" ] } }, "/v2/timeoff": { "get": { "description": "Retrieves a paginated list of Time Off based on the applied filters and pagination.", "operationId": "findAll", "parameters": [ { "name": "pageSize", "required": false, "in": "query", "description": "Number of records to return per page.", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "The page index.", "schema": { "example": 1, "type": "number" } }, { "name": "field", "required": false, "in": "query", "description": "The field to sort results by.", "schema": { "enum": [ "id", "techId", "startDate", "endDate", "status", "reason", "details", "isAllDay", "updatedAt", "createdAt" ], "type": "string" } }, { "name": "order", "required": false, "in": "query", "description": "The sort direction.", "examples": { "ASC": { "value": "ASC", "description": "Ascending order" }, "DESC": { "value": "DESC", "description": "Descending order" } }, "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } }, { "name": "techId", "required": false, "in": "query", "description": "Filter by tech ID (prefix `USR-`). Can be passed multiple times.", "style": "form", "explode": true, "schema": { "example": "USR-8c65ffdb713ea0ea", "type": "array", "items": { "type": "string" } } }, { "name": "baseDate", "required": false, "in": "query", "description": "The time off start-date boundary for the filter. Must be combined with `timeline`. Expected format: `YYYY-MM-DD HH:MM:SS`.", "schema": { "format": "date-time", "example": "2025-01-13 13:36:46", "type": "string" } }, { "name": "timeline", "required": false, "in": "query", "description": "Comparison direction for the date filter. Must be combined with `baseDate`. `prev` shows time offs starting before baseDate; `next` shows time offs starting on or after baseDate.", "examples": { "prev": { "value": "prev", "description": "Before start date" }, "next": { "value": "next", "description": "On or after start date" } }, "schema": { "enum": [ "prev", "next" ], "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A paginated list of Time Off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseTimeoffsV2Dto" } } } }, "400": { "description": "Invalid sort field, order direction, tech ID, or incomplete/invalid baseDate and timeline filters." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Retrieve a list of Time Off", "tags": [ "TimeOffs" ] }, "post": { "description": "Creates a new Time Off and returns the created Time Off object.", "operationId": "create", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": true, "description": "The Time Off data to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTimeOffV2Dto" } } } }, "responses": { "201": { "description": "The created Time Off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseTimeOffV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Create a new Time Off", "tags": [ "TimeOffs" ] } }, "/v2/timeoff/future": { "get": { "description": "Retrieves a paginated list of future approved time offs based on the current date and pagination.", "operationId": "findFutureTimeOffs", "parameters": [ { "name": "pageSize", "required": false, "in": "query", "description": "Number of records to return per page.", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "The page index.", "schema": { "example": 1, "type": "number" } }, { "name": "field", "required": false, "in": "query", "description": "The field to sort results by.", "schema": { "enum": [ "id", "techId", "startDate", "endDate", "status", "reason", "details", "isAllDay", "updatedAt", "createdAt" ], "type": "string" } }, { "name": "order", "required": false, "in": "query", "description": "The sort direction.", "examples": { "ASC": { "value": "ASC", "description": "Ascending order" }, "DESC": { "value": "DESC", "description": "Descending order" } }, "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A paginated list of future approved Time Off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseTimeoffsV2Dto" } } } }, "400": { "description": "Invalid sort field or order direction." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Retrieve future time offs", "tags": [ "TimeOffs" ] } }, "/v2/timeoff/{id}": { "get": { "description": "Retrieves a single Time Off by its ID.", "operationId": "findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The time off ID (prefix `TO-`).", "schema": { "example": "TO-de9750285414508f", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "The requested Time Off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseTimeOffV2Dto" } } } }, "400": { "description": "The provided ID is not a valid time off ID." }, "401": { "description": "Missing or invalid authentication token." }, "403": { "description": "Access to this time off is not allowed." }, "404": { "description": "Time off not found." } }, "summary": "Retrieve a single Time Off", "tags": [ "TimeOffs" ] }, "put": { "description": "Updates an existing Time Off and returns the updated Time Off.", "operationId": "update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The time off ID (prefix `TO-`).", "schema": { "example": "TO-de9750285414508f", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": false, "description": "The Time Off fields to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTimeOffV2Dto" } } } }, "responses": { "200": { "description": "The updated Time Off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseTimeOffV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Time off not found." } }, "summary": "Update an existing Time Off", "tags": [ "TimeOffs" ] }, "delete": { "description": "Deletes a Time Off by its ID.", "operationId": "delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The time off ID (prefix `TO-`).", "schema": { "example": "TO-de9750285414508f", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "204": { "description": "Time off deleted successfully." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Time off not found." } }, "summary": "Delete a Time Off", "tags": [ "TimeOffs" ] } }, "/v2/clients": { "get": { "description": "Returns a paginated list of clients. Supports full-text search, tag filtering, due-balance filtering, sorting, and date-range filtering. Results are sourced from Elasticsearch and include basic contact and address information.", "operationId": "findAll", "parameters": [ { "name": "pageSize", "required": false, "in": "query", "description": "Number of records to return per page.", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "The page index.", "schema": { "example": 1, "type": "number" } }, { "name": "searchQuery", "required": false, "in": "query", "description": "Free-text search string matched against full name, company name, full address, parent full name, custom fields, primary phone, and email address.", "schema": { "example": "John Doe", "type": "string" } }, { "name": "isDue", "required": false, "in": "query", "description": "Filter clients by outstanding balance status. `Due` returns clients with any open balance; `PastDue` returns clients whose balance is overdue.", "schema": { "enum": [ "PastDue", "Due" ], "type": "string" } }, { "name": "tags", "required": false, "in": "query", "description": "Comma-separated list of tag IDs to filter by. Only clients that have **all** specified tags are returned.", "schema": { "example": "TAG-16a94b03317f6e64,TAG-211d1676f4b90c40", "type": "string" } }, { "name": "field", "required": false, "in": "query", "description": "Field to sort results by. When omitted the default sort is by `serialId` descending.", "schema": { "enum": [ "serialId", "firstName", "fullName", "clientCompany", "primaryPhone" ], "type": "string" } }, { "name": "order", "required": false, "in": "query", "description": "Sort direction. Defaults to `DESC`.", "examples": { "ASC": { "value": "ASC", "summary": "Ascending" }, "DESC": { "value": "DESC", "summary": "Descending (default)" } }, "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } }, { "name": "dateProperty", "required": false, "in": "query", "description": "The client date field to apply the date filter to. Must be combined with `dateOperator` and `date`.", "schema": { "enum": [ "created" ], "type": "string" } }, { "name": "dateOperator", "required": false, "in": "query", "description": "Comparison operator for the date filter. Must be combined with `dateProperty` and `date`.", "examples": { "prev": { "value": "prev", "summary": "On or before the given date" }, "next": { "value": "next", "summary": "On or after the given date" }, "between": { "value": "between", "summary": "Between two dates (maximum range: 1 year)" } }, "schema": { "enum": [ "prev", "next", "between" ], "type": "string" } }, { "name": "date", "required": false, "in": "query", "description": "Date value(s) for the filter. Format depends on `dateOperator`: `prev` / `next` accept a single date (`YYYY-MM-DD`); `between` accepts two dates separated by `_` (`YYYY-MM-DD_YYYY-MM-DD`).", "examples": { "prev": { "value": "2025-01-13", "description": "prev: Filter clients by dateProperty before date" }, "next": { "value": "2025-01-13", "description": "next: Filter clients by dateProperty after date" }, "between": { "value": "2025-01-13_2025-01-14", "description": "between: Filter clients by dateProperty between dates max 1 year" } }, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "Paginated list of clients.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseClientsV2Dto" } } } }, "400": { "description": "Invalid query parameters (e.g. unresolvable tag ID, malformed date range)." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "One or more of the provided tag IDs was not found." } }, "summary": "Retrieve a list of Clients", "tags": [ "Clients" ] }, "post": { "description": "> **Beta:** This endpoint is subject to change and may contain bugs. Breaking changes may occur without notice.\n\nCreates a new client and returns the created client object. Either `email` or `primaryPhone` must be provided. The client's service location is created from `addressDetails`. Optionally accepts a billing address, an ad group, a parent client, tax exemption details, and custom field values.", "operationId": "create", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": true, "description": "The Client data to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClientV2Dto" } } } }, "responses": { "201": { "description": "The created client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseClientV2Dto" } } } }, "400": { "description": "Validation error (e.g. both email and primaryPhone are missing, or invalid custom field values)." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "The provided ad group ID or parent client ID was not found." } }, "summary": "Create a new Client", "tags": [ "Clients" ], "x-badges": [ { "name": "Beta", "position": "after", "color": "purple" } ] } }, "/v2/clients/{id}": { "get": { "description": "Returns a single client including full contact details, service and billing addresses, tags, ad group, notes, additional contacts, and custom field values.", "operationId": "findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The client ID (prefix `CL-`).", "schema": { "example": "CL-OvmDp2yvv1yqMwRl", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "The requested client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseClientV2Dto" } } } }, "400": { "description": "The provided ID is not a valid client ID." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "No client with the given ID exists for this account." } }, "summary": "Get a client by ID", "tags": [ "Clients" ] } }, "/v2/clients/{clientId}/notes": { "get": { "description": "Returns a paginated list of notes for the given client, ordered by creation date descending.", "operationId": "findAll", "parameters": [ { "name": "clientId", "required": true, "in": "path", "description": "The client ID (prefix `CL-`).", "schema": { "example": "CL-OvmDp2yvv1yqMwRl", "type": "string" } }, { "name": "pageSize", "required": false, "in": "query", "description": "Number of records to return per page.", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "The page index.", "schema": { "example": 1, "type": "number" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "Paginated list of client notes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseClientNotesV2Dto" } } } }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "No client with the given ID exists for this account." } }, "summary": "Retrieve a list of Client Notes", "tags": [ "Client Notes" ] }, "post": { "description": "Creates a new note for the given client.", "operationId": "create", "parameters": [ { "name": "clientId", "required": true, "in": "path", "description": "The client ID (prefix `CL-`).", "schema": { "example": "CL-OvmDp2yvv1yqMwRl", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": true, "description": "The Client Note data to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClientNoteV2Dto" } } } }, "responses": { "201": { "description": "The created client note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseClientNoteV2Dto" } } } }, "400": { "description": "Validation error (e.g. missing note content)." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "No client with the given ID exists for this account." } }, "summary": "Create a new Client Note", "tags": [ "Client Notes" ] } }, "/v2/clients/{clientId}/notes/{noteId}": { "get": { "description": "Returns a single note belonging to the given client.", "operationId": "findOne", "parameters": [ { "name": "clientId", "required": true, "in": "path", "description": "The client ID (prefix `CL-`).", "schema": { "example": "CL-OvmDp2yvv1yqMwRl", "type": "string" } }, { "name": "noteId", "required": true, "in": "path", "description": "The client note ID (prefix `CLN-`).", "schema": { "example": "CLN-211d1676f4b90c40", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "The requested client note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseClientNoteV2Dto" } } } }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "No client or note with the given ID exists for this account." } }, "summary": "Get a client note by ID", "tags": [ "Client Notes" ] }, "put": { "description": "Updates the content and/or pinned state of a note belonging to the given client.", "operationId": "update", "parameters": [ { "name": "clientId", "required": true, "in": "path", "description": "The client ID (prefix `CL-`).", "schema": { "example": "CL-OvmDp2yvv1yqMwRl", "type": "string" } }, { "name": "noteId", "required": true, "in": "path", "description": "The client note ID (prefix `CLN-`).", "schema": { "example": "CLN-211d1676f4b90c40", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": true, "description": "The Client Note fields to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClientNoteV2Dto" } } } }, "responses": { "200": { "description": "The updated client note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseClientNoteV2Dto" } } } }, "400": { "description": "Validation error." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "No client or note with the given ID exists for this account." } }, "summary": "Update a Client Note", "tags": [ "Client Notes" ] }, "delete": { "description": "Deletes a note belonging to the given client.", "operationId": "delete", "parameters": [ { "name": "clientId", "required": true, "in": "path", "description": "The client ID (prefix `CL-`).", "schema": { "example": "CL-OvmDp2yvv1yqMwRl", "type": "string" } }, { "name": "noteId", "required": true, "in": "path", "description": "The client note ID (prefix `CLN-`).", "schema": { "example": "CLN-211d1676f4b90c40", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "204": { "description": "The client note was deleted." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "No client or note with the given ID exists for this account." } }, "summary": "Delete a Client Note", "tags": [ "Client Notes" ] } }, "/v2/tags": { "get": { "description": "Retrieves a paginated list of Tags.", "operationId": "findAll", "parameters": [ { "name": "pageSize", "required": false, "in": "query", "description": "Number of records to return per page.", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "The page index.", "schema": { "example": 1, "type": "number" } }, { "name": "type", "required": false, "in": "query", "description": "Filter tags by type.", "examples": { "job": { "value": "job", "description": "Only job tags" }, "client": { "value": "client", "description": "Only client tags" }, "call": { "value": "call", "description": "Only call tags" } }, "schema": { "enum": [ "job", "client", "call", "task", "project" ], "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A paginated list of Tags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseTagsV2Dto" } } } }, "400": { "description": "Invalid query parameters." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Retrieve a list of Tags", "tags": [ "Tags" ] }, "post": { "description": "Creates a new Tag and returns the created Tag object.", "operationId": "create", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": true, "description": "The Tag data to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTagV2Dto" } } } }, "responses": { "201": { "description": "The created Tag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseTagV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Create a new Tag", "tags": [ "Tags" ] } }, "/v2/tags/{id}": { "put": { "description": "Updates an existing Tag and returns the updated Tag.", "operationId": "update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The tag ID (prefix `TAG-`).", "schema": { "example": "TAG-16a94b03317f6e64", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": false, "description": "The Tag fields to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTagV2Dto" } } } }, "responses": { "200": { "description": "The updated Tag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseTagV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Tag not found." } }, "summary": "Update an existing Tag", "tags": [ "Tags" ] }, "delete": { "description": "Deletes a Tag by its ID.", "operationId": "delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The tag ID (prefix `TAG-`).", "schema": { "example": "TAG-16a94b03317f6e64", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "204": { "description": "Tag deleted successfully." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Tag not found." } }, "summary": "Delete a Tag", "tags": [ "Tags" ] } }, "/v2/jobs": { "get": { "description": "Retrieves a paginated list of Jobs, optionally filtered by date range.", "operationId": "findAll", "parameters": [ { "name": "pageSize", "required": false, "in": "query", "description": "Number of records to return per page.", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "The page index.", "schema": { "example": 1, "type": "number" } }, { "name": "field", "required": false, "in": "query", "description": "The field to sort results by. Must be combined with `order`.", "schema": { "enum": [ "created", "updated", "statusUpdated", "utcUpdated" ], "type": "string" } }, { "name": "order", "required": false, "in": "query", "description": "The sort direction. Must be combined with `field`.", "examples": { "ASC": { "value": "ASC", "description": "Ascending order" }, "DESC": { "value": "DESC", "description": "Descending order" } }, "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } }, { "name": "isOpen", "required": false, "in": "query", "description": "When true, returns only open jobs.", "schema": { "default": false, "example": true, "type": "boolean" } }, { "name": "dateProperty", "required": false, "in": "query", "description": "The job date field to apply the date filter to. Must be combined with `dateOperator` and `date`.", "schema": { "enum": [ "date", "endDate", "utcUpdated", "created" ], "type": "string" } }, { "name": "dateOperator", "required": false, "in": "query", "description": "Comparison operator for the date filter. Must be combined with `dateProperty` and `date`.", "examples": { "prev": { "value": "prev", "description": "On or before the given date" }, "next": { "value": "next", "description": "On or after the given date" }, "between": { "value": "between", "description": "Between two dates (maximum range: 1 year)" } }, "schema": { "enum": [ "prev", "next", "between" ], "type": "string" } }, { "name": "date", "required": false, "in": "query", "description": "Date value(s) for the filter. Format depends on `dateOperator`: `prev` / `next` accept a single date (`YYYY-MM-DD`); `between` accepts two dates separated by `_` (`YYYY-MM-DD_YYYY-MM-DD`).", "examples": { "prev": { "value": "2025-01-13", "description": "prev: Filter jobs before date" }, "next": { "value": "2025-01-13", "description": "next: Filter jobs after date" }, "between": { "value": "2025-01-13_2025-01-14", "description": "between: Filter jobs between dates (max 1 year)" } }, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A paginated list of Jobs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseJobsV2Dto" } } } }, "400": { "description": "Invalid query parameters." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Retrieve a list of Jobs", "tags": [ "Jobs" ] }, "post": { "description": "Creates a new Job and returns the created Job object.\n\n**Client Matching & Creation Logic:**\n\n1. **If `clientInfo.clientId` is provided:**\n - The job will be associated with that existing client\n - The existing client's data will be used as defaults for any missing information\n\n2. **If `clientInfo.clientId` is NOT provided:**\n - The system **first attempts to locate an existing client** by matching:\n - Full name (firstName + lastName)\n - Primary phone\n - Email address\n - Company name\n - Address\n - If a matching client is found, that client will be used for the job\n - If NO matching client is found, a new client will be created using the provided information\n \n When creating a new client, the following fields in `clientInfo` become **required**:\n - `firstName`: Client's first name\n - `email` or `primaryPhone`: At least one contact method (email must be valid when provided)\n - `addressDetails`: Complete address information (country, state, city, zipCode, address)\n\n**Property/Address Logic:**\n\n - If a `clientId` exists, the system **first attempts to find a matching property** for that client by comparing the provided address details\n - If a matching property is found on the client, that property will be used\n - If NO matching property is found, a new property will be created using the address details from `clientInfo.addressDetails`\n - When creating a new property, all address fields (country, state, city, zipCode, address) must be provided\n\n**Summary:** The system intelligently matches existing clients and properties before creating new ones, ensuring data consistency and avoiding duplicates.", "operationId": "create", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": true, "description": "The Job data to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobV2Dto" } } } }, "responses": { "201": { "description": "The created Job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseOneJobV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Create a new Job", "tags": [ "Jobs" ] } }, "/v2/jobs/{id}": { "get": { "description": "Retrieves a single Job by its ID.", "operationId": "findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The job ID (prefix `JOB-`).", "schema": { "example": "JOB-BA5r7o4bqzR9MONa", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "The requested Job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseOneJobV2Dto" } } } }, "400": { "description": "The provided ID is not a valid job ID." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Job not found." } }, "summary": "Retrieve a single Job", "tags": [ "Jobs" ] }, "put": { "description": "Updates an existing Job and returns the updated Job.", "operationId": "update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The job ID (prefix `JOB-`).", "schema": { "example": "JOB-BA5r7o4bqzR9MONa", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": false, "description": "The Job fields to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateJobV2Dto" } } } }, "responses": { "200": { "description": "The updated Job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseOneJobV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Job not found." } }, "summary": "Update an existing Job", "tags": [ "Jobs" ] } }, "/v2/leads": { "get": { "description": "Retrieves a paginated list of Leads, optionally filtered by date range.", "operationId": "findAll", "parameters": [ { "name": "pageSize", "required": false, "in": "query", "description": "Number of records to return per page.", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "The page index.", "schema": { "example": 1, "type": "number" } }, { "name": "field", "required": false, "in": "query", "description": "The field to sort results by. Must be combined with `order`.", "schema": { "enum": [ "created", "updated", "statusUpdated", "utcUpdated" ], "type": "string" } }, { "name": "order", "required": false, "in": "query", "description": "The sort direction. Must be combined with `field`.", "examples": { "ASC": { "value": "ASC", "description": "Ascending order" }, "DESC": { "value": "DESC", "description": "Descending order" } }, "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } }, { "name": "isOpen", "required": false, "in": "query", "description": "When true, returns only open leads.", "schema": { "default": false, "example": true, "type": "boolean" } }, { "name": "dateProperty", "required": false, "in": "query", "description": "The lead date field to apply the date filter to. Must be combined with `dateOperator` and `date`.", "schema": { "enum": [ "date", "endDate", "utcUpdated", "created" ], "type": "string" } }, { "name": "dateOperator", "required": false, "in": "query", "description": "Comparison operator for the date filter. Must be combined with `dateProperty` and `date`.", "examples": { "prev": { "value": "prev", "description": "On or before the given date" }, "next": { "value": "next", "description": "On or after the given date" }, "between": { "value": "between", "description": "Between two dates (maximum range: 1 year)" } }, "schema": { "enum": [ "prev", "next", "between" ], "type": "string" } }, { "name": "date", "required": false, "in": "query", "description": "Date value(s) for the filter. Format depends on `dateOperator`: `prev` / `next` accept a single date (`YYYY-MM-DD`); `between` accepts two dates separated by `_` (`YYYY-MM-DD_YYYY-MM-DD`).", "examples": { "prev": { "value": "2025-01-13", "description": "prev: Filter leads before date" }, "next": { "value": "2025-01-13", "description": "next: Filter leads after date" }, "between": { "value": "2025-01-13_2025-01-14", "description": "between: Filter leads between dates (max 1 year)" } }, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A paginated list of Leads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseLeadsV2Dto" } } } }, "400": { "description": "Invalid query parameters." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Retrieve a list of Leads", "tags": [ "Leads" ] }, "post": { "description": "Creates a new Lead and returns the created Lead object.\n\n**Client Matching & Creation Logic:**\n\n1. **If `clientInfo.clientId` is provided:**\n - The lead will be associated with that existing client\n - The existing client's data will be used as defaults for any missing information\n\n2. **If `clientInfo.clientId` is NOT provided:**\n - The system **first attempts to locate an existing client** by matching:\n - Full name (firstName + lastName)\n - Primary phone\n - Email address\n - Company name\n - Address\n - If a matching client is found, that client will be used for the lead\n - If NO matching client is found, a new client will be created using the provided information\n \n When creating a new client, the following fields in `clientInfo` become **required**:\n - `firstName`: Client's first name\n - `email` or `primaryPhone`: At least one contact method (email must be valid when provided)\n - `addressDetails`: Complete address information (country, state, city, zipCode, address)\n\n**Property/Address Logic:**\n\n - If a `clientId` exists the system **first attempts to find a matching property** for that client by comparing the provided address details\n - If a matching property is found on the client, that property will be used\n - If NO matching property is found, a new property will be created using the address details from `clientInfo.addressDetails`\n - When creating a new property, all address fields (country, state, city, zipCode, address) must be provided\n\n**Summary:** The system intelligently matches existing clients and properties before creating new ones, ensuring data consistency and avoiding duplicates.", "operationId": "create", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": true, "description": "The Lead data to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLeadV2Dto" } } } }, "responses": { "201": { "description": "The created Lead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseLeadV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Create a new Lead", "tags": [ "Leads" ] } }, "/v2/leads/{id}": { "get": { "description": "Retrieves a single Lead by its ID.", "operationId": "findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The lead ID (prefix `LD-`).", "schema": { "example": "LD-LwqGJnRwvZPaNe5E", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "The requested Lead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseLeadV2Dto" } } } }, "400": { "description": "The provided ID is not a valid lead ID." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Lead not found." } }, "summary": "Retrieve a single Lead", "tags": [ "Leads" ] }, "put": { "description": "Updates an existing Lead and returns the updated Lead.", "operationId": "update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The lead ID (prefix `LD-`).", "schema": { "example": "LD-LwqGJnRwvZPaNe5E", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": false, "description": "The Lead fields to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLeadV2Dto" } } } }, "responses": { "200": { "description": "The updated Lead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseLeadV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Lead not found." } }, "summary": "Update an existing Lead", "tags": [ "Leads" ] } }, "/v2/leads/{leadId}/convert": { "post": { "description": "Converts an existing Lead to a Job and returns the resulting Job object.", "operationId": "convert", "parameters": [ { "name": "leadId", "required": true, "in": "path", "description": "The lead ID (prefix `LD-`).", "schema": { "example": "LD-LwqGJnRwvZPaNe5E", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "The converted Job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseJobV2Dto" } } } }, "400": { "description": "Lead is missing required fields or is already converted." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Lead not found." } }, "summary": "Convert a Lead to a Job", "tags": [ "Leads" ] } }, "/v2/users": { "get": { "description": "Retrieves a paginated list of Users.", "operationId": "findAll", "parameters": [ { "name": "pageSize", "required": false, "in": "query", "description": "Number of records to return per page.", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "The page index.", "schema": { "example": 1, "type": "number" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A paginated list of Users.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseUsersV2Dto" } } } }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Retrieve a list of Users", "tags": [ "Users" ] } }, "/v2/users/{id}": { "get": { "description": "Retrieves a single User by its ID.", "operationId": "findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The user ID (prefix `USR-`).", "schema": { "example": "USR-A21Lz3rPQxkYqRNo", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "The requested User.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseUserV2Dto" } } } }, "400": { "description": "The provided ID is not a valid user ID." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "User not found." } }, "summary": "Retrieve a single User", "tags": [ "Users" ] } }, "/v2/users/{id}/jobtypes": { "post": { "description": "Adds Job Types to a User and returns the updated User object.", "operationId": "addTechJobTypes", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The user ID (prefix `USR-`).", "schema": { "example": "USR-A21Lz3rPQxkYqRNo", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": true, "description": "The Job Type IDs to add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeleteUserJobTypeV2Dto" } } } }, "responses": { "201": { "description": "The updated User.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseUserV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "User not found." } }, "summary": "Add Job Types to a User", "tags": [ "Users" ] }, "delete": { "description": "Removes Job Types from a User.", "operationId": "removeTechJobTypes", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The user ID (prefix `USR-`).", "schema": { "example": "USR-A21Lz3rPQxkYqRNo", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": true, "description": "The Job Type IDs to remove.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeleteUserJobTypeV2Dto" } } } }, "responses": { "204": { "description": "Job Types removed successfully." }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "User not found." } }, "summary": "Remove Job Types from a User", "tags": [ "Users" ] } }, "/v2/leadstatus": { "get": { "description": "Retrieves a list of Lead Statuses.", "operationId": "findAll", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A list of Lead Statuses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseLeadStatusesV2Dto" } } } }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Retrieve a list of Lead Statuses", "tags": [ "Lead Status" ] }, "post": { "description": "Creates a new Lead Status and returns the created Lead Status.", "operationId": "create", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": true, "description": "The Lead Status data to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLeadStatusV2Dto" } } } }, "responses": { "201": { "description": "The created Lead Status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseLeadStatusV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Create a new Lead Status", "tags": [ "Lead Status" ] }, "delete": { "description": "Deletes a Lead Status by its name.", "operationId": "delete", "parameters": [ { "name": "name", "required": true, "in": "query", "description": "The name of the Lead Status to delete.", "schema": { "example": "Submitted", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "204": { "description": "Lead Status deleted successfully." }, "400": { "description": "The status still has leads assigned to it." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Lead Status not found." } }, "summary": "Delete a Lead Status", "tags": [ "Lead Status" ] } }, "/v2/invoices": { "get": { "description": "Retrieves a paginated list of Invoices, optionally filtered by date range.", "operationId": "findAll", "parameters": [ { "name": "pageSize", "required": false, "in": "query", "description": "Number of records to return per page.", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "The page index.", "schema": { "example": 1, "type": "number" } }, { "name": "dateProperty", "required": false, "in": "query", "description": "The invoice date field to apply the date filter to. Must be combined with `dateOperator` and `date`.", "schema": { "enum": [ "updated", "created" ], "type": "string" } }, { "name": "dateOperator", "required": false, "in": "query", "description": "Comparison operator for the date filter. Must be combined with `dateProperty` and `date`.", "examples": { "prev": { "value": "prev", "description": "On or before the given date" }, "next": { "value": "next", "description": "On or after the given date" }, "between": { "value": "between", "description": "Between two dates (maximum range: 1 year)" } }, "schema": { "enum": [ "prev", "next", "between" ], "type": "string" } }, { "name": "date", "required": false, "in": "query", "description": "Date value(s) for the filter. Format depends on `dateOperator`: `prev` / `next` accept a single date (`YYYY-MM-DD`); `between` accepts two dates separated by `_` (`YYYY-MM-DD_YYYY-MM-DD`).", "examples": { "prev": { "value": "2025-01-13", "description": "prev: Filter invoices before date" }, "next": { "value": "2025-01-13", "description": "next: Filter invoices after date" }, "between": { "value": "2025-01-13_2025-01-14", "description": "between: Filter invoices between dates (max 1 year)" } }, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A paginated list of Invoices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseInvoicesV2Dto" } } } }, "400": { "description": "Invalid query parameters." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Retrieve a list of Invoices", "tags": [ "Invoices" ] } }, "/v2/invoices/{id}": { "get": { "description": "Retrieves a single Invoice by its ID.", "operationId": "findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The invoice ID (prefix `IV-`).", "schema": { "example": "IV-LwqGJnRwvZPaNe5E", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "The requested Invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseInvoiceV2Dto" } } } }, "400": { "description": "The provided ID is not a valid invoice ID." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Invoice not found." } }, "summary": "Retrieve a single Invoice", "tags": [ "Invoices" ] } }, "/v2/timeSheet": { "get": { "description": "Retrieves a paginated list of Time Sheets based on the applied filters and pagination.", "operationId": "findAll", "parameters": [ { "name": "pageSize", "required": false, "in": "query", "description": "Number of records to return per page.", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "The page index.", "schema": { "example": 1, "type": "number" } }, { "name": "techId", "required": false, "in": "query", "description": "Filter by tech ID (prefix `USR-`).", "schema": { "example": "USR-81ce48127c24fd23", "type": "string" } }, { "name": "jobId", "required": false, "in": "query", "description": "Filter by job ID (prefix `JOB-`).", "schema": { "example": "JOB-BA5r7o4bqzR9MONa", "type": "string" } }, { "name": "dateQuery", "required": false, "in": "query", "description": "Filter by start date range in the format `YYYY-MM-DD_YYYY-MM-DD`.", "schema": { "example": "2025-01-01_2025-12-31", "type": "string" } }, { "name": "withJob", "required": false, "in": "query", "description": "When true, only returns shifts associated with a job. Ignored if `jobId` is provided.", "examples": { "true": { "value": true, "description": "With job" }, "false": { "value": false, "description": "Without job" } }, "schema": { "type": "boolean" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A paginated list of Time Sheets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseTimesheetsV2Dto" } } } }, "400": { "description": "Invalid query parameters." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Retrieve a list of Time Sheets", "tags": [ "TimeSheets" ] }, "post": { "description": "Creates a new Time Sheet and returns the created Time Sheet object.", "operationId": "create", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": true, "description": "The Time Sheet data to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTimesheetV2DTO" } } } }, "responses": { "201": { "description": "The created Time Sheet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseTimesheetV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Create a new Time Sheet", "tags": [ "TimeSheets" ] } }, "/v2/timeSheet/{id}": { "get": { "description": "Retrieves a single Time Sheet by its ID.", "operationId": "findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The time sheet ID (prefix `TS-`).", "schema": { "example": "TS-f4e29a5a3f8a01a6", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "The requested Time Sheet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseTimesheetV2Dto" } } } }, "400": { "description": "The provided ID is not a valid time sheet ID." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Time Sheet not found." } }, "summary": "Retrieve a single Time Sheet", "tags": [ "TimeSheets" ] }, "put": { "description": "Updates an existing Time Sheet and returns the updated Time Sheet.", "operationId": "update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The time sheet ID (prefix `TS-`).", "schema": { "example": "TS-f4e29a5a3f8a01a6", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": false, "description": "The Time Sheet fields to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTimesheetV2Dto" } } } }, "responses": { "200": { "description": "The updated Time Sheet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseTimesheetV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Time Sheet not found." } }, "summary": "Update an existing Time Sheet", "tags": [ "TimeSheets" ] }, "delete": { "description": "Deletes a Time Sheet by its ID.", "operationId": "delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The time sheet ID (prefix `TS-`).", "schema": { "example": "TS-f4e29a5a3f8a01a6", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "204": { "description": "Time Sheet deleted successfully." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Delete a Time Sheet", "tags": [ "TimeSheets" ] } }, "/v2/search": { "get": { "description": "Returns a list of matching results across entity types based on the provided search term.\n\nBy default, results are returned from all entity types (jobs, leads, clients, invoices) up to the specified `limit` per type.\n\nUse the `type` parameter to restrict results to a single entity type. Requesting `type=lead` requires the Leads add-on to be enabled on the account.\n\nResults are ranked by relevance score. The `entityId` field is an ID that can be used with other API endpoints.", "operationId": "searchAll", "parameters": [ { "name": "term", "required": true, "in": "query", "description": "Search term matched against name, phone, email, address, serial numbers, and custom fields across entity types.", "schema": { "example": "john doe", "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Restrict results to a single entity type. Omit to search across all types.\n\n- `job` — returns only jobs (excludes leads)\n- `lead` — returns only leads (requires Leads add-on)\n- `client` — returns only clients\n- `invoice` — returns only invoices", "schema": { "type": "string", "enum": [ "job", "lead", "client", "invoice" ] } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of results to return per entity type. Defaults to 5, maximum 15.", "schema": { "default": 5, "example": 5, "type": "number" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "Search results grouped with total count and result list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseSearchResultsV2Dto" } } } }, "400": { "description": "Invalid query parameters, or `type=lead` requested without the Leads add-on enabled." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Search across multiple entity types", "tags": [ "Search" ] } }, "/v2/jobSubStatus": { "get": { "description": "Retrieves a paginated list of Job Sub Statuses.", "operationId": "findAll", "parameters": [ { "name": "pageSize", "required": false, "in": "query", "description": "Number of records to return per page.", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "The page index.", "schema": { "example": 1, "type": "number" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A paginated list of Job Sub Statuses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseJobSubStatusesV2Dto" } } } }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Retrieve a list of Job Sub Statuses", "tags": [ "Job Sub Status" ] }, "post": { "description": "Creates a new Job Sub Status and returns the created Job Sub Status object.", "operationId": "create", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": true, "description": "The Job Sub Status data to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobSubStatusV2Dto" } } } }, "responses": { "201": { "description": "The created Job Sub Status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseJobSubStatusV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Create a new Job Sub Status", "tags": [ "Job Sub Status" ] } }, "/v2/jobSubStatus/{id}": { "get": { "description": "Retrieves a single Job Sub Status by its ID.", "operationId": "findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The job sub status ID (prefix `JSS-`).", "schema": { "example": "JSS-BA5r7o4bqzR9MONa", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "The requested Job Sub Status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseJobSubStatusV2Dto" } } } }, "400": { "description": "The provided ID is not a valid job sub status ID." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Job Sub Status not found." } }, "summary": "Retrieve a single Job Sub Status", "tags": [ "Job Sub Status" ] }, "put": { "description": "Updates an existing Job Sub Status and returns the updated Job Sub Status.", "operationId": "update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The job sub status ID (prefix `JSS-`).", "schema": { "example": "JSS-BA5r7o4bqzR9MONa", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": false, "description": "The Job Sub Status fields to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateJobSubStatusV2Dto" } } } }, "responses": { "200": { "description": "The updated Job Sub Status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseJobSubStatusV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Job Sub Status not found." } }, "summary": "Update an existing Job Sub Status", "tags": [ "Job Sub Status" ] }, "delete": { "description": "Deletes a Job Sub Status by its ID.", "operationId": "delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The job sub status ID (prefix `JSS-`).", "schema": { "example": "JSS-BA5r7o4bqzR9MONa", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "204": { "description": "Job Sub Status deleted successfully." }, "400": { "description": "The status still has sub statuses assigned to it." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Job Sub Status not found." } }, "summary": "Delete a Job Sub Status", "tags": [ "Job Sub Status" ] } }, "/v2/jobs/{jobId}/team": { "get": { "description": "Retrieves a paginated list of technicians assigned to a job.", "operationId": "findAllJobTechnitions", "parameters": [ { "name": "jobId", "required": true, "in": "path", "description": "The Job ID", "schema": { "example": "JOB-BA5r7o4bqzR9MONa", "type": "string" } }, { "name": "pageSize", "required": false, "in": "query", "description": "The page size", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "The page number", "schema": { "example": 1, "type": "number" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A paginated list of job technicians", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseJobTechnitionsV2Dto" } } } }, "404": { "description": "Job not found" } }, "summary": "Retrieve a list of Job Technicians", "tags": [ "Jobs" ] }, "post": { "description": "Assigns a technician to a job. If the account does not have multi-technician enabled, use `replace: true` to replace the existing technician.", "operationId": "createJobTechnition", "parameters": [ { "name": "jobId", "required": true, "in": "path", "description": "The Job ID", "schema": { "example": "JOB-BA5r7o4bqzR9MONa", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobLeadTechnitionV2Dto" } } } }, "responses": { "201": { "description": "The assigned technician", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseJobLeadTechnitionV2Dto" } } } }, "400": { "description": "Invalid input" }, "404": { "description": "Job or user not found" } }, "summary": "Assign a Technician to a Job", "tags": [ "Jobs" ] } }, "/v2/jobs/{jobId}/team/{userId}": { "put": { "description": "Sets the specified technician as the primary technician for the job. All other technicians will be set as non-primary.", "operationId": "setPrimaryJobTechnition", "parameters": [ { "name": "jobId", "required": true, "in": "path", "description": "The Job ID", "schema": { "example": "JOB-BA5r7o4bqzR9MONa", "type": "string" } }, { "name": "userId", "required": true, "in": "path", "description": "The User ID", "schema": { "example": "USR-BA5r7o4bqzR9MONa", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "The updated technician with isPrimary set to true", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseJobLeadTechnitionV2Dto" } } } }, "404": { "description": "Job not found" } }, "summary": "Set a Technician as Primary", "tags": [ "Jobs" ] }, "delete": { "description": "Removes the specified technician from the job.", "operationId": "removeJobTechnition", "parameters": [ { "name": "jobId", "required": true, "in": "path", "description": "The Job ID", "schema": { "example": "JOB-BA5r7o4bqzR9MONa", "type": "string" } }, { "name": "userId", "required": true, "in": "path", "description": "The User ID", "schema": { "example": "USR-BA5r7o4bqzR9MONa", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "204": { "description": "Technician unassigned successfully" }, "400": { "description": "Job is closed" }, "404": { "description": "Job or technician assignment not found" } }, "summary": "Unassign a Technician from a Job", "tags": [ "Jobs" ] } }, "/v2/leads/{leadId}/team": { "get": { "description": "Retrieves a paginated list of technicians assigned to a lead.", "operationId": "findAllLeadTechnitions", "parameters": [ { "name": "leadId", "required": true, "in": "path", "description": "The Lead ID", "schema": { "example": "LD-BA5r7o4bqzR9MONa", "type": "string" } }, { "name": "pageSize", "required": false, "in": "query", "description": "The page size", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "The page number", "schema": { "example": 1, "type": "number" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A paginated list of lead technicians", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseLeadTechnitionsV2Dto" } } } }, "404": { "description": "Lead not found" } }, "summary": "Retrieve a list of Lead Technicians", "tags": [ "Leads" ] }, "post": { "description": "Assigns a technician to a lead. If the account does not have multi-technician enabled, use `replace: true` to replace the existing technician.", "operationId": "createLeadTechnition", "parameters": [ { "name": "leadId", "required": true, "in": "path", "description": "The Lead ID", "schema": { "example": "LD-BA5r7o4bqzR9MONa", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobLeadTechnitionV2Dto" } } } }, "responses": { "201": { "description": "The assigned technician", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseJobLeadTechnitionV2Dto" } } } }, "400": { "description": "Invalid input" }, "404": { "description": "Lead or user not found" } }, "summary": "Assign a Technician to a Lead", "tags": [ "Leads" ] } }, "/v2/leads/{leadId}/team/{userId}": { "put": { "description": "Sets the specified technician as the primary technician for the lead. All other technicians will be set as non-primary.", "operationId": "setPrimaryLeadTechnition", "parameters": [ { "name": "leadId", "required": true, "in": "path", "description": "The Lead ID", "schema": { "example": "LD-BA5r7o4bqzR9MONa", "type": "string" } }, { "name": "userId", "required": true, "in": "path", "description": "The User ID", "schema": { "example": "USR-BA5r7o4bqzR9MONa", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "The updated technician with isPrimary set to true", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseJobLeadTechnitionV2Dto" } } } }, "404": { "description": "Lead not found" } }, "summary": "Set a Technician as Primary", "tags": [ "Leads" ] }, "delete": { "description": "Removes the specified technician from the lead.", "operationId": "removeLeadTechnition", "parameters": [ { "name": "leadId", "required": true, "in": "path", "description": "The Lead ID", "schema": { "example": "LD-BA5r7o4bqzR9MONa", "type": "string" } }, { "name": "userId", "required": true, "in": "path", "description": "The User ID", "schema": { "example": "USR-BA5r7o4bqzR9MONa", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "204": { "description": "Technician unassigned successfully" }, "404": { "description": "Lead or technician assignment not found" } }, "summary": "Unassign a Technician from a Lead", "tags": [ "Leads" ] } }, "/v2/customfields": { "get": { "description": "Retrieves a paginated list of Custom Fields, optionally filtered by entity type.", "operationId": "findAll", "parameters": [ { "name": "pageSize", "required": false, "in": "query", "description": "Number of records to return per page.", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "The page index.", "schema": { "example": 1, "type": "number" } }, { "name": "entityType", "required": false, "in": "query", "description": "Filter results by the entity the custom field belongs to.", "schema": { "enum": [ "JOB", "CLIENT" ], "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A paginated list of Custom Fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseCustomFieldsV2Dto" } } } }, "400": { "description": "Invalid query parameters." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Retrieve a list of Custom Fields", "tags": [ "Custom Fields" ] }, "post": { "description": "Creates a new Custom Field and returns the created Custom Field.", "operationId": "create", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": true, "description": "The Custom Field data to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomFieldV2Dto" } } } }, "responses": { "201": { "description": "The created Custom Field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseCustomFieldV2Dto" } } } }, "400": { "description": "Invalid input (e.g. unsupported type, options provided for a non-select field, searchable flag on a non-searchable type, or the field limit has been reached)." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Create a new Custom Field", "tags": [ "Custom Fields" ] } }, "/v2/customfields/{id}": { "get": { "description": "Retrieves a single Custom Field by its ID.", "operationId": "findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The custom field ID (prefix `CF-`).", "schema": { "example": "CF-eYLPK7198xVp6Z8q", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "The requested Custom Field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseCustomFieldV2Dto" } } } }, "400": { "description": "The provided ID is not a valid custom field ID." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Custom Field not found." } }, "summary": "Retrieve a single Custom Field", "tags": [ "Custom Fields" ] }, "put": { "description": "Updates an existing Custom Field and returns the updated object.", "operationId": "update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The custom field ID (prefix `CF-`).", "schema": { "example": "CF-eYLPK7198xVp6Z8q", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": false, "description": "The Custom Field fields to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomFieldV2Dto" } } } }, "responses": { "200": { "description": "The updated Custom Field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseCustomFieldV2Dto" } } } }, "400": { "description": "Invalid input." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Custom Field not found." } }, "summary": "Update an existing Custom Field", "tags": [ "Custom Fields" ] }, "delete": { "description": "Deletes a Custom Field by its ID.", "operationId": "delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The custom field ID (prefix `CF-`).", "schema": { "example": "CF-eYLPK7198xVp6Z8q", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "204": { "description": "Custom Field deleted successfully." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Custom Field not found." } }, "summary": "Delete a Custom Field", "tags": [ "Custom Fields" ] } }, "/v2/customfieldsgroups": { "get": { "description": "Retrieves a paginated list of Custom Fields Groups, optionally filtered by entity type.", "operationId": "findAll", "parameters": [ { "name": "pageSize", "required": false, "in": "query", "description": "Number of records to return per page.", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "The page index.", "schema": { "example": 1, "type": "number" } }, { "name": "entityType", "required": false, "in": "query", "description": "Filter results by the entity the custom fields group belongs to.", "schema": { "enum": [ "JOB", "CLIENT" ], "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A paginated list of Custom Fields Groups.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseCustomFieldsGroupsV2Dto" } } } }, "400": { "description": "Invalid query parameters." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Retrieve a list of Custom Fields Groups", "tags": [ "Custom Fields Groups" ] }, "post": { "description": "Creates a new Custom Fields Group and returns the created Custom Fields Group.", "operationId": "create", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": true, "description": "The Custom Fields Group data to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomFieldsGroupV2Dto" } } } }, "responses": { "201": { "description": "The created Custom Fields Group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseCustomFieldsGroupV2Dto" } } } }, "400": { "description": "Invalid input (e.g. a group with the same name already exists)." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Create a new Custom Fields Group", "tags": [ "Custom Fields Groups" ] } }, "/v2/customfieldsgroups/{id}": { "get": { "description": "Retrieves a single Custom Fields Group by its ID.", "operationId": "findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The custom fields group ID (prefix `CFG-`).", "schema": { "example": "CFG-eYLPK7198xVp6Z8q", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "The requested Custom Fields Group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseCustomFieldsGroupV2Dto" } } } }, "400": { "description": "The provided ID is not a valid custom fields group ID." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Custom Fields Group not found." } }, "summary": "Retrieve a single Custom Fields Group", "tags": [ "Custom Fields Groups" ] }, "put": { "description": "Updates an existing Custom Fields Group and returns the updated Custom Fields Group.", "operationId": "update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The custom fields group ID (prefix `CFG-`).", "schema": { "example": "CFG-eYLPK7198xVp6Z8q", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "requestBody": { "required": false, "description": "The Custom Fields Group fields to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomFieldsGroupV2Dto" } } } }, "responses": { "200": { "description": "The updated Custom Fields Group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseCustomFieldsGroupV2Dto" } } } }, "400": { "description": "Invalid input (e.g. a group with the same name already exists)." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Custom Fields Group not found." } }, "summary": "Update an existing Custom Fields Group", "tags": [ "Custom Fields Groups" ] }, "delete": { "description": "Deletes a Custom Fields Group by its ID.", "operationId": "delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The custom fields group ID (prefix `CFG-`).", "schema": { "example": "CFG-eYLPK7198xVp6Z8q", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "204": { "description": "Custom Fields Group deleted successfully." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Custom Fields Group not found." } }, "summary": "Delete a Custom Fields Group", "tags": [ "Custom Fields Groups" ] } }, "/v2/availability": { "get": { "description": "> **Beta:** This endpoint is subject to change and may contain bugs. Breaking changes may occur without notice.\n\nReturns the list of available booking slots for the account within the requested date range.\n\nOnly slots that still have open capacity are returned, so a day with no returned slots is fully booked or unavailable.\n\nEach slot includes a `userIds` array containing the IDs of users who are already occupying capacity in that slot.\n\nUse `jobTypes` to restrict availability to the technicians who can perform those job types, and `availableBased`/`totalSpots`/`scheduleOffset`/`showHolidays` to override account booking settings for the request without changing them.\n\nThe range cannot exceed 60 days.", "operationId": "getAvailability", "parameters": [ { "name": "startDate", "required": false, "in": "query", "description": "The first date of the range to return availability for, in `YYYY-MM-DD` format. Defaults to today when omitted.", "schema": { "example": "2026-01-15", "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "The last date of the range to return availability for, in `YYYY-MM-DD` format. Must be on or after the start date, and the range cannot exceed 60 days. Defaults to 31 days after the start date when omitted.", "schema": { "example": "2026-01-31", "type": "string" } }, { "name": "slotLength", "required": false, "in": "query", "description": "The slot length in minutes. Must be between 30 and 480 (8 hours) in steps of 30. Defaults to the account configured slot length when omitted.", "schema": { "example": 60, "type": "number" } }, { "name": "jobTypes", "required": false, "in": "query", "description": "Comma-separated list of job type IDs (prefix `JT-`). When provided, availability is restricted to the technicians who can perform any of those job types.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "availableBased", "required": false, "in": "query", "description": "Overrides the account capacity mode for this request only: `0` = no capacity limit, `1` = based on available technicians, `2` = maximum jobs per slot. Defaults to the account configured mode when omitted.", "schema": { "example": 1, "type": "number" } }, { "name": "totalSpots", "required": false, "in": "query", "description": "Overrides the total capacity per slot for this request only. Mainly useful together with `availableBased=2` to set the maximum jobs per slot without changing the account settings.", "schema": { "example": 3, "type": "number" } }, { "name": "scheduleOffset", "required": false, "in": "query", "description": "Overrides the minimum notice window in hours for this request only. Allowed values: `0` (none), `1`–`10` (hours), or `24`/`48`/`72`/`96`/`120`/`144`/`168` (1–7 days). Slots earlier than now plus this offset are excluded. Defaults to the account configured schedule offset when omitted.", "schema": { "example": 24, "type": "number" } }, { "name": "showHolidays", "required": false, "in": "query", "description": "Overrides whether public holidays block slots for this request only: `0` = ignore holidays, `1` = apply the holiday calendar. Defaults to the account configured setting when omitted.", "schema": { "example": 1, "type": "number" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A list of available booking slots.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseAvailabilitySlotsV2Dto" } } } }, "400": { "description": "Invalid query parameters." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Retrieve booking availability", "tags": [ "Availability" ], "x-badges": [ { "name": "Beta", "position": "after", "color": "purple" } ] } }, "/v2/availability/blockingEntities": { "get": { "description": "> **Beta:** This endpoint is subject to change and may contain bugs. Breaking changes may occur without notice.\n\nReturns the entities (jobs, leads, tasks, events, recurrences, time-offs) that are occupying capacity on the requested date, including fully booked slots.\n\nUse this endpoint to investigate why a specific date has reduced or no availability. Each entity includes a ID that can be used with the corresponding resource endpoint.", "operationId": "getBlockingEntities", "parameters": [ { "name": "date", "required": true, "in": "query", "description": "The date to retrieve blocking entities for, in `YYYY-MM-DD` format. Cannot be in the past.", "schema": { "example": "2026-01-15", "type": "string" } }, { "name": "slotLength", "required": false, "in": "query", "description": "The slot length in minutes. Must be between 30 and 480 (8 hours) in steps of 30. Defaults to the account configured slot length when omitted.", "schema": { "example": 60, "type": "number" } }, { "name": "jobTypes", "required": false, "in": "query", "description": "Comma-separated list of job type IDs (prefix `JT-`). When provided, availability is restricted to the technicians who can perform any of those job types.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "availableBased", "required": false, "in": "query", "description": "Overrides the account capacity mode for this request only: `0` = no capacity limit, `1` = based on available technicians, `2` = maximum jobs per slot. Defaults to the account configured mode when omitted.", "schema": { "example": 1, "type": "number" } }, { "name": "totalSpots", "required": false, "in": "query", "description": "Overrides the total capacity per slot for this request only. Mainly useful together with `availableBased=2` to set the maximum jobs per slot without changing the account settings.", "schema": { "example": 3, "type": "number" } }, { "name": "scheduleOffset", "required": false, "in": "query", "description": "Overrides the minimum notice window in hours for this request only. Allowed values: `0` (none), `1`–`10` (hours), or `24`/`48`/`72`/`96`/`120`/`144`/`168` (1–7 days). Slots earlier than now plus this offset are excluded. Defaults to the account configured schedule offset when omitted.", "schema": { "example": 24, "type": "number" } }, { "name": "showHolidays", "required": false, "in": "query", "description": "Overrides whether public holidays block slots for this request only: `0` = ignore holidays, `1` = apply the holiday calendar. Defaults to the account configured setting when omitted.", "schema": { "example": 1, "type": "number" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A list of entities blocking availability on the requested date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseBlockingEntitiesV2Dto" } } } }, "400": { "description": "Invalid query parameters." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Retrieve blocking entities for a date", "tags": [ "Availability" ], "x-badges": [ { "name": "Beta", "position": "after", "color": "purple" } ] } }, "/v2/estimates": { "get": { "description": "Retrieves a paginated list of Estimates, optionally filtered by date range.", "operationId": "findAll", "parameters": [ { "name": "pageSize", "required": false, "in": "query", "description": "Number of records to return per page.", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "The page index.", "schema": { "example": 1, "type": "number" } }, { "name": "dateProperty", "required": false, "in": "query", "description": "The estimate date field to apply the date filter to. Must be combined with `dateOperator` and `date`.", "schema": { "enum": [ "updated", "created" ], "type": "string" } }, { "name": "dateOperator", "required": false, "in": "query", "description": "Comparison operator for the date filter. Must be combined with `dateProperty` and `date`.", "examples": { "prev": { "value": "prev", "description": "On or before the given date" }, "next": { "value": "next", "description": "On or after the given date" }, "between": { "value": "between", "description": "Between two dates (maximum range: 1 year)" } }, "schema": { "enum": [ "prev", "next", "between" ], "type": "string" } }, { "name": "date", "required": false, "in": "query", "description": "Date value(s) for the filter. Format depends on `dateOperator`: `prev` / `next` accept a single date (`YYYY-MM-DD`); `between` accepts two dates separated by `_` (`YYYY-MM-DD_YYYY-MM-DD`).", "examples": { "prev": { "value": "2025-01-13", "description": "prev: Filter estimates before date" }, "next": { "value": "2025-01-13", "description": "next: Filter estimates after date" }, "between": { "value": "2025-01-13_2025-01-14", "description": "between: Filter estimates between dates (max 1 year)" } }, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "A paginated list of Estimates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseEstimatesV2Dto" } } } }, "400": { "description": "Invalid query parameters." }, "401": { "description": "Missing or invalid authentication token." } }, "summary": "Retrieve a list of Estimates", "tags": [ "Estimates" ] } }, "/v2/estimates/{id}": { "get": { "description": "Retrieves a single Estimate by its ID.", "operationId": "findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The estimate ID (prefix `ES-`).", "schema": { "example": "ES-LwqGJnRwvZPaNe5E", "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Bearer Token", "schema": { "type": "string", "example": "Bearer " }, "required": true } ], "responses": { "200": { "description": "The requested Estimate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseOneEstimateV2Dto" } } } }, "400": { "description": "The provided ID is not a valid estimate ID." }, "401": { "description": "Missing or invalid authentication token." }, "404": { "description": "Estimate not found." } }, "summary": "Retrieve a single Estimate", "tags": [ "Estimates" ] } } }, "info": { "title": "Developer API", "description": "The API is built to allow you to create a functional application or integration quickly and easily.", "version": "2.0", "contact": {}, "x-logo": { "url": "./Workiz_Logox500.png", "altText": "Workiz Logo" } }, "tags": [ { "name": "Search" }, { "name": "AdGroups" }, { "name": "Availability" }, { "name": "Client Notes" }, { "name": "Clients" }, { "name": "Custom Fields" }, { "name": "Custom Fields Groups" }, { "name": "Estimates" }, { "name": "Events" }, { "name": "Invoices" }, { "name": "Job Sub Status" }, { "name": "Jobs" }, { "name": "JobTypes" }, { "name": "Lead Status" }, { "name": "Leads" }, { "name": "Tags" }, { "name": "TimeOffs" }, { "name": "TimeSheets" }, { "name": "Users" } ], "servers": [ { "url": "https://api.workiz.com/crm/api" } ], "components": { "schemas": { "ResponseJobTypeV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the job type (prefix `JT-`).", "example": "JT-8718036049ec4c4d" }, "name": { "type": "string", "description": "The name of the job type.", "example": "Cleaning" }, "avgDuration": { "type": "number", "description": "The average duration of the job type in minutes.", "example": 60 }, "displayOrder": { "type": "number", "description": "The display order of the job type.", "example": 1 }, "disabled": { "type": "boolean", "description": "Indicates whether the job type is disabled or not.", "example": false } } }, "ResponseJobTypesV2Dto": { "type": "object", "properties": { "pageSize": { "type": "number", "description": "The maximum number of items returned per page.", "example": 10 }, "page": { "type": "number", "description": "The current page number.", "example": 1 }, "totalResults": { "type": "number", "description": "The total number of results.", "example": 50 }, "hasMore": { "type": "boolean", "description": "Whether there are more results.", "example": true }, "data": { "description": "A list of Job Types.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseJobTypeV2Dto" } } } }, "CreateJobTypeV2Dto": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the job type.", "example": "Some type" }, "avgDuration": { "type": "number", "description": "The average duration in minutes.", "example": 60 }, "displayOrder": { "type": "number", "description": "The position of the job type in the display list.", "example": 1 }, "disabled": { "type": "boolean", "description": "Indicates whether the job type is disabled or not.", "example": false }, "applyToSubAccounts": { "type": "boolean", "description": "When true, the job type is also created on all franchise sub-accounts.", "example": true } }, "required": [ "name", "displayOrder" ] }, "UpdateJobTypeV2Dto": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the job type.", "example": "Some type" }, "avgDuration": { "type": "number", "description": "The average duration in minutes.", "example": 60 }, "displayOrder": { "type": "number", "description": "The position of the job type in the display list.", "example": 1 }, "disabled": { "type": "boolean", "description": "Indicates whether the job type is disabled or not.", "example": false }, "applyToSubAccounts": { "type": "boolean", "description": "When true, the update is also applied to matching job types on all franchise sub-accounts.", "example": true } } }, "ResponseAdGroupV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the ad group (prefix `AG-`).", "example": "AG-71b8d7310acbf8cc" }, "name": { "type": "string", "description": "The name of the ad group.", "example": "Group A" }, "displayOrder": { "type": "number", "description": "The display order of the ad group.", "example": 1 }, "description": { "type": "string", "description": "The description of the ad group.", "example": "This is a sample ad group." }, "disabled": { "type": "boolean", "description": "Indicates whether the ad group is disabled or not.", "example": false } } }, "ResponseAdGroupsV2Dto": { "type": "object", "properties": { "pageSize": { "type": "number", "description": "The maximum number of items returned per page.", "example": 10 }, "page": { "type": "number", "description": "The current page number.", "example": 1 }, "totalResults": { "type": "number", "description": "The total number of results.", "example": 50 }, "hasMore": { "type": "boolean", "description": "Whether there are more results.", "example": true }, "data": { "description": "A list of Ad Groups.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseAdGroupV2Dto" } } } }, "CreateAdGroupV2Dto": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the ad group.", "example": "Group 1" }, "displayOrder": { "type": "number", "description": "The position of the ad group in the display list.", "example": 1 }, "description": { "type": "string", "description": "The description of the ad group.", "example": "This is an ad group." }, "disabled": { "type": "boolean", "description": "Indicates whether the ad group is disabled or not.", "example": false } }, "required": [ "name", "displayOrder" ] }, "UpdateAdGroupV2Dto": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the ad group.", "example": "Group 1" }, "displayOrder": { "type": "number", "description": "The position of the ad group in the display list.", "example": 1 }, "description": { "type": "string", "description": "The description of the ad group.", "example": "This is an ad group." }, "disabled": { "type": "boolean", "description": "Indicates whether the ad group is disabled or not.", "example": false } } }, "ResponseEventV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the event (prefix `EVT-`).", "example": "EVT-Dxgp7NRjo6kXb5eG" }, "status": { "type": "string", "description": "The status of the event.", "enum": [ "Done", "Open" ] }, "title": { "type": "string", "description": "The title of the event.", "example": "Doctor appointment" }, "description": { "type": "string", "description": "The description of the event.", "example": "Doctor appointment with Dr. Smith" }, "start": { "type": "string", "description": "The time & date when the event starts.", "example": "2024-07-25 09:00:00" }, "end": { "type": "string", "description": "The time & date when the event ends.", "example": "2024-07-25 11:00:00" }, "isAllDay": { "type": "boolean", "description": "Whether the event is an all-day event.", "example": false }, "techIds": { "description": "Array of tech IDs assigned to the event (prefix `USR-`).", "example": [ "USR-83510a9930f203f4", "USR-a4f86bf1deefec12", "USR-d59dbcd34aa19dce" ], "type": "array", "items": { "type": "string" } }, "isDeleted": { "type": "boolean", "description": "Whether the event is deleted.", "example": false }, "updatedAt": { "type": "string", "description": "The date and time the event was updated.", "example": "2024-07-25 09:00:00" }, "createdAt": { "type": "string", "description": "The date and time the event was created.", "example": "2024-07-25 09:00:00" } } }, "ResponseEventsV2Dto": { "type": "object", "properties": { "pageSize": { "type": "number", "description": "The maximum number of items returned per page.", "example": 10 }, "page": { "type": "number", "description": "The current page number.", "example": 1 }, "totalResults": { "type": "number", "description": "The total number of results.", "example": 50 }, "hasMore": { "type": "boolean", "description": "Whether there are more results.", "example": true }, "data": { "description": "A list of Events.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseEventV2Dto" } } } }, "ResponseAttachEventV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the event (prefix `EVT-`).", "example": "EVT-Dxgp7NRjo6kXb5eG" }, "status": { "type": "string", "description": "The status of the event.", "enum": [ "Done", "Open" ] }, "title": { "type": "string", "description": "The title of the event.", "example": "Doctor appointment" }, "description": { "type": "string", "description": "The description of the event.", "example": "Doctor appointment with Dr. Smith" }, "start": { "type": "string", "description": "The time & date when the event starts.", "example": "2024-07-25 09:00:00" }, "end": { "type": "string", "description": "The time & date when the event ends.", "example": "2024-07-25 11:00:00" }, "isAllDay": { "type": "boolean", "description": "Whether the event is an all-day event.", "example": false }, "techIds": { "description": "Array of tech IDs assigned to the event (prefix `USR-`).", "example": [ "USR-83510a9930f203f4", "USR-a4f86bf1deefec12", "USR-d59dbcd34aa19dce" ], "type": "array", "items": { "type": "string" } }, "isDeleted": { "type": "boolean", "description": "Whether the event is deleted.", "example": false }, "updatedAt": { "type": "string", "description": "The date and time the event was updated.", "example": "2024-07-25 09:00:00" }, "createdAt": { "type": "string", "description": "The date and time the event was created.", "example": "2024-07-25 09:00:00" }, "attachments": { "description": "Array of attachments.", "example": [ { "name": "example", "type": "jpg", "filePath": "https://example.com/example.jpg" } ], "type": "array", "items": { "type": "string" } } } }, "CreateEventV2Dto": { "type": "object", "properties": { "status": { "type": "string", "description": "The status of the event.", "example": "Open", "default": "Open", "enum": [ "Done", "Open" ] }, "title": { "type": "string", "description": "The title of the event.", "example": "Doctor appointment" }, "description": { "type": "string", "description": "The description of the event.", "example": "Doctor appointment with Dr. Smith", "default": "" }, "start": { "type": "string", "description": "The time & date when the event starts. Must be before the end date.", "example": "2024-07-25 09:00:00" }, "end": { "type": "string", "description": "The time & date when the event ends. Must be after the start date.", "example": "2024-07-25 11:00:00" }, "isAllDay": { "type": "object", "description": "Whether the event is an all-day event.", "default": false, "example": false }, "techIds": { "description": "Array of tech IDs assigned to the event (prefix `USR-`).", "example": [ "USR-83510a9930f203f4", "USR-a4f86bf1deefec12", "USR-d59dbcd34aa19dce" ], "type": "array", "items": { "type": "string" } } }, "required": [ "title", "start", "end" ] }, "UpdateEventV2Dto": { "type": "object", "properties": { "status": { "type": "string", "description": "The status of the event.", "enum": [ "Done", "Open" ] }, "title": { "type": "string", "description": "The title of the event.", "example": "Doctor appointment" }, "description": { "type": "string", "description": "The description of the event.", "example": "Doctor appointment with Dr. Smith" }, "start": { "type": "string", "description": "The time & date when the event starts.", "example": "2024-07-25 09:00:00" }, "end": { "type": "string", "description": "The time & date when the event ends.", "example": "2024-07-25 11:00:00" }, "isAllDay": { "type": "boolean", "description": "Whether the event is an all-day event.", "example": false }, "techIds": { "description": "Array of tech IDs assigned to the event (prefix `USR-`). Pass an empty array to remove all technicians.", "example": [ "USR-83510a9930f203f4", "USR-a4f86bf1deefec12", "USR-d59dbcd34aa19dce" ], "type": "array", "items": { "type": "string" } } } }, "ResponseTimeOffV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the time off.", "example": "TO-de9750285414508f" }, "techId": { "type": "string", "description": "The assigned tech ID (prefix `USR-`). Use `-1` to assign to all company techs.", "example": "USR-38c1ee5c4efa38a4" }, "startDate": { "format": "date-time", "type": "string", "description": "The time & date when the time off starts.", "example": "2024-07-25 09:00:00" }, "endDate": { "format": "date-time", "type": "string", "description": "The time & date when the time off ends.", "example": "2024-07-25 11:00:00" }, "status": { "type": "string", "description": "The status of the time off.", "example": "approved", "enum": [ "approved", "pending", "declined" ] }, "reason": { "type": "string", "description": "The reason for the time off.", "example": "Vacation", "enum": [ "Vacation", "Sick day", "Personal", "Company Added", "Other" ] }, "details": { "type": "string", "description": "Details about the time off.", "example": "Doctor appointment" }, "isAllDay": { "type": "boolean", "description": "Whether the time off is for the entire day.", "example": true }, "updatedAt": { "format": "date-time", "type": "string", "description": "The date and time the time off was updated.", "example": "2024-07-25 09:00:00" }, "createdAt": { "format": "date-time", "type": "string", "description": "The date and time the time off was created.", "example": "2024-07-25 09:00:00" } } }, "ResponseTimeoffsV2Dto": { "type": "object", "properties": { "pageSize": { "type": "number", "description": "The maximum number of items returned per page.", "example": 10 }, "page": { "type": "number", "description": "The current page number.", "example": 1 }, "totalResults": { "type": "number", "description": "The total number of results.", "example": 50 }, "hasMore": { "type": "boolean", "description": "Whether there are more results.", "example": true }, "data": { "description": "A list of Time Off.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseTimeOffV2Dto" } } } }, "CreateTimeOffV2Dto": { "type": "object", "properties": { "techId": { "type": "string", "description": "The tech ID to assign the time off to (prefix `USR-`). Use `-1` to assign to all company techs.", "example": "USR-38c1ee5c4efa38a4" }, "startDate": { "format": "date-time", "type": "string", "description": "The time & date when the time off starts.", "example": "2024-07-25 09:00:00" }, "endDate": { "format": "date-time", "type": "string", "description": "The time & date when the time off ends.", "example": "2024-07-25 11:00:00" }, "status": { "type": "string", "description": "The status of the time off request.", "example": "pending", "enum": [ "approved", "pending", "declined" ] }, "reason": { "type": "string", "description": "Reason for the time off.", "example": "Vacation", "enum": [ "Vacation", "Sick day", "Personal", "Company Added", "Other" ] }, "details": { "type": "string", "description": "Details about the time off.", "example": "Doctor appointment" }, "isAllDay": { "type": "boolean", "description": "Whether the time off is for the entire day.", "example": false } }, "required": [ "techId", "startDate", "endDate" ] }, "UpdateTimeOffV2Dto": { "type": "object", "properties": { "techId": { "type": "string", "description": "The tech ID to assign the time off to (prefix `USR-`). Use `-1` to assign to all company techs.", "example": "USR-38c1ee5c4efa38a4" }, "startDate": { "format": "date-time", "type": "string", "description": "The time & date when the time off starts.", "example": "2024-07-25 09:00:00" }, "endDate": { "format": "date-time", "type": "string", "description": "The time & date when the time off ends.", "example": "2024-07-25 11:00:00" }, "status": { "type": "string", "description": "The status of the time off request.", "example": "pending", "enum": [ "approved", "pending", "declined" ] }, "reason": { "type": "string", "description": "Reason for the time off.", "example": "Vacation", "enum": [ "Vacation", "Sick day", "Personal", "Company Added", "Other" ] }, "details": { "type": "string", "description": "Details about the time off.", "example": "Doctor appointment" }, "isAllDay": { "type": "boolean", "description": "Whether the time off is for the entire day.", "example": false } } }, "ResponseAllClientContactV2Dto": { "type": "object", "properties": { "firstName": { "type": "string", "description": "The first name of the contact.", "example": "John" }, "lastName": { "type": "string", "description": "The last name of the contact.", "example": "Doe" }, "fullName": { "type": "string", "description": "The full name of the contact.", "example": "John Doe" }, "email": { "type": "string", "description": "The email address of the contact.", "example": "john.doe@example.com" }, "primaryPhone": { "type": "string", "description": "The primary phone number of the contact.", "example": "1234567890" }, "secondaryPhone": { "type": "string", "description": "The secondary phone number of the contact.", "example": "1234567890" }, "country": { "type": "string", "description": "The country of the contact.", "example": "USA" }, "state": { "type": "string", "description": "The state of the contact.", "example": "NY" }, "city": { "type": "string", "description": "The city of the contact.", "example": "New York" }, "zipcode": { "type": "string", "description": "The zip code of the contact.", "example": "10001" }, "address": { "type": "string", "description": "The address of the contact.", "example": "123 Main St" }, "role": { "type": "string", "description": "The job title or role of the contact.", "example": "Property Manager" }, "note": { "type": "string", "description": "A free-text note about the contact.", "example": "Prefers contact by email." } } }, "ResponseAllClientV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the client (prefix `CL-`).", "example": "CL-OvmDp2yvv1yqMwRl" }, "serialId": { "type": "number", "description": "The serial ID of the client.", "example": 1023 }, "firstName": { "type": "string", "description": "The first name of the client.", "example": "John" }, "lastName": { "type": "string", "description": "The last name of the client.", "example": "Doe" }, "fullName": { "type": "string", "description": "The full name of the client.", "example": "John Doe" }, "companyName": { "type": "string", "description": "The company name of the client.", "example": "John Doe Inc." }, "email": { "type": "string", "description": "The email address of the client.", "example": "john.doe@example.com" }, "primaryExt": { "type": "string", "description": "The primary phone extension of the client.", "example": "123" }, "primaryPhone": { "type": "string", "description": "The primary phone of the client.", "example": "1234567890" }, "secondaryExt": { "type": "string", "description": "The secondary phone extension of the client.", "example": "456" }, "secondaryPhone": { "type": "string", "description": "The secondary phone of the client.", "example": "1234567890" }, "country": { "type": "string", "description": "The country of the client.", "example": "USA" }, "state": { "type": "string", "description": "The state of the client.", "example": "NY" }, "city": { "type": "string", "description": "The city of the client.", "example": "New York" }, "zipcode": { "type": "string", "description": "The zipcode of the client.", "example": "10001" }, "unit": { "type": "string", "description": "The unit of the client.", "example": "100" }, "address": { "type": "string", "description": "The address of the client.", "example": "123 Main St" }, "fullAddress": { "type": "string", "description": "The full address of the client.", "example": "123 Main St, New York, NY 10001" }, "clientContacts": { "description": "The contacts of the client.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseAllClientContactV2Dto" } }, "created": { "format": "date-time", "type": "string", "description": "The creation date of the client.", "example": "2026-01-01 00:00:00" } } }, "ResponseClientsV2Dto": { "type": "object", "properties": { "pageSize": { "type": "number", "description": "The maximum number of items returned per page.", "example": 10 }, "page": { "type": "number", "description": "The current page number.", "example": 1 }, "totalResults": { "type": "number", "description": "The total number of results.", "example": 50 }, "hasMore": { "type": "boolean", "description": "Whether there are more results.", "example": true }, "data": { "description": "A list of the clients.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseAllClientV2Dto" } } } }, "ResponseGenericAdGroupV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the ad group (prefix `AG-`).", "example": "AG-71b8d7310acbf8cc" }, "name": { "type": "string", "description": "The name of the ad group.", "example": "Ad Group 1" } } }, "ResponseOneTagV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the tag (prefix `TAG-`).", "example": "TAG-211d1676f4b90c40" }, "name": { "type": "string", "description": "The name of the tag.", "example": "Tag 1" }, "color": { "type": "string", "description": "The color of the tag.", "example": "#edce4c" } } }, "ResponseOneBaseClientV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the client (prefix `CL-`).", "example": "CL-OvmDp2yvv1yqMwRl" }, "serialId": { "type": "number", "description": "The serial ID of the client.", "example": 1023 }, "firstName": { "type": "string", "description": "The first name of the client.", "example": "John" }, "lastName": { "type": "string", "description": "The last name of the client.", "example": "Doe" }, "fullName": { "type": "string", "description": "The full name of the client.", "example": "John Doe" }, "companyName": { "type": "string", "description": "The company name of the client.", "example": "John Doe Inc." }, "email": { "type": "string", "description": "The email address of the client.", "example": "john.doe@example.com" }, "primaryExt": { "type": "string", "description": "The primary phone extension of the client.", "example": "123" }, "primaryPhone": { "type": "string", "description": "The primary phone of the client.", "example": "1234567890" }, "secondaryExt": { "type": "string", "description": "The secondary phone extension of the client.", "example": "456" }, "secondaryPhone": { "type": "string", "description": "The secondary phone of the client.", "example": "1234567890" }, "country": { "type": "string", "description": "The country of the client.", "example": "USA" }, "state": { "type": "string", "description": "The state of the client.", "example": "NY" }, "city": { "type": "string", "description": "The city of the client.", "example": "New York" }, "zipcode": { "type": "string", "description": "The zipcode of the client.", "example": "10001" }, "unit": { "type": "string", "description": "The unit of the client.", "example": "100" }, "address": { "type": "string", "description": "The address of the client.", "example": "123 Main St" }, "serviceAddress": { "type": "string", "description": "The service address of the client.", "example": "123 Main St, New York, NY 10001" }, "billingAddress": { "type": "string", "description": "The billing address of the client.", "example": "123 Main St, New York, NY 10001" }, "allowBilling": { "type": "boolean", "description": "Whether the client allows billing.", "example": true } } }, "ResponseOneClientContactV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the client contact (prefix `CLC-`).", "example": "CLC-211d1676f4b90c40" }, "firstName": { "type": "string", "description": "The first name of the contact.", "example": "John" }, "lastName": { "type": "string", "description": "The last name of the contact.", "example": "Doe" }, "fullName": { "type": "string", "description": "The full name of the contact.", "example": "John Doe" }, "email": { "type": "string", "description": "The email address of the contact.", "example": "john.doe@example.com" }, "primaryPhone": { "type": "string", "description": "The primary phone number of the contact.", "example": "1234567890" }, "secondaryPhone": { "type": "string", "description": "The secondary phone number of the contact.", "example": "1234567890" }, "country": { "type": "string", "description": "The country of the contact.", "example": "USA" }, "state": { "type": "string", "description": "The state of the contact.", "example": "NY" }, "city": { "type": "string", "description": "The city of the contact.", "example": "New York" }, "zipcode": { "type": "string", "description": "The zip code of the contact.", "example": "10001" }, "address": { "type": "string", "description": "The address of the contact.", "example": "123 Main St" }, "role": { "type": "string", "description": "The job title or role of the contact.", "example": "Property Manager" }, "note": { "type": "string", "description": "A free-text note about the contact.", "example": "Prefers contact by email." } } }, "ResponseOneClientNoteV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the client note (prefix `CLN-`).", "example": "CLN-211d1676f4b90c40" }, "note": { "type": "string", "description": "The note content.", "example": "Customer requested a follow-up call." }, "techName": { "type": "string", "description": "The name of the user who created the note.", "example": "John Doe" }, "createdAt": { "format": "date-time", "type": "string", "description": "The date and time the note was created.", "example": "2021-01-01 00:00:00" } } }, "ResponseGenericCustomFieldV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the custom field (prefix `CF-`).", "example": "CF-eYLPK7198xVp6Z8q" }, "fieldName": { "type": "string", "description": "The name of the custom field.", "example": "Custom Field 1" }, "value": { "description": "The value of the custom field. Can be string, number, boolean, date string, or an array of file objects.", "oneOf": [ { "type": "string", "description": "A string value.", "example": "John Doe" }, { "type": "number", "description": "A number value.", "example": 123 }, { "type": "boolean", "description": "A boolean value.", "example": true }, { "type": "date", "description": "A date value.", "example": "2021-01-01" }, { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the file.", "example": "file.png" }, "url": { "type": "string", "description": "The URL of the file.", "example": "https://example.com/file.png" } } }, "example": [ { "name": "file.png", "url": "https://example.com/file.png" } ] } ] } } }, "ResponseClientV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the client (prefix `CL-`).", "example": "CL-OvmDp2yvv1yqMwRl" }, "serialId": { "type": "number", "description": "The serial ID of the client.", "example": 1023 }, "firstName": { "type": "string", "description": "The first name of the client.", "example": "John" }, "lastName": { "type": "string", "description": "The last name of the client.", "example": "Doe" }, "fullName": { "type": "string", "description": "The full name of the client.", "example": "John Doe" }, "companyName": { "type": "string", "description": "The company name of the client.", "example": "John Doe Inc." }, "email": { "type": "string", "description": "The email address of the client.", "example": "john.doe@example.com" }, "primaryExt": { "type": "string", "description": "The primary phone extension of the client.", "example": "123" }, "primaryPhone": { "type": "string", "description": "The primary phone of the client.", "example": "1234567890" }, "secondaryExt": { "type": "string", "description": "The secondary phone extension of the client.", "example": "456" }, "secondaryPhone": { "type": "string", "description": "The secondary phone of the client.", "example": "1234567890" }, "country": { "type": "string", "description": "The country of the client.", "example": "USA" }, "state": { "type": "string", "description": "The state of the client.", "example": "NY" }, "city": { "type": "string", "description": "The city of the client.", "example": "New York" }, "zipcode": { "type": "string", "description": "The zipcode of the client.", "example": "10001" }, "unit": { "type": "string", "description": "The unit of the client.", "example": "100" }, "address": { "type": "string", "description": "The address of the client.", "example": "123 Main St" }, "serviceAddress": { "type": "string", "description": "The service address of the client.", "example": "123 Main St, New York, NY 10001" }, "billingAddress": { "type": "string", "description": "The billing address of the client.", "example": "123 Main St, New York, NY 10001" }, "allowBilling": { "type": "boolean", "description": "Whether the client allows billing.", "example": true }, "adGroup": { "description": "The ad group of the client.", "allOf": [ { "$ref": "#/components/schemas/ResponseGenericAdGroupV2Dto" } ] }, "tags": { "description": "The tags of the client.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseOneTagV2Dto" } }, "parentClient": { "description": "The parent client of the client.", "allOf": [ { "$ref": "#/components/schemas/ResponseOneBaseClientV2Dto" } ] }, "clientContacts": { "description": "The contacts of the client.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseOneClientContactV2Dto" } }, "notes": { "description": "The notes of the client.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseOneClientNoteV2Dto" } }, "customFields": { "description": "A list of Client Custom Fields.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericCustomFieldV2Dto" } }, "created": { "type": "string", "description": "The creation date of the client.", "example": "2026-01-01 00:00:00" } } }, "CreateClientAddressDetailsV2Dto": { "type": "object", "properties": { "country": { "type": "string", "description": "The country of the address.", "example": "US" }, "state": { "type": "string", "description": "The state of the address.", "example": "NY" }, "city": { "type": "string", "description": "The city of the address.", "example": "New York" }, "zipCode": { "type": "string", "description": "The ZIP code of the address.", "example": "10001" }, "address": { "type": "string", "description": "The street address.", "example": "123 Main St" }, "unit": { "type": "string", "description": "The unit or suite number.", "example": "100" } } }, "CustomFieldValueV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the custom field (prefix `CF-`).", "example": "CF-DNr3zVoKWod6abEn" }, "value": { "description": "The value of the custom field.", "example": "test", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "id", "value" ] }, "CreateClientV2Dto": { "type": "object", "properties": { "firstName": { "type": "string", "description": "The first name of the client.", "example": "John" }, "lastName": { "type": "string", "description": "The last name of the client.", "example": "Doe" }, "companyName": { "type": "string", "description": "The company name of the client.", "example": "Example Inc." }, "email": { "type": "string", "description": "The email address of the client. Either email or primaryPhone must be provided.", "example": "john.doe@example.com" }, "primaryExt": { "type": "string", "description": "The extension number for the primary phone number.", "example": "123" }, "primaryPhone": { "type": "string", "description": "The primary phone number of the client. Either email or primaryPhone must be provided.", "example": "1234567890" }, "secondaryExt": { "type": "string", "description": "The extension number for the secondary phone number.", "example": "456" }, "secondaryPhone": { "type": "string", "description": "The secondary phone number of the client.", "example": "1234567890" }, "addressDetails": { "description": "The service address details of the client. When provided, a service location is created for the client.", "allOf": [ { "$ref": "#/components/schemas/CreateClientAddressDetailsV2Dto" } ] }, "billingAddressDetails": { "description": "The billing address details of the client. When different from the service address, a separate billing location is created.", "allOf": [ { "$ref": "#/components/schemas/CreateClientAddressDetailsV2Dto" } ] }, "adGroupId": { "type": "string", "description": "The ID of the ad group (prefix `AG-`).", "example": "AG-59kGnmvvyamryw1O" }, "allowBilling": { "type": "boolean", "description": "Whether the client allows billing. Defaults to the account-level setting when omitted.", "example": true }, "parentClientId": { "type": "string", "description": "The ID of the parent client (prefix `CL-`). The created client is set as a sub-client of it.", "example": "CL-OvmDp2yvv1yqMwRl" }, "taxExempt": { "type": "boolean", "description": "Whether the client is tax exempt.", "example": false }, "taxExemptReason": { "type": "string", "description": "The tax exemption reason code. Can only be provided when taxExempt is true; defaults to `99` (Other) when taxExempt is true and no reason is provided. Allowed values: `1` = Federal Government, `2` = State Government, `3` = Local Government, `4` = Tribal Government, `5` = Charitable Organization, `6` = Religious Organization, `7` = Educational Organization, `8` = Hospital, `9` = Resale, `10` = Direct Pay Permit, `11` = Multiple Points Of Use, `12` = Direct Mail, `13` = Agricultural Production, `14` = Industrial Production / Manufacturing, `15` = Foreign Diplomat, `99` = Other.", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "99" ], "example": "9" }, "description": { "type": "string", "description": "The description of the client.", "example": "This is a description" }, "customFields": { "description": "The custom fields of the client.", "example": [ { "id": "CF-DNr3zVoKWod6abEn", "value": "test" } ], "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldValueV2Dto" } } }, "required": [ "firstName" ] }, "ResponseClientNoteV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the client note (prefix `CLN-`).", "example": "CLN-211d1676f4b90c40" }, "note": { "type": "string", "description": "The note content.", "example": "Customer requested a follow-up call." }, "pin": { "type": "boolean", "description": "Whether the note is pinned to the top of the list.", "example": false }, "techName": { "type": "string", "description": "The name of the user who created the note.", "example": "John Doe" }, "createdAt": { "type": "string", "description": "The date and time the note was created.", "example": "2021-01-01 00:00:00" } } }, "ResponseClientNotesV2Dto": { "type": "object", "properties": { "pageSize": { "type": "number", "description": "The maximum number of items returned per page.", "example": 10 }, "page": { "type": "number", "description": "The current page number.", "example": 1 }, "totalResults": { "type": "number", "description": "The total number of results.", "example": 50 }, "hasMore": { "type": "boolean", "description": "Whether there are more results.", "example": true }, "data": { "description": "A list of Client Notes.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseClientNoteV2Dto" } } } }, "CreateClientNoteV2Dto": { "type": "object", "properties": { "note": { "type": "string", "description": "The note content.", "example": "Customer requested a follow-up call." }, "pin": { "type": "boolean", "description": "Whether the note is pinned to the top of the list.", "example": false } }, "required": [ "note" ] }, "UpdateClientNoteV2Dto": { "type": "object", "properties": { "note": { "type": "string", "description": "The note content.", "example": "Customer requested a follow-up call." }, "pin": { "type": "boolean", "description": "Whether the note is pinned to the top of the list.", "example": true } } }, "ResponseTagV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the tag (prefix `TAG-`).", "example": "TAG-3e6cca162914f48f" }, "name": { "type": "string", "description": "The name of the tag.", "example": "Opportunity" }, "color": { "type": "string", "description": "The color of the tag.", "enum": [ "#0059a0", "#be2c2c", "#e18a2b", "#37d34d", "#edce4c", "#c04d97", "#198218", "#3d1c8b" ] }, "type": { "type": "string", "description": "The type of the tag.", "example": "job" } } }, "ResponseTagsV2Dto": { "type": "object", "properties": { "pageSize": { "type": "number", "description": "The maximum number of items returned per page.", "example": 10 }, "page": { "type": "number", "description": "The current page number.", "example": 1 }, "totalResults": { "type": "number", "description": "The total number of results.", "example": 50 }, "hasMore": { "type": "boolean", "description": "Whether there are more results.", "example": true }, "data": { "description": "A list of Tags.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseTagV2Dto" } } } }, "CreateTagV2Dto": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the tag.", "example": "Opportunity" }, "color": { "type": "string", "description": "The color of the tag.", "enum": [ "#0059a0", "#be2c2c", "#e18a2b", "#37d34d", "#edce4c", "#c04d97", "#198218", "#3d1c8b" ] }, "type": { "type": "string", "description": "The type of the tag.", "enum": [ "job", "client", "call", "task", "project" ] } }, "required": [ "name", "color", "type" ] }, "UpdateTagV2Dto": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the tag.", "example": "Opportunity" }, "color": { "type": "string", "description": "The color of the tag.", "enum": [ "#0059a0", "#be2c2c", "#e18a2b", "#37d34d", "#edce4c", "#c04d97", "#198218", "#3d1c8b" ] } } }, "ResponseJobJobSubStatusV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the job sub status (prefix `JSS-`).", "example": "JSS-BA5r7o4bqzR9MONa" }, "name": { "type": "string", "description": "The name of the job sub status.", "example": "Follow Up" } } }, "ResponseGenericJobTypeV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the job type (prefix `JT-`).", "example": "JT-8718036049ec4c4d" }, "name": { "type": "string", "description": "The name of the job type.", "example": "Repair" } } }, "ResponseJobLeadAddressV2Dto": { "type": "object", "properties": { "country": { "type": "string", "description": "The country of the client.", "example": "US" }, "state": { "type": "string", "description": "The state of the client.", "example": "Ohio" }, "city": { "type": "string", "description": "The city of the client.", "example": "San Francisco" }, "zipCode": { "type": "string", "description": "The zip code of the client.", "example": "94102" }, "address": { "type": "string", "description": "The address of the client.", "example": "462 Powell St" }, "unit": { "type": "string", "description": "The unit of the client.", "example": "3422" }, "latitude": { "type": "number", "description": "The latitude of the client.", "example": -76.2768398 }, "longitude": { "type": "number", "description": "The longitude of the client.", "example": 36.9669587 }, "locationKey": { "type": "string", "description": "The location key of the client.", "example": "462 Powell St, San Francisco, Ohio 94102" } } }, "ResponseGenericServiceAreaV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the service area (prefix `SA-`).", "example": "SA-71b8d7310acbf8cc" }, "name": { "type": "string", "description": "The name of the service area.", "example": "San Francisco" } } }, "ResponseJobLeadDetailsV2Dto": { "type": "object", "properties": { "clientId": { "type": "string", "description": "The ID of the associated client (prefix `CL-`).", "example": "CL-OvmDp2yvv1yqMwRl" }, "serialId": { "type": "number", "description": "The serial ID of the client.", "example": 1023 }, "firstName": { "type": "string", "description": "The first name of the client.", "example": "John Doe" }, "lastName": { "type": "string", "description": "The last name of the client.", "example": "Doe" }, "companyName": { "type": "string", "description": "The company name of the client.", "example": "Sample Company name" }, "email": { "type": "string", "description": "The email address of the client.", "example": "client@workiz.com" }, "primaryExt": { "type": "string", "description": "The primary extension of the client.", "example": "619" }, "primaryPhone": { "type": "string", "description": "The primary phone of the client.", "example": "6195555555" }, "secondaryExt": { "type": "string", "description": "The secondary extension of the client.", "example": "613" }, "secondaryPhone": { "type": "string", "description": "The secondary phone of the client.", "example": "6195555555" }, "addressDetails": { "description": "The address of the client.", "allOf": [ { "$ref": "#/components/schemas/ResponseJobLeadAddressV2Dto" } ] }, "serviceArea": { "description": "The service area.", "allOf": [ { "$ref": "#/components/schemas/ResponseGenericServiceAreaV2Dto" } ] } } }, "ResponseJobMaskedNumberV2Dto": { "type": "object", "properties": { "number": { "type": "string", "description": "The call masking phone number.", "example": "6195551234" }, "extension": { "type": "string", "description": "The call masking extension for the primary phone.", "example": "042" }, "secondaryExtension": { "type": "string", "description": "The call masking extension for the secondary phone.", "example": "043" } }, "required": [ "number", "extension" ] }, "ResponseGenericTechV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the technician (prefix `USR-`).", "example": "USR-38c1ee5c4efa38a4" }, "name": { "type": "string", "description": "The name of the technician.", "example": "John Doe" } } }, "ResponseJobLineItemV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the job line item (prefix `JLI-`).", "example": "JLI-BA5r7o4bqzR9MONa" }, "productId": { "type": "number", "description": "The product ID of the item from which this line item was created.", "example": 1000 }, "type": { "type": "string", "description": "The type of the line item.", "example": "product" }, "name": { "type": "string", "description": "The name of the line item.", "example": "Deadbolt" }, "description": { "type": "string", "description": "The description of the line item.", "example": "Deadbolt replacement, any color and size" }, "price": { "type": "number", "description": "The price of the line item.", "example": 100 }, "quantity": { "type": "number", "description": "The quantity of the line item.", "example": 1 }, "total": { "type": "number", "description": "The total of the line item.", "example": 100 }, "cost": { "type": "number", "description": "The cost of the line item.", "example": 100 }, "taxable": { "type": "boolean", "description": "Whether the line item is taxable.", "example": true }, "discountable": { "type": "boolean", "description": "Whether the line item is discountable.", "example": true }, "inventoryManaged": { "type": "boolean", "description": "Whether the line item is managed by inventory.", "example": true }, "inventorySync": { "type": "boolean", "description": "Whether the line item is synced to inventory.", "example": true }, "optionalConverted": { "type": "boolean", "description": "Whether the line item was an optional item.", "example": true } } }, "ResponseGenericPaymentV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the payment (prefix `PAY-`).", "example": "PAY-BA5r7o4bqzR9MONa" }, "type": { "type": "string", "description": "The type of the payment.", "example": "Cash" }, "amount": { "type": "number", "description": "The amount of the payment.", "example": 100 }, "tipAmount": { "type": "number", "description": "The tip amount.", "example": 10 } } }, "ResponseGenericTagV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the tag (prefix `TAG-`).", "example": "TAG-8cddc18e7b0458fa" }, "name": { "type": "string", "description": "The name of the tag.", "example": "Estimate" } } }, "ResponseJobLeadNoteV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the note (prefix `JNT-`).", "example": "JNT-8cddc18e7b0458fa" }, "techName": { "type": "string", "description": "The name of the technician who created the note.", "example": "John Doe" }, "note": { "type": "string", "description": "The note.", "example": "This is a note" }, "timestamp": { "format": "date-time", "type": "string", "description": "The date and time when the note was made.", "example": "2022-01-01 10:00:00" } } }, "ResponseJobV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the job (prefix `JOB-`).", "example": "JOB-BA5r7o4bqzR9MONa" }, "uuid": { "type": "string", "description": "The UUID of the job.", "example": "3YBIBO" }, "serialId": { "type": "number", "description": "The serial ID of the job.", "example": 12345 }, "name": { "type": "string", "description": "The name of the job.", "example": "AC Repair" }, "status": { "type": "string", "description": "The status of the job.", "example": "Submitted" }, "subStatus": { "description": "The sub status of the job.", "allOf": [ { "$ref": "#/components/schemas/ResponseJobJobSubStatusV2Dto" } ] }, "date": { "format": "date-time", "type": "string", "description": "The date and time when the job is scheduled.", "example": "2022-01-01 10:00:00" }, "endDate": { "format": "date-time", "type": "string", "description": "The date and time when the job is scheduled to end.", "example": "2022-01-01 10:00:00" }, "isAllDay": { "type": "boolean", "description": "Whether the job is all day.", "example": false }, "isScheduled": { "type": "boolean", "description": "Whether the job is scheduled.", "example": true }, "jobType": { "description": "The type of the job.", "allOf": [ { "$ref": "#/components/schemas/ResponseGenericJobTypeV2Dto" } ] }, "adGroup": { "description": "The ad group of the job.", "allOf": [ { "$ref": "#/components/schemas/ResponseGenericAdGroupV2Dto" } ] }, "description": { "type": "string", "description": "The description of the job.", "example": "This is a description of the job." }, "subTotal": { "type": "number", "description": "The subtotal of the job before tax and discounts.", "example": 946 }, "discountAmount": { "type": "number", "description": "The job discount amount.", "example": 10 }, "taxableAmount": { "type": "number", "description": "The taxable amount of the job.", "example": 946 }, "taxPercent": { "type": "number", "description": "The tax percentage of the job.", "example": 10.111 }, "taxAmount": { "type": "number", "description": "The tax amount of the job.", "example": 10.51 }, "costing": { "type": "number", "description": "The cost amount of the job.", "example": 10.51 }, "techExpenses": { "type": "number", "description": "The technician expenses of the job.", "example": 12.51 }, "tipAmount": { "type": "number", "description": "The tip amount of the job.", "example": 43.51 }, "totalPrice": { "type": "number", "description": "The total price of the job.", "example": 956.51 }, "amountDue": { "type": "number", "description": "The amount due for the job.", "example": 956.51 }, "amountDueDate": { "format": "date-time", "type": "string", "description": "The date and time when the job amount is due.", "example": "2022-01-01 10:00:00" }, "converted": { "type": "boolean", "description": "Whether the job was converted from a lead.", "example": true }, "clientInfo": { "description": "The client information of the job.", "allOf": [ { "$ref": "#/components/schemas/ResponseJobLeadDetailsV2Dto" } ] }, "maskedNumber": { "description": "Call masking number and extension for the customer on this job, if available.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/ResponseJobMaskedNumberV2Dto" } ] }, "team": { "description": "A list of job technicians.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericTechV2Dto" } }, "lineItems": { "description": "A list of Job Line Items.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseJobLineItemV2Dto" } }, "payments": { "description": "The payments of the job.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericPaymentV2Dto" } }, "tags": { "description": "A list of Job Tags.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericTagV2Dto" } }, "customFields": { "description": "A list of Job Custom Fields.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericCustomFieldV2Dto" } }, "notes": { "description": "A list of Job Notes.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseJobLeadNoteV2Dto" } }, "conversionDate": { "format": "date-time", "type": "string", "description": "The date and time when the job was converted from a lead (based on account timezone).", "example": "2022-01-01 10:00:00" }, "statusUpdated": { "format": "date-time", "type": "string", "description": "The date and time when the job status was last updated (based on account timezone).", "example": "2022-01-01 12:00:00" }, "updatedAt": { "format": "date-time", "type": "string", "description": "The date and time when the job was last updated (based on account timezone).", "example": "2022-01-01 12:00:00" }, "createdAt": { "format": "date-time", "type": "string", "description": "The date and time when the job was created (based on account timezone).", "example": "2022-01-01 10:00:00" } } }, "ResponseJobsV2Dto": { "type": "object", "properties": { "pageSize": { "type": "number", "description": "The maximum number of items returned per page.", "example": 10 }, "page": { "type": "number", "description": "The current page number.", "example": 1 }, "totalResults": { "type": "number", "description": "The total number of results.", "example": 50 }, "hasMore": { "type": "boolean", "description": "Whether there are more results.", "example": true }, "data": { "description": "A list of Jobs.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseJobV2Dto" } } } }, "ResponseGenericAttachmentV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the attachment (prefix `FLE-`).", "example": "FLE-BA5r7o4bqzR9MONa" }, "name": { "type": "string", "description": "The name of the attachment.", "example": "file.pdf" }, "fileUrl": { "type": "string", "description": "The URL of the attachment.", "example": "https://example.com/file.pdf" } } }, "ResponseOneJobV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the job (prefix `JOB-`).", "example": "JOB-BA5r7o4bqzR9MONa" }, "uuid": { "type": "string", "description": "The UUID of the job.", "example": "3YBIBO" }, "serialId": { "type": "number", "description": "The serial ID of the job.", "example": 12345 }, "name": { "type": "string", "description": "The name of the job.", "example": "AC Repair" }, "status": { "type": "string", "description": "The status of the job.", "example": "Submitted" }, "subStatus": { "description": "The sub status of the job.", "allOf": [ { "$ref": "#/components/schemas/ResponseJobJobSubStatusV2Dto" } ] }, "date": { "format": "date-time", "type": "string", "description": "The date and time when the job is scheduled.", "example": "2022-01-01 10:00:00" }, "endDate": { "format": "date-time", "type": "string", "description": "The date and time when the job is scheduled to end.", "example": "2022-01-01 10:00:00" }, "isAllDay": { "type": "boolean", "description": "Whether the job is all day.", "example": false }, "isScheduled": { "type": "boolean", "description": "Whether the job is scheduled.", "example": true }, "jobType": { "description": "The type of the job.", "allOf": [ { "$ref": "#/components/schemas/ResponseGenericJobTypeV2Dto" } ] }, "adGroup": { "description": "The ad group of the job.", "allOf": [ { "$ref": "#/components/schemas/ResponseGenericAdGroupV2Dto" } ] }, "description": { "type": "string", "description": "The description of the job.", "example": "This is a description of the job." }, "subTotal": { "type": "number", "description": "The subtotal of the job before tax and discounts.", "example": 946 }, "discountAmount": { "type": "number", "description": "The job discount amount.", "example": 10 }, "taxableAmount": { "type": "number", "description": "The taxable amount of the job.", "example": 946 }, "taxPercent": { "type": "number", "description": "The tax percentage of the job.", "example": 10.111 }, "taxAmount": { "type": "number", "description": "The tax amount of the job.", "example": 10.51 }, "costing": { "type": "number", "description": "The cost amount of the job.", "example": 10.51 }, "techExpenses": { "type": "number", "description": "The technician expenses of the job.", "example": 12.51 }, "tipAmount": { "type": "number", "description": "The tip amount of the job.", "example": 43.51 }, "totalPrice": { "type": "number", "description": "The total price of the job.", "example": 956.51 }, "amountDue": { "type": "number", "description": "The amount due for the job.", "example": 956.51 }, "amountDueDate": { "format": "date-time", "type": "string", "description": "The date and time when the job amount is due.", "example": "2022-01-01 10:00:00" }, "converted": { "type": "boolean", "description": "Whether the job was converted from a lead.", "example": true }, "clientInfo": { "description": "The client information of the job.", "allOf": [ { "$ref": "#/components/schemas/ResponseJobLeadDetailsV2Dto" } ] }, "maskedNumber": { "description": "Call masking number and extension for the customer on this job, if available.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/ResponseJobMaskedNumberV2Dto" } ] }, "team": { "description": "A list of job technicians.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericTechV2Dto" } }, "lineItems": { "description": "A list of Job Line Items.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseJobLineItemV2Dto" } }, "payments": { "description": "The payments of the job.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericPaymentV2Dto" } }, "tags": { "description": "A list of Job Tags.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericTagV2Dto" } }, "customFields": { "description": "A list of Job Custom Fields.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericCustomFieldV2Dto" } }, "notes": { "description": "A list of Job Notes.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseJobLeadNoteV2Dto" } }, "conversionDate": { "format": "date-time", "type": "string", "description": "The date and time when the job was converted from a lead (based on account timezone).", "example": "2022-01-01 10:00:00" }, "statusUpdated": { "format": "date-time", "type": "string", "description": "The date and time when the job status was last updated (based on account timezone).", "example": "2022-01-01 12:00:00" }, "updatedAt": { "format": "date-time", "type": "string", "description": "The date and time when the job was last updated (based on account timezone).", "example": "2022-01-01 12:00:00" }, "createdAt": { "format": "date-time", "type": "string", "description": "The date and time when the job was created (based on account timezone).", "example": "2022-01-01 10:00:00" }, "attachments": { "description": "The attachments of the job.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericAttachmentV2Dto" } } } }, "CreateUpdateAddressDetailsV2Dto": { "type": "object", "properties": { "country": { "type": "string", "description": "The country of the address.", "example": "US" }, "state": { "type": "string", "description": "The state of the address.", "example": "NY" }, "city": { "type": "string", "description": "The city of the address.", "example": "New York" }, "zipCode": { "type": "string", "description": "The ZIP code of the address.", "example": "10001" }, "address": { "type": "string", "description": "The street address.", "example": "123 Main St" }, "unit": { "type": "string", "description": "The unit or suite number.", "example": "100" } } }, "CreateClientInfoV2Dto": { "type": "object", "properties": { "clientId": { "type": "string", "description": "The ID of the client (prefix `CL-`). Used to fill in any missing fields from the existing client record.", "example": "CL-Lb2R3vrLxBk3YkOJ" }, "firstName": { "type": "string", "description": "The first name of the client. Required when clientId is not provided.", "example": "John" }, "lastName": { "type": "string", "description": "The last name of the client.", "example": "Doe" }, "email": { "type": "string", "description": "The email address of the client. Required when clientId is not provided and primaryPhone is not provided.", "example": "john.doe@example.com" }, "companyName": { "type": "string", "description": "The company name of the client.", "example": "Example Inc." }, "primaryExt": { "type": "string", "description": "The extension number for the primary phone number.", "example": "123" }, "primaryPhone": { "type": "string", "description": "The primary phone number of the client. Required when clientId is not provided and email is not provided.", "example": "1234567890" }, "secondaryExt": { "type": "string", "description": "The extension number for the secondary phone number.", "example": "123" }, "secondaryPhone": { "type": "string", "description": "The secondary phone number of the client.", "example": "1234567890" }, "addressDetails": { "description": "The address details of the client.", "allOf": [ { "$ref": "#/components/schemas/CreateUpdateAddressDetailsV2Dto" } ] } } }, "CreateJobV2Dto": { "type": "object", "properties": { "date": { "format": "date-time", "type": "string", "description": "The scheduled start date and time for the job (Must be before the endDate). Required when isScheduled is true. Note: Both dates are rounded to the nearest quarter hour (0, 15, 30, 45 minutes) for validation.", "example": "2022-01-01 10:00:00" }, "endDate": { "format": "date-time", "type": "string", "description": "The scheduled end date and time for the job (Must be after the start date). Required when isScheduled is true. Note: Both dates are rounded to the nearest quarter hour (0, 15, 30, 45 minutes) for validation.", "example": "2022-01-01 10:00:00" }, "isAllDay": { "type": "boolean", "description": "> **Beta:** This property is subject to change and may contain bugs.\n\nWhether the job is an all-day event. Defaults to false.", "example": false, "x-badges": [ { "name": "Beta", "position": "after", "color": "purple" } ] }, "isScheduled": { "type": "boolean", "description": "> **Beta:** This property is subject to change and may contain bugs.\n\nWhether the job is scheduled. When false, the job is created as unscheduled and date/endDate become optional. Defaults to true.", "example": true, "x-badges": [ { "name": "Beta", "position": "after", "color": "purple" } ] }, "name": { "type": "string", "description": "The name of the job.", "example": "AC Repair" }, "description": { "type": "string", "description": "The description of the job.", "example": "This is a description" }, "timeZone": { "type": "string", "description": "The timezone of the job.", "example": "America/New_York" }, "jobTypeId": { "type": "string", "description": "The ID of the job type (prefix `JT-`).", "example": "JT-38c1ee5c4efa38a4" }, "adGroupId": { "type": "string", "description": "The ID of the ad group (prefix `AG-`).", "example": "AG-59kGnmvvyamryw1O" }, "clientInfo": { "description": "The client information including address details.", "allOf": [ { "$ref": "#/components/schemas/CreateClientInfoV2Dto" } ] }, "createdBy": { "type": "string", "description": "The ID of the user who created the job (prefix `USR-`).", "example": "USR-laAe5KNY6DZmEnzV" }, "createdDate": { "format": "date-time", "type": "string", "description": "The date and time when the job record was created. If not provided, defaults to the current timestamp.", "example": "2022-01-01 10:00:00" }, "customFields": { "description": "The custom fields of the job.", "example": [ { "id": "CF-DNr3zVoKWod6abEn", "value": "test" } ], "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldValueV2Dto" } } }, "required": [ "jobTypeId", "clientInfo" ] }, "UpdateClientInfoV2Dto": { "type": "object", "properties": { "firstName": { "type": "string", "description": "The first name of the client (required when clientId is not provided).", "example": "John" }, "lastName": { "type": "string", "description": "The last name of the client.", "example": "Doe" }, "email": { "type": "string", "description": "The email address of the client (required when clientId is not provided).", "example": "john.doe@example.com" }, "companyName": { "type": "string", "description": "The company name of the client.", "example": "Example Inc." }, "primaryExt": { "type": "string", "description": "The extension number for the primary phone number.", "example": "123" }, "primaryPhone": { "type": "string", "description": "The primary phone number of the client.", "example": "1234567890" }, "secondaryExt": { "type": "string", "description": "The extension number for the secondary phone number.", "example": "123" }, "secondaryPhone": { "type": "string", "description": "The secondary phone number of the client.", "example": "1234567890" }, "addressDetails": { "description": "The address details of the client.", "allOf": [ { "$ref": "#/components/schemas/CreateUpdateAddressDetailsV2Dto" } ] } } }, "UpdateJobV2Dto": { "type": "object", "properties": { "status": { "type": "string", "description": "The status of the job.", "example": "Submitted", "enum": [ "Submitted", "In progress", "Pending", "done pending approval", "Canceled", "Done" ] }, "subStatusId": { "type": "string", "description": "The ID of the job sub status (prefix `JSS-`).", "example": "JSS-BA5r7o4bqzR9MONa" }, "date": { "format": "date-time", "type": "string", "description": "The scheduled start date and time for the job (Must be before the endDate). Note: Both dates are rounded to the nearest quarter hour (0, 15, 30, 45 minutes) for validation.", "example": "2022-01-01 10:00:00" }, "endDate": { "format": "date-time", "type": "string", "description": "The scheduled end date and time for the job (Must be after the start date). Note: Both dates are rounded to the nearest quarter hour (0, 15, 30, 45 minutes) for validation.", "example": "2022-01-01 10:00:00" }, "isAllDay": { "type": "boolean", "description": "> **Beta:** This property is subject to change and may contain bugs.\n\nWhether the job is an all-day event. When omitted, the current value is left unchanged.", "example": false, "x-badges": [ { "name": "Beta", "position": "after", "color": "purple" } ] }, "isScheduled": { "type": "boolean", "description": "> **Beta:** This property is subject to change and may contain bugs.\n\nWhether the job is scheduled. When false, the job is marked as unscheduled. When omitted, the current schedule state is left unchanged.", "example": true, "x-badges": [ { "name": "Beta", "position": "after", "color": "purple" } ] }, "name": { "type": "string", "description": "The name of the job.", "example": "AC Repair" }, "description": { "type": "string", "description": "The description of the job.", "example": "This is a description" }, "timeZone": { "type": "string", "description": "The timezone of the job.", "example": "America/New_York" }, "jobTypeId": { "type": "string", "description": "The ID of the job type (prefix `JT-`).", "example": "JT-38c1ee5c4efa38a4" }, "adGroupId": { "type": "string", "description": "The ID of the ad group (prefix `AG-`).", "example": "AG-59kGnmvvyamryw1O" }, "clientInfo": { "description": "The client information including address details.", "allOf": [ { "$ref": "#/components/schemas/UpdateClientInfoV2Dto" } ] }, "createdBy": { "type": "string", "description": "The ID of the user who created the job (prefix `USR-`).", "example": "USR-laAe5KNY6DZmEnzV" }, "tags": { "description": "Array of tag IDs to assign to the job (prefix `TAG-`).", "example": [ "TAG-16a94b03317f6e64" ], "type": "array", "items": { "type": "string" } }, "customFields": { "description": "The custom fields of the job.", "example": [ { "id": "CF-DNr3zVoKWod6abEn", "value": "test" } ], "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldValueV2Dto" } } } }, "ResponseLeadV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the lead (prefix `LD-`).", "example": "LD-LwqGJnRwvZPaNe5E" }, "uuid": { "type": "string", "description": "The UUID of the lead.", "example": "GD87TS" }, "serialId": { "type": "number", "description": "The serial ID of the lead.", "example": 12345 }, "status": { "type": "string", "description": "The status of the lead.", "example": "Submitted" }, "date": { "format": "date-time", "type": "string", "description": "The date and time when the lead is scheduled.", "example": "2022-01-01 10:00:00" }, "endDate": { "format": "date-time", "type": "string", "description": "The date and time when the lead is scheduled to end.", "example": "2022-01-01 10:00:00" }, "isAllDay": { "type": "boolean", "description": "Whether the lead is all day.", "example": true }, "isScheduled": { "type": "boolean", "description": "Whether the lead is scheduled.", "example": true }, "jobType": { "description": "The type of the lead.", "allOf": [ { "$ref": "#/components/schemas/ResponseGenericJobTypeV2Dto" } ] }, "adGroup": { "description": "The ad group of the lead.", "allOf": [ { "$ref": "#/components/schemas/ResponseGenericAdGroupV2Dto" } ] }, "description": { "type": "string", "description": "The description of the lead.", "example": "This is a description of the lead." }, "leadLost": { "type": "boolean", "description": "Whether the lead was marked as lost.", "example": true }, "clientInfo": { "description": "The client information of the lead.", "allOf": [ { "$ref": "#/components/schemas/ResponseJobLeadDetailsV2Dto" } ] }, "team": { "description": "A list of lead technicians.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericTechV2Dto" } }, "tags": { "description": "A list of Tags.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericTagV2Dto" } }, "customFields": { "description": "A list of Custom Fields.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericCustomFieldV2Dto" } }, "notes": { "description": "A list of Notes.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseJobLeadNoteV2Dto" } }, "statusUpdated": { "format": "date-time", "type": "string", "description": "The date and time when the lead status was last updated (based on account timezone).", "example": "2022-01-01 12:00:00" }, "updatedAt": { "format": "date-time", "type": "string", "description": "The date and time when the lead was last updated (based on account timezone).", "example": "2022-01-01 12:00:00" }, "createdAt": { "format": "date-time", "type": "string", "description": "The date and time when the lead was created (based on account timezone).", "example": "2022-01-01 10:00:00" } } }, "ResponseLeadsV2Dto": { "type": "object", "properties": { "pageSize": { "type": "number", "description": "The maximum number of items returned per page.", "example": 10 }, "page": { "type": "number", "description": "The current page number.", "example": 1 }, "totalResults": { "type": "number", "description": "The total number of results.", "example": 50 }, "hasMore": { "type": "boolean", "description": "Whether there are more results.", "example": true }, "data": { "description": "A list of Leads.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseLeadV2Dto" } } } }, "CreateLeadV2Dto": { "type": "object", "properties": { "date": { "format": "date-time", "type": "string", "description": "The scheduled start date and time for the lead (Must be before the endDate). Required when isScheduled is true. Note: Both dates are rounded to the nearest quarter hour (0, 15, 30, 45 minutes) for validation.", "example": "2022-01-01 10:00:00" }, "endDate": { "format": "date-time", "type": "string", "description": "The scheduled end date and time for the lead (Must be after the start date). Required when isScheduled is true. Note: Both dates are rounded to the nearest quarter hour (0, 15, 30, 45 minutes) for validation.", "example": "2022-01-01 10:00:00" }, "isAllDay": { "type": "boolean", "description": "> **Beta:** This property is subject to change and may contain bugs.\n\nWhether the lead is an all-day event. Defaults to false.", "example": false, "x-badges": [ { "name": "Beta", "position": "after", "color": "purple" } ] }, "isScheduled": { "type": "boolean", "description": "> **Beta:** This property is subject to change and may contain bugs.\n\nWhether the lead is scheduled. When false, the lead is created as unscheduled and date/endDate become optional. Defaults to true.", "example": true, "x-badges": [ { "name": "Beta", "position": "after", "color": "purple" } ] }, "description": { "type": "string", "description": "The description of the lead.", "example": "This is a description" }, "timeZone": { "type": "string", "description": "The timezone of the lead.", "example": "America/New_York" }, "jobTypeId": { "type": "string", "description": "The ID of the job type (prefix `JT-`).", "example": "JT-38c1ee5c4efa38a4" }, "adGroupId": { "type": "string", "description": "The ID of the ad group (prefix `AG-`).", "example": "AG-59kGnmvvyamryw1O" }, "clientInfo": { "description": "The client information including address details.", "allOf": [ { "$ref": "#/components/schemas/CreateClientInfoV2Dto" } ] }, "createdBy": { "type": "string", "description": "The ID of the user who created the lead (prefix `USR-`).", "example": "USR-laAe5KNY6DZmEnzV" }, "createdDate": { "format": "date-time", "type": "string", "description": "The date and time when the lead record was created. If not provided, defaults to the current timestamp.", "example": "2022-01-01 10:00:00" }, "customFields": { "description": "The custom fields of the lead.", "example": [ { "id": "CF-DNr3zVoKWod6abEn", "value": "test" } ], "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldValueV2Dto" } } }, "required": [ "clientInfo" ] }, "UpdateLeadV2Dto": { "type": "object", "properties": { "status": { "type": "string", "description": "The status of the lead.", "example": "new", "enum": [ "new", "scheduled", "in progress", "estimated", "approved", "and any user-defined status" ] }, "date": { "format": "date-time", "type": "string", "description": "The scheduled start date and time for the lead (Must be before the endDate). Note: Both dates are rounded to the nearest quarter hour (0, 15, 30, 45 minutes) for validation.", "example": "2022-01-01 10:00:00" }, "endDate": { "format": "date-time", "type": "string", "description": "The scheduled end date and time for the lead (Must be after the start date). Note: Both dates are rounded to the nearest quarter hour (0, 15, 30, 45 minutes) for validation.", "example": "2022-01-01 10:00:00" }, "isAllDay": { "type": "boolean", "description": "> **Beta:** This property is subject to change and may contain bugs.\n\nWhether the lead is an all-day event. When omitted, the current value is left unchanged.", "example": false, "x-badges": [ { "name": "Beta", "position": "after", "color": "purple" } ] }, "isScheduled": { "type": "boolean", "description": "> **Beta:** This property is subject to change and may contain bugs.\n\nWhether the lead is scheduled. When false, the lead is marked as unscheduled. When omitted, the current schedule state is left unchanged.", "example": true, "x-badges": [ { "name": "Beta", "position": "after", "color": "purple" } ] }, "description": { "type": "string", "description": "The description of the lead.", "example": "This is a description" }, "timeZone": { "type": "string", "description": "The timezone of the lead.", "example": "America/New_York" }, "jobTypeId": { "type": "string", "description": "The ID of the job type (prefix `JT-`). Pass an empty value to remove the job type from the lead.", "example": "JT-38c1ee5c4efa38a4" }, "adGroupId": { "type": "string", "description": "The ID of the ad group (prefix `AG-`).", "example": "AG-59kGnmvvyamryw1O" }, "clientInfo": { "description": "The client information including address details.", "allOf": [ { "$ref": "#/components/schemas/UpdateClientInfoV2Dto" } ] }, "createdBy": { "type": "string", "description": "The ID of the user who created the lead (prefix `USR-`).", "example": "USR-laAe5KNY6DZmEnzV" }, "tags": { "description": "Array of tag IDs to assign to the lead (prefix `TAG-`).", "example": [ "TAG-16a94b03317f6e64" ], "type": "array", "items": { "type": "string" } }, "customFields": { "description": "The custom fields of the lead.", "example": [ { "id": "CF-DNr3zVoKWod6abEn", "value": "test" } ], "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldValueV2Dto" } } } }, "ResponseUserV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the user (prefix `USR-`).", "example": "USR-38c1ee5c4efa38a4" }, "name": { "type": "string", "description": "The name of the user.", "example": "John Smith" }, "emailAddress": { "type": "string", "description": "The email address of the user.", "example": "john.doe@gmail.com" }, "cellPhone": { "type": "string", "description": "The phone number of the user.", "example": "1234567890" }, "address": { "type": "string", "description": "The address of the user.", "example": "1234 Elm Street, Apt 5B, Springfield, IL 62701, USA" }, "role": { "type": "string", "description": "The role of the user.", "example": "tech" }, "fieldTech": { "type": "boolean", "description": "Whether the user is a field technician and can be assigned to jobs.", "example": true }, "active": { "type": "boolean", "description": "Whether the user is active.", "example": true }, "notes": { "type": "string", "description": "Notes about the user.", "example": "This is a note" }, "jobTypes": { "description": "The job types assigned to the user. An empty array means the user is assigned to all job types.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericJobTypeV2Dto" } }, "serviceAreas": { "description": "The service areas of the user.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericServiceAreaV2Dto" } } } }, "ResponseUsersV2Dto": { "type": "object", "properties": { "pageSize": { "type": "number", "description": "The maximum number of items returned per page.", "example": 10 }, "page": { "type": "number", "description": "The current page number.", "example": 1 }, "totalResults": { "type": "number", "description": "The total number of results.", "example": 50 }, "hasMore": { "type": "boolean", "description": "Whether there are more results.", "example": true }, "data": { "description": "A list of Users.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseUserV2Dto" } } } }, "CreateDeleteUserJobTypeV2Dto": { "type": "object", "properties": { "jobTypes": { "description": "Array of job type IDs (prefix `JT-`).", "example": [ "JT-38c1ee5c4efa38a4", "JT-38c1ee5c4efa38a5" ], "type": "array", "items": { "type": "string" } } }, "required": [ "jobTypes" ] }, "ResponseLeadStatusV2Dto": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the lead status.", "example": "Submitted" } } }, "ResponseLeadStatusesV2Dto": { "type": "object", "properties": { "totalResults": { "type": "number", "description": "The total number of lead statuses.", "example": 10 }, "hasMore": { "type": "boolean", "description": "Whether there are more lead statuses to fetch.", "example": false }, "data": { "description": "A list of Lead Statuses.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseLeadStatusV2Dto" } } } }, "CreateLeadStatusV2Dto": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the lead status.", "example": "Submitted" } }, "required": [ "name" ] }, "ResponseAllInvoiceV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the invoice (prefix `IV-`).", "example": "IV-bK9r2XyZL54aWDR0" }, "uuid": { "type": "string", "description": "The UUID of the invoice.", "example": "3YBIBO" }, "serialId": { "type": "number", "description": "The serial ID of the invoice.", "example": "56" }, "name": { "type": "string", "description": "The name of the invoice.", "example": "Invoice 1" }, "notes": { "type": "string", "description": "The invoice note.", "example": "This is a note for the invoice" }, "jobId": { "type": "string", "description": "The ID of the associated job (prefix `JOB-`).", "example": "JOB-BA5r7o4bqzR9MONa" }, "subTotal": { "type": "number", "description": "The subtotal of the invoice before tax and discounts.", "example": 946 }, "taxableAmount": { "type": "number", "description": "The taxable amount of the invoice.", "example": 946 }, "taxPercent": { "type": "number", "description": "The tax percentage of the invoice.", "example": 10.111 }, "taxAmount": { "type": "number", "description": "The tax amount of the invoice.", "example": 10.51 }, "costing": { "type": "number", "description": "The cost amount of the invoice.", "example": 10.51 }, "techExpenses": { "type": "number", "description": "The technician expenses of the invoice.", "example": 12.51 }, "tipAmount": { "type": "number", "description": "The tip amount of the invoice.", "example": 43.51 }, "totalPrice": { "type": "number", "description": "The total price of the invoice.", "example": 956.51 }, "amountDue": { "type": "number", "description": "The amount due for the invoice.", "example": 956.51 }, "amountDueDate": { "format": "date-time", "type": "string", "description": "The date and time when the invoice amount is due.", "example": "2026-01-01 10:00:00" }, "updated": { "format": "date-time", "type": "string", "description": "The date and time the invoice was last updated.", "example": "2026-01-01 00:00:00" }, "created": { "format": "date-time", "type": "string", "description": "The date and time the invoice was created.", "example": "2026-01-01 00:00:00" } } }, "ResponseInvoicesV2Dto": { "type": "object", "properties": { "pageSize": { "type": "number", "description": "The maximum number of items returned per page.", "example": 10 }, "page": { "type": "number", "description": "The current page number.", "example": 1 }, "totalResults": { "type": "number", "description": "The total number of results.", "example": 50 }, "hasMore": { "type": "boolean", "description": "Whether there are more results.", "example": true }, "data": { "description": "A list of Invoices.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseAllInvoiceV2Dto" } } } }, "ResponseInvoiceLineItemV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the invoice line item (prefix `ILI-`).", "example": "ILI-BA5r7o4bqzR9MONa" }, "productId": { "type": "number", "description": "The product ID of the item from which this line item was created.", "example": 1000 }, "name": { "type": "string", "description": "The name of the line item.", "example": "Deadbolt" }, "description": { "type": "string", "description": "The description of the line item.", "example": "Deadbolt replacement, any color and size" }, "price": { "type": "number", "description": "The price of the line item.", "example": 100 }, "quantity": { "type": "number", "description": "The quantity of the line item.", "example": 1 }, "total": { "type": "number", "description": "The total of the line item.", "example": 100 }, "cost": { "type": "number", "description": "The cost of the line item.", "example": 100 }, "taxable": { "type": "boolean", "description": "Whether the line item is taxable.", "example": true }, "discountable": { "type": "boolean", "description": "Whether the line item is discountable.", "example": true }, "inventoryManaged": { "type": "boolean", "description": "Whether the line item is managed by inventory.", "example": true }, "inventorySync": { "type": "boolean", "description": "Whether the line item is synced to inventory.", "example": true }, "optionalConverted": { "type": "boolean", "description": "Whether the line item was an optional item.", "example": true } } }, "ResponseGenericSignatureV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the signature image (prefix `IMG-`).", "example": "IMG-BA5r7o4bqzR9MONa" }, "signedByName": { "type": "string", "description": "The name of the person who signed.", "example": "John Doe" }, "imageUrl": { "type": "string", "description": "The URL of the signature image.", "example": "https://example.com/image.png" } } }, "ResponseInvoiceV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the invoice (prefix `IV-`).", "example": "IV-bK9r2XyZL54aWDR0" }, "uuid": { "type": "string", "description": "The UUID of the invoice.", "example": "3YBIBO" }, "serialId": { "type": "number", "description": "The serial ID of the invoice.", "example": "56" }, "name": { "type": "string", "description": "The name of the invoice.", "example": "Invoice 1" }, "notes": { "type": "string", "description": "The invoice note.", "example": "This is a note for the invoice" }, "jobId": { "type": "string", "description": "The ID of the associated job (prefix `JOB-`).", "example": "JOB-BA5r7o4bqzR9MONa" }, "discountAmount": { "type": "number", "description": "The invoice discount amount.", "example": 10 }, "subTotal": { "type": "number", "description": "The subtotal of the invoice before tax and discounts.", "example": 946 }, "taxableAmount": { "type": "number", "description": "The taxable amount of the invoice.", "example": 946 }, "taxPercent": { "type": "number", "description": "The tax percentage of the invoice.", "example": 10.111 }, "taxAmount": { "type": "number", "description": "The tax amount of the invoice.", "example": 10.51 }, "costing": { "type": "number", "description": "The cost amount of the invoice.", "example": 10.51 }, "techExpenses": { "type": "number", "description": "The technician expenses of the invoice.", "example": 12.51 }, "tipAmount": { "type": "number", "description": "The tip amount of the invoice.", "example": 43.51 }, "totalPrice": { "type": "number", "description": "The total price of the invoice.", "example": 956.51 }, "amountDue": { "type": "number", "description": "The amount due for the invoice.", "example": 956.51 }, "amountDueDate": { "format": "date-time", "type": "string", "description": "The date and time when the invoice amount is due.", "example": "2026-01-01 10:00:00" }, "lineItems": { "description": "A list of invoice line items.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseInvoiceLineItemV2Dto" } }, "payments": { "description": "The payments of the invoice.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericPaymentV2Dto" } }, "attachments": { "description": "The attachments of the invoice.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericAttachmentV2Dto" } }, "signatureImage": { "description": "The signature images of the invoice.", "allOf": [ { "$ref": "#/components/schemas/ResponseGenericSignatureV2Dto" } ] }, "updated": { "format": "date-time", "type": "string", "description": "The date and time the invoice was last updated.", "example": "2026-01-01 00:00:00" }, "created": { "format": "date-time", "type": "string", "description": "The date and time the invoice was created.", "example": "2026-01-01 00:00:00" } } }, "ResponseTimesheetV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the time sheet (prefix `TS-`).", "example": "TS-de9750285414508f" }, "techId": { "type": "string", "description": "The ID of the user logged to this shift (prefix `USR-`).", "example": "USR-81ce48127c24fd23" }, "techName": { "type": "string", "description": "The name of the user logged to this shift.", "example": "John Doe" }, "startDate": { "type": "string", "description": "The start date and time of the shift.", "example": "2024-01-24 08:00:00" }, "endDate": { "type": "string", "description": "The end date and time of the shift.", "example": "2024-01-24 16:00:00" }, "notes": { "type": "string", "description": "The notes of the shift.", "example": "This is a note" }, "jobId": { "type": "string", "description": "The ID of the job associated with this shift (prefix `JOB-`).", "example": "JOB-BA5r7o4bqzR9MONa" }, "laborCost": { "type": "number", "description": "The labor cost per hour of this shift.", "example": 34.75 }, "shiftLength": { "type": "string", "description": "The length of the shift in hours.", "example": "08:00" } } }, "ResponseTimesheetsV2Dto": { "type": "object", "properties": { "pageSize": { "type": "number", "description": "The maximum number of items returned per page.", "example": 10 }, "page": { "type": "number", "description": "The current page number.", "example": 1 }, "totalResults": { "type": "number", "description": "The total number of results.", "example": 50 }, "hasMore": { "type": "boolean", "description": "Whether there are more results.", "example": true }, "data": { "description": "A list of Time Sheets.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseTimesheetV2Dto" } } } }, "CreateTimesheetV2DTO": { "type": "object", "properties": { "techId": { "type": "string", "description": "The ID of the user to clock into this shift (prefix `USR-`).", "example": "USR-81ce48127c24fd23" }, "jobId": { "type": "string", "description": "The ID of the job associated with this shift (prefix `JOB-`).", "example": "JOB-BA5r7o4bqzR9MONa" }, "laborCost": { "type": "number", "description": "The labor cost per hour of this shift.", "example": 25 }, "startDate": { "type": "string", "description": "The start date and time of the shift.", "example": "2024-07-25 09:00:00" }, "endDate": { "type": "string", "description": "The end date and time of the shift.", "example": "2024-07-25 09:00:00" }, "notes": { "type": "string", "description": "The notes of the shift.", "example": "This is a note" } }, "required": [ "techId", "startDate", "endDate" ] }, "UpdateTimesheetV2Dto": { "type": "object", "properties": { "techId": { "type": "string", "description": "The ID of the user clocked into this shift (prefix `USR-`).", "example": "USR-81ce48127c24fd23" }, "laborCost": { "type": "number", "description": "The labor cost per hour of this shift.", "example": 25 }, "startDate": { "type": "string", "description": "The start date and time of the shift.", "example": "2024-07-25 09:00:00" }, "endDate": { "type": "string", "description": "The end date and time of the shift.", "example": "2024-07-25 09:00:00" }, "notes": { "type": "string", "description": "The notes of the shift.", "example": "This is a note" } } }, "ResponseSearchClientInfoV2Dto": { "type": "object", "properties": { "serialId": { "type": "number", "description": "The serial ID of the client.", "example": 1023 }, "fullName": { "type": "string", "description": "The full name of the client.", "example": "John Doe" }, "companyName": { "type": "string", "description": "The company name of the client.", "example": "Sample Company name" }, "email": { "type": "string", "description": "The email address of the client.", "example": "client@workiz.com" }, "primaryPhone": { "type": "string", "description": "The primary phone number of the client.", "example": "6195555555" }, "fullAddress": { "type": "string", "description": "The full address of the client.", "example": "123 Main St, New York, NY 10001" } } }, "ResponseSearchV2Dto": { "type": "object", "properties": { "entityType": { "type": "string", "description": "The entity type of the result.", "example": "job", "enum": [ "job", "lead", "client", "invoice" ] }, "entityId": { "type": "string", "description": "ID of the entity. Can be used with the corresponding entity endpoint (e.g. GET /jobs/:id).", "example": "JOB-LwqGJnRwvZPaNe5E" }, "uuid": { "type": "string", "description": "UUID of the entity. Not present when the result is a client.", "example": "GD87TS" }, "serialId": { "type": "number", "description": "Numeric serial ID of the entity.", "example": 1042 }, "name": { "type": "string", "description": "Display name of the entity. For jobs this is the job name, for clients the full name.", "example": "Fix leaking pipe" }, "status": { "type": "string", "description": "Status of the entity (e.g. `pending`, `completed`). Only present for jobs and leads.", "example": "pending" }, "date": { "type": "string", "description": "Scheduled date for jobs and leads. Format: `yyyy-MM-dd HH:mm:ss`. Not present for clients or invoices.", "example": "2026-04-28 09:00:00" }, "totalPrice": { "type": "number", "description": "Total price of the invoice. Only present for invoices.", "example": 250 }, "amountDue": { "type": "number", "description": "Amount due on the invoice. Only present for invoices.", "example": 100 }, "companyName": { "type": "string", "description": "Company name of the client. Only present for clients.", "example": "Acme Corp" }, "email": { "type": "string", "description": "Email address of the client. Only present for clients.", "example": "client@example.com" }, "primaryPhone": { "type": "string", "description": "Primary phone number of the client. Only present for clients.", "example": "6195551234" }, "fullAddress": { "type": "string", "description": "Full address of the client. Only present for clients.", "example": "123 Main St, San Diego, CA 92101" }, "clientInfo": { "description": "Client associated with the job, lead, or invoice. Not present when the result itself is a client.", "allOf": [ { "$ref": "#/components/schemas/ResponseSearchClientInfoV2Dto" } ] } } }, "ResponseSearchResultsV2Dto": { "type": "object", "properties": { "limit": { "type": "number", "description": "The maximum number of results returned per entity type.", "example": 5 }, "totalResults": { "type": "number", "description": "The total number of results.", "example": 10 }, "data": { "description": "List of matching search results.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseSearchV2Dto" } } } }, "ResponseJobSubStatusV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the job sub status (prefix `JSS-`).", "example": "JSS-BA5r7o4bqzR9MONa" }, "name": { "type": "string", "description": "The name of the job sub status.", "example": "Follow Up" }, "parentName": { "type": "string", "description": "The name of the parent job status.", "example": "In progress" }, "color": { "type": "string", "description": "The color key of the job sub status.", "example": "lavender", "enum": [ "silver", "blue", "green", "orange", "red", "anthracite", "grey", "azure", "denim", "royalBlue", "crimson", "cerise", "apricot", "cream", "bronze", "yellow", "emerald", "forest", "purple", "plum", "lavender", "violet", "slate" ] } } }, "ResponseJobSubStatusesV2Dto": { "type": "object", "properties": { "pageSize": { "type": "number", "description": "The maximum number of items returned per page.", "example": 10 }, "page": { "type": "number", "description": "The current page number.", "example": 1 }, "totalResults": { "type": "number", "description": "The total number of results.", "example": 50 }, "hasMore": { "type": "boolean", "description": "Whether there are more results.", "example": true }, "data": { "description": "A list of Job Sub Statuses.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseJobSubStatusV2Dto" } } } }, "CreateJobSubStatusV2Dto": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the job sub status.", "example": "New" }, "parentName": { "type": "string", "description": "The name of the parent job status.", "example": "In progress", "enum": [ "In progress", "Canceled", "Pending", "done pending approval" ] }, "color": { "type": "string", "description": "The color key for the job sub status. Available colors:
silver: #cccccc
blue: #004795
green: #6d960c
orange: #cc9707
red: #e35a36
anthracite: #282e36
grey: #666666
azure: #3589E9
denim: #24589B
royalBlue: #000ED2
crimson: #B91C1C
cerise: #E11D48
apricot: #FBAB33
cream: #E8CF63
bronze: #D58E41
yellow: #FFD400
emerald: #22C55E
forest: #3E802B
purple: #9747FF
plum: #B25494
lavender: #D574E4
violet: #391E86
slate: #3B4B52", "example": "silver", "enum": [ "silver", "blue", "green", "orange", "red", "anthracite", "grey", "azure", "denim", "royalBlue", "crimson", "cerise", "apricot", "cream", "bronze", "yellow", "emerald", "forest", "purple", "plum", "lavender", "violet", "slate" ] } }, "required": [ "name", "parentName", "color" ] }, "UpdateJobSubStatusV2Dto": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the job sub status.", "example": "New" }, "color": { "type": "string", "description": "The color key for the job sub status. Available colors:
silver: #cccccc
blue: #004795
green: #6d960c
orange: #cc9707
red: #e35a36
anthracite: #282e36
grey: #666666
azure: #3589E9
denim: #24589B
royalBlue: #000ED2
crimson: #B91C1C
cerise: #E11D48
apricot: #FBAB33
cream: #E8CF63
bronze: #D58E41
yellow: #FFD400
emerald: #22C55E
forest: #3E802B
purple: #9747FF
plum: #B25494
lavender: #D574E4
violet: #391E86
slate: #3B4B52", "example": "silver", "enum": [ "silver", "blue", "green", "orange", "red", "anthracite", "grey", "azure", "denim", "royalBlue", "crimson", "cerise", "apricot", "cream", "bronze", "yellow", "emerald", "forest", "purple", "plum", "lavender", "violet", "slate" ] } } }, "ResponseJobLeadTechnitionV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the user", "example": "USR-BA5r7o4bqzR9MONa" }, "name": { "type": "string", "description": "The name of the technician.", "example": "John Doe" }, "emailAddress": { "type": "string", "description": "The email address of the technician.", "example": "john.doe@example.com" }, "isPrimary": { "type": "boolean", "description": "Whether the technician is the primary technician.", "example": true } } }, "ResponseJobTechnitionsV2Dto": { "type": "object", "properties": { "pageSize": { "type": "number", "description": "The maximum number of items returned per page.", "example": 10 }, "page": { "type": "number", "description": "The current page number.", "example": 1 }, "totalResults": { "type": "number", "description": "The total number of results.", "example": 50 }, "hasMore": { "type": "boolean", "description": "Whether there are more results.", "example": true }, "data": { "description": "A list of Job Technicians.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseJobLeadTechnitionV2Dto" } } } }, "CreateJobLeadTechnitionV2Dto": { "type": "object", "properties": { "technitionId": { "type": "number", "description": "The ID of the technician (prefix `USR-`).", "example": "USR-BA5r7o4bqzR9MONa" }, "isPrimary": { "type": "number", "description": "Whether the technician is the primary technician.", "example": true }, "replace": { "type": "boolean", "description": "Whether to replace the existing technician, works only if the option \"Allow Multiple Technicians\" is disabled in the account settings.", "example": true } }, "required": [ "technitionId" ] }, "ResponseLeadTechnitionsV2Dto": { "type": "object", "properties": { "pageSize": { "type": "number", "description": "The maximum number of items returned per page.", "example": 10 }, "page": { "type": "number", "description": "The current page number.", "example": 1 }, "totalResults": { "type": "number", "description": "The total number of results.", "example": 50 }, "hasMore": { "type": "boolean", "description": "Whether there are more results.", "example": true }, "data": { "description": "A list of Lead Technicians.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseJobLeadTechnitionV2Dto" } } } }, "ResponseCustomFieldV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the custom field (prefix `CF-`).", "example": "CF-eYLPK7198xVp6Z8q" }, "entityType": { "type": "string", "description": "The entity type of the custom field.", "enum": [ "JOB", "CLIENT" ], "example": "JOB" }, "name": { "type": "string", "description": "The name of the custom field.", "example": "Custom Field 1" }, "type": { "type": "string", "description": "The type of the custom field.", "enum": [ "Text", "Number", "Date", "Drop Down", "Checkbox", "Large Text", "File Upload" ], "example": "Text" }, "groupId": { "description": "The ID of the custom fields group the field belongs to (prefix `CFG-`). -1 if no group is assigned.", "example": "CFG-eYLPK7198xVp6Z8q", "oneOf": [ { "type": "string", "example": "CFG-eYLPK7198xVp6Z8q" }, { "type": "number", "example": -1 } ] }, "jobTypes": { "description": "The job types associated with the custom field.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericJobTypeV2Dto" } }, "options": { "description": "The options of the custom field.", "example": [ "option 1", "option 2", "option 3" ], "type": "array", "items": { "type": "string" } }, "position": { "type": "number", "description": "The position of the custom field.", "example": 1 }, "required": { "type": "boolean", "description": "Indicates whether the custom field is required or not. (job only)", "example": false }, "requiredClose": { "type": "boolean", "description": "Indicates whether the custom field is required to close the job. (job only)", "example": false }, "searchable": { "type": "boolean", "description": "Indicates whether the custom field is searchable or not.", "example": false } } }, "ResponseCustomFieldsV2Dto": { "type": "object", "properties": { "pageSize": { "type": "number", "description": "The maximum number of items returned per page.", "example": 10 }, "page": { "type": "number", "description": "The current page number.", "example": 1 }, "totalResults": { "type": "number", "description": "The total number of results.", "example": 50 }, "hasMore": { "type": "boolean", "description": "Whether there are more results.", "example": true }, "data": { "description": "The list of custom fields.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseCustomFieldV2Dto" } } } }, "CreateCustomFieldV2Dto": { "type": "object", "properties": { "entityType": { "type": "string", "description": "The entity type of the custom field.", "enum": [ "JOB", "CLIENT" ], "example": "JOB" }, "name": { "type": "string", "description": "The custom field name.", "example": "Custom Field 1" }, "type": { "type": "string", "description": "The type of the custom field.", "enum": [ "Text", "Number", "Date", "Drop Down", "Checkbox", "Large Text", "File Upload" ], "example": "Text" }, "groupId": { "type": "string", "description": "The ID of the custom fields group (prefix `CFG-`). Use -1 for no group. Defaults to -1.", "example": "CFG-KMYQvPr0GZWwke3z" }, "jobTypes": { "description": "Array of job type IDs to associate with the custom field (prefix `JT-`).", "example": [ "JT-KMYQvPr0GZWwke3z", "JT-AMYQvPr0GZWwke4a" ], "type": "array", "items": { "type": "string" } }, "options": { "description": "The options of the custom field (Drop Down type only).", "example": [ "option 1", "option 2", "option 3" ], "type": "array", "items": { "type": "string" } }, "position": { "type": "number", "description": "The position of the custom field.", "example": 1 }, "required": { "type": "boolean", "description": "Indicates whether the custom field is required or not. (job only)", "example": false }, "requiredClose": { "type": "boolean", "description": "Indicates whether the custom field is required to close the job. (job only)", "example": false }, "searchable": { "type": "boolean", "description": "Indicates whether the custom field is searchable or not.", "example": false } }, "required": [ "entityType", "name", "type" ] }, "UpdateCustomFieldV2Dto": { "type": "object", "properties": { "name": { "type": "string", "description": "The custom field name.", "example": "Custom Field 1" }, "groupId": { "type": "string", "description": "The ID of the custom fields group (prefix `CFG-`). Use -1 for no group. Defaults to -1.", "example": "CFG-KMYQvPr0GZWwke3z" }, "jobTypes": { "description": "Array of job type IDs to associate with the custom field (prefix `JT-`).", "example": [ "JT-KMYQvPr0GZWwke3z", "JT-AMYQvPr0GZWwke4a" ], "type": "array", "items": { "type": "string" } }, "options": { "description": "The options of the custom field (Drop Down type only).", "example": [ "option 1", "option 2", "option 3" ], "type": "array", "items": { "type": "string" } }, "position": { "type": "number", "description": "The position of the custom field.", "example": 1 }, "required": { "type": "boolean", "description": "Indicates whether the custom field is required or not. (job only)", "example": false }, "requiredClose": { "type": "boolean", "description": "Indicates whether the custom field is required to close the job. (job only)", "example": false }, "searchable": { "type": "boolean", "description": "Indicates whether the custom field is searchable or not.", "example": false } } }, "ResponseCustomFieldsGroupV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the custom fields group (prefix `CFG-`).", "example": "CFG-eYLPK7198xVp6Z8q" }, "entityType": { "type": "string", "description": "The entity type of the custom fields group.", "enum": [ "JOB", "CLIENT" ], "example": "JOB" }, "name": { "type": "string", "description": "The name of the custom fields group.", "example": "Custom Fields Group 1" } } }, "ResponseCustomFieldsGroupsV2Dto": { "type": "object", "properties": { "pageSize": { "type": "number", "description": "The maximum number of items returned per page.", "example": 10 }, "page": { "type": "number", "description": "The current page number.", "example": 1 }, "totalResults": { "type": "number", "description": "The total number of results.", "example": 50 }, "hasMore": { "type": "boolean", "description": "Whether there are more results.", "example": true }, "data": { "description": "The list of custom fields groups.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseCustomFieldsGroupV2Dto" } } } }, "CreateCustomFieldsGroupV2Dto": { "type": "object", "properties": { "entityType": { "type": "string", "description": "The entity type of the custom fields group.", "enum": [ "JOB", "CLIENT" ], "example": "JOB" }, "name": { "type": "string", "description": "The custom fields group name.", "example": "Custom Fields Group 1" } }, "required": [ "entityType", "name" ] }, "UpdateCustomFieldsGroupV2Dto": { "type": "object", "properties": { "name": { "type": "string", "description": "The custom fields group name.", "example": "Custom Fields Group 1" } } }, "ResponseAvailabilitySlotV2Dto": { "type": "object", "properties": { "startTime": { "type": "string", "description": "The start date and time of the slot in the account timezone, in `YYYY-MM-DD HH:mm` format.", "example": "2026-01-15 09:00" }, "startTimestamp": { "type": "number", "description": "The start time of the slot as a Unix timestamp in seconds.", "example": 1768460400 }, "slotLength": { "type": "number", "description": "The duration of the slot in minutes.", "example": 60 }, "totalSpots": { "type": "number", "description": "The total number of bookings the slot can hold.", "example": 3 }, "openSpots": { "type": "number", "description": "The number of bookings still available in the slot.", "example": 2 }, "userIds": { "description": "Technicians unavailable in this slot. (prefix `USR-`)", "example": [ "USR-83510a9930f203f4", "USR-a4f86bf1deefec12", "USR-d59dbcd34aa19dce" ], "type": "array", "items": { "type": "string" } } } }, "ResponseAvailabilitySlotsV2Dto": { "type": "object", "properties": { "totalResults": { "type": "number", "description": "The total number of available booking slots within the requested range.", "example": 100 }, "data": { "description": "A list of available booking slots within the requested range.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseAvailabilitySlotV2Dto" } } } }, "BlockingEntitiesV2Dto": { "type": "object", "properties": { "type": { "type": "string", "description": "The entity type occupying the slot.", "enum": [ "job", "lead", "task", "event", "recurrence", "timeOff" ], "example": "job" }, "id": { "type": "string", "description": "The ID of the entity. For recurrences this is the parent job ID. (prefixes `JOB-`, `LD-`, `TSK-`, `EVT-`, or `TO-`)", "example": "JOB-BA5r7o4bqzR9MONa" }, "name": { "type": "string", "description": "The display name of the entity.", "example": "Plumbing repair" } } }, "ResponseBlockingEntityV2Dto": { "type": "object", "properties": { "startTime": { "type": "string", "description": "The start date and time of the slot in the account timezone, in `YYYY-MM-DD HH:mm` format.", "example": "2026-01-15 09:00" }, "startTimestamp": { "type": "number", "description": "The start time of the slot as a Unix timestamp in seconds.", "example": 1768460400 }, "blockingEntities": { "description": "The entities occupying capacity in this slot.", "type": "array", "items": { "$ref": "#/components/schemas/BlockingEntitiesV2Dto" } } } }, "ResponseBlockingEntitiesV2Dto": { "type": "object", "properties": { "totalResults": { "type": "number", "description": "The total number of slots on the requested date.", "example": 100 }, "data": { "description": "The list of slots and entities occupying them on the requested date.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseBlockingEntityV2Dto" } } } }, "ResponseAllEstimateV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the estimate (prefix `ES-`).", "example": "ES-LwqGJnRwvZPaNe5E" }, "status": { "type": "string", "description": "The status of the estimate.", "example": "Pending" }, "serialId": { "type": "string", "description": "The interval of the estimate.", "example": "1-1" }, "name": { "type": "string", "description": "The name of the estimate.", "example": "Estimate 1" }, "description": { "type": "string", "description": "The description of the estimate.", "example": "This is a description for the estimate" }, "notes": { "type": "string", "description": "The estimate note.", "example": "This is a note for the estimate" }, "imageUrl": { "type": "string", "description": "The image URL of the estimate.", "example": "https://example.com/image.png" }, "clientId": { "type": "string", "description": "The ID of the associated client (prefix `CL-`).", "example": "CL-LwqGJnRwvZPaNe5E" }, "jobId": { "type": "string", "description": "The ID of the associated job or lead (prefix `JOB-` or `LD-`).", "example": "JOB-BA5r7o4bqzR9MONa" }, "taxPercent": { "type": "number", "description": "The estimate tax percent.", "example": 10 }, "taxableAmount": { "type": "number", "description": "The estimate taxable amount.", "example": 100 }, "taxAmount": { "type": "number", "description": "The estimate tax amount.", "example": 10 }, "isDepositPercentage": { "type": "boolean", "description": "The estimate deposit percentage or amount.", "example": true }, "deposit": { "type": "number", "description": "The deposit amount or percentage needed.", "example": 100 }, "subTotal": { "type": "number", "description": "The estimate subtotal before tax and discounts.", "example": 10 }, "total": { "type": "number", "description": "The total amount of the estimate.", "example": 10 }, "declineReason": { "type": "string", "description": "The decline reason of the estimate.", "example": "This is a decline reason for the estimate" }, "sentDate": { "format": "date-time", "type": "string", "description": "The sent date of the estimate.", "example": "2026-01-01 00:00:00" }, "estimateDate": { "format": "date-time", "type": "string", "description": "The date of the estimate.", "example": "2026-01-01 00:00:00" }, "lastViewedDate": { "format": "date-time", "type": "string", "description": "The last viewed date of the estimate.", "example": "2026-01-01 00:00:00" }, "statusUpdatedAt": { "format": "date-time", "type": "string", "description": "The date and time the status was last updated.", "example": "2026-01-01 00:00:00" }, "updated": { "format": "date-time", "type": "string", "description": "The date and time the estimate was last updated.", "example": "2026-01-01 00:00:00" }, "created": { "format": "date-time", "type": "string", "description": "The date and time the estimate was created.", "example": "2026-01-01 00:00:00" } } }, "ResponseEstimatesV2Dto": { "type": "object", "properties": { "pageSize": { "type": "number", "description": "The maximum number of items returned per page.", "example": 10 }, "page": { "type": "number", "description": "The current page number.", "example": 1 }, "totalResults": { "type": "number", "description": "The total number of results.", "example": 50 }, "hasMore": { "type": "boolean", "description": "Whether there are more results.", "example": true }, "data": { "description": "A list of Estimates.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseAllEstimateV2Dto" } } } }, "ResponseEstimateLineItemV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the estimate line item (prefix `ELI-`).", "example": "ELI-BA5r7o4bqzR9MONa" }, "productId": { "type": "number", "description": "The product ID of the item from which this line item was created.", "example": 1000 }, "name": { "type": "string", "description": "The name of the line item.", "example": "Deadbolt" }, "description": { "type": "string", "description": "The description of the line item.", "example": "Deadbolt replacement, any color and size" }, "price": { "type": "number", "description": "The price of the line item.", "example": 100 }, "quantity": { "type": "number", "description": "The quantity of the line item.", "example": 1 }, "total": { "type": "number", "description": "The total of the line item.", "example": 100 }, "cost": { "type": "number", "description": "The cost of the line item.", "example": 100 }, "taxable": { "type": "boolean", "description": "Whether the line item is taxable.", "example": true }, "discountable": { "type": "boolean", "description": "Whether the line item is discountable.", "example": true }, "inventoryManaged": { "type": "boolean", "description": "Whether the line item is managed by inventory.", "example": true }, "inventorySync": { "type": "boolean", "description": "Whether the line item is synced to inventory.", "example": true }, "optionalConverted": { "type": "boolean", "description": "Whether the line item was an optional item.", "example": true } } }, "ResponseOneEstimateV2Dto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the estimate (prefix `ES-`).", "example": "ES-LwqGJnRwvZPaNe5E" }, "status": { "type": "string", "description": "The status of the estimate.", "example": "Pending" }, "serialId": { "type": "string", "description": "The interval of the estimate.", "example": "1-1" }, "name": { "type": "string", "description": "The name of the estimate.", "example": "Estimate 1" }, "description": { "type": "string", "description": "The description of the estimate.", "example": "This is a description for the estimate" }, "notes": { "type": "string", "description": "The estimate note.", "example": "This is a note for the estimate" }, "imageUrl": { "type": "string", "description": "The image URL of the estimate.", "example": "https://example.com/image.png" }, "clientId": { "type": "string", "description": "The ID of the associated client (prefix `CL-`).", "example": "CL-LwqGJnRwvZPaNe5E" }, "jobId": { "type": "string", "description": "The ID of the associated job or lead (prefix `JOB-` or `LD-`).", "example": "JOB-BA5r7o4bqzR9MONa" }, "discountAmount": { "type": "number", "description": "The estimate discount amount.", "example": 10 }, "taxPercent": { "type": "number", "description": "The estimate tax percent.", "example": 10 }, "taxableAmount": { "type": "number", "description": "The estimate taxable amount.", "example": 100 }, "taxAmount": { "type": "number", "description": "The estimate tax amount.", "example": 10 }, "isDepositPercentage": { "type": "boolean", "description": "The estimate deposit percentage or amount.", "example": true }, "deposit": { "type": "number", "description": "The deposit amount or percentage needed.", "example": 100 }, "subTotal": { "type": "number", "description": "The estimate subtotal before tax and discounts.", "example": 10 }, "total": { "type": "number", "description": "The total amount of the estimate.", "example": 10 }, "declineReason": { "type": "string", "description": "The decline reason of the estimate.", "example": "This is a decline reason for the estimate" }, "lineItems": { "description": "A list of estimate line items.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseEstimateLineItemV2Dto" } }, "payments": { "description": "The payments of the estimate.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericPaymentV2Dto" } }, "attachments": { "description": "The attachments of the estimate.", "type": "array", "items": { "$ref": "#/components/schemas/ResponseGenericAttachmentV2Dto" } }, "signatureImage": { "description": "The signature images of the estimate.", "allOf": [ { "$ref": "#/components/schemas/ResponseGenericSignatureV2Dto" } ] }, "sentDate": { "format": "date-time", "type": "string", "description": "The sent date of the estimate.", "example": "2026-01-01 00:00:00" }, "estimateDate": { "format": "date-time", "type": "string", "description": "The date of the estimate.", "example": "2026-01-01 00:00:00" }, "lastViewedDate": { "format": "date-time", "type": "string", "description": "The last viewed date of the estimate.", "example": "2026-01-01 00:00:00" }, "statusUpdatedAt": { "format": "date-time", "type": "string", "description": "The date and time the status was last updated.", "example": "2026-01-01 00:00:00" }, "updated": { "format": "date-time", "type": "string", "description": "The date and time the estimate was last updated.", "example": "2026-01-01 00:00:00" }, "created": { "format": "date-time", "type": "string", "description": "The date and time the estimate was created.", "example": "2026-01-01 00:00:00" } } }, "WebhookTriggerV2Dto": { "type": "object", "properties": { "type": { "type": "string", "description": "The automation event type that triggered this webhook.", "example": "job_created" }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp of when the event was triggered.", "example": "2024-03-15T10:30:00Z" } }, "required": [ "type", "timestamp" ] }, "WebhookMetadataV2Dto": { "type": "object", "properties": { "automationId": { "type": "string", "description": "The automation rule ID that triggered this webhook.", "example": "auto_789" }, "ruleName": { "type": "string", "description": "The name of the automation rule.", "example": "New Job Notification" } }, "required": [ "automationId", "ruleName" ] }, "WebhookJobPayloadV2Dto": { "type": "object", "properties": { "trigger": { "description": "The trigger event that fired this webhook.", "allOf": [ { "$ref": "#/components/schemas/WebhookTriggerV2Dto" } ] }, "data": { "description": "The full job entity at the time of the event.", "allOf": [ { "$ref": "#/components/schemas/ResponseJobV2Dto" } ] }, "metadata": { "description": "Metadata about the automation rule that triggered this webhook.", "allOf": [ { "$ref": "#/components/schemas/WebhookMetadataV2Dto" } ] } }, "required": [ "trigger", "data", "metadata" ] }, "WebhookLeadPayloadV2Dto": { "type": "object", "properties": { "trigger": { "description": "The trigger event that fired this webhook.", "allOf": [ { "$ref": "#/components/schemas/WebhookTriggerV2Dto" } ] }, "data": { "description": "The full lead entity at the time of the event.", "allOf": [ { "$ref": "#/components/schemas/ResponseLeadV2Dto" } ] }, "metadata": { "description": "Metadata about the automation rule that triggered this webhook.", "allOf": [ { "$ref": "#/components/schemas/WebhookMetadataV2Dto" } ] } }, "required": [ "trigger", "data", "metadata" ] }, "WebhookInvoicePayloadV2Dto": { "type": "object", "properties": { "trigger": { "description": "The trigger event that fired this webhook.", "allOf": [ { "$ref": "#/components/schemas/WebhookTriggerV2Dto" } ] }, "data": { "description": "The full invoice entity at the time of the event.", "allOf": [ { "$ref": "#/components/schemas/ResponseInvoiceV2Dto" } ] }, "metadata": { "description": "Metadata about the automation rule that triggered this webhook.", "allOf": [ { "$ref": "#/components/schemas/WebhookMetadataV2Dto" } ] } }, "required": [ "trigger", "data", "metadata" ] }, "WebhookEstimatePayloadV2Dto": { "type": "object", "properties": { "trigger": { "description": "The trigger event that fired this webhook.", "allOf": [ { "$ref": "#/components/schemas/WebhookTriggerV2Dto" } ] }, "data": { "description": "The full estimate entity at the time of the event.", "allOf": [ { "$ref": "#/components/schemas/ResponseOneEstimateV2Dto" } ] }, "metadata": { "description": "Metadata about the automation rule that triggered this webhook.", "allOf": [ { "$ref": "#/components/schemas/WebhookMetadataV2Dto" } ] } }, "required": [ "trigger", "data", "metadata" ] } } }, "x-webhooks": { "job-event": { "post": { "tags": [ "Webhooks" ], "summary": "Job webhook payload", "description": "Workiz **POST**s this payload to your configured webhook URL whenever a **job** automation rule fires.\n\nTo set up a webhook, go to the Workiz Automation Center, select a trigger event (e.g. `job_created`), add optional conditions, then choose **post webhook** as the action. See the Workiz help article for a step-by-step guide.\n\nThe `trigger.type` value reflects the automation event (e.g. `job_created`). The `data` object is identical to the response from the corresponding GET /:id endpoint.\n\n**Authorization header**: When an auth key is configured on the automation rule, Workiz includes `Authorization: Bearer ` in the request. This header is optional — your endpoint does not need to require it.\n\nYour endpoint should return any **2xx** status code to acknowledge receipt.", "parameters": [ { "in": "header", "name": "Authorization", "description": "Optional Bearer token sent by Workiz when an auth key is configured on the automation rule.", "schema": { "type": "string", "example": "Bearer sk_live_1234567890" }, "required": false } ], "requestBody": { "description": "The webhook payload Workiz sends to your endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookJobPayloadV2Dto" } } } }, "responses": { "200": { "description": "Return any 2xx to acknowledge receipt." } } } }, "lead-event": { "post": { "tags": [ "Webhooks" ], "summary": "Lead webhook payload", "description": "Workiz **POST**s this payload to your configured webhook URL whenever a **lead** automation rule fires.\n\nTo set up a webhook, go to the Workiz Automation Center, select a trigger event (e.g. `lead_created`), add optional conditions, then choose **post webhook** as the action. See the Workiz help article for a step-by-step guide.\n\nThe `trigger.type` value reflects the automation event (e.g. `lead_created`). The `data` object is identical to the response from the corresponding GET /:id endpoint.\n\n**Authorization header**: When an auth key is configured on the automation rule, Workiz includes `Authorization: Bearer ` in the request. This header is optional — your endpoint does not need to require it.\n\nYour endpoint should return any **2xx** status code to acknowledge receipt.", "parameters": [ { "in": "header", "name": "Authorization", "description": "Optional Bearer token sent by Workiz when an auth key is configured on the automation rule.", "schema": { "type": "string", "example": "Bearer sk_live_1234567890" }, "required": false } ], "requestBody": { "description": "The webhook payload Workiz sends to your endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookLeadPayloadV2Dto" } } } }, "responses": { "200": { "description": "Return any 2xx to acknowledge receipt." } } } }, "invoice-event": { "post": { "tags": [ "Webhooks" ], "summary": "Invoice webhook payload", "description": "Workiz **POST**s this payload to your configured webhook URL whenever a **invoice** automation rule fires.\n\nTo set up a webhook, go to the Workiz Automation Center, select a trigger event (e.g. `invoice_sent`), add optional conditions, then choose **post webhook** as the action. See the Workiz help article for a step-by-step guide.\n\nThe `trigger.type` value reflects the automation event (e.g. `invoice_sent`). The `data` object is identical to the response from the corresponding GET /:id endpoint.\n\n**Authorization header**: When an auth key is configured on the automation rule, Workiz includes `Authorization: Bearer ` in the request. This header is optional — your endpoint does not need to require it.\n\nYour endpoint should return any **2xx** status code to acknowledge receipt.", "parameters": [ { "in": "header", "name": "Authorization", "description": "Optional Bearer token sent by Workiz when an auth key is configured on the automation rule.", "schema": { "type": "string", "example": "Bearer sk_live_1234567890" }, "required": false } ], "requestBody": { "description": "The webhook payload Workiz sends to your endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInvoicePayloadV2Dto" } } } }, "responses": { "200": { "description": "Return any 2xx to acknowledge receipt." } } } }, "estimate-event": { "post": { "tags": [ "Webhooks" ], "summary": "Estimate webhook payload", "description": "Workiz **POST**s this payload to your configured webhook URL whenever a **estimate** automation rule fires.\n\nTo set up a webhook, go to the Workiz Automation Center, select a trigger event (e.g. `estimate_created`), add optional conditions, then choose **post webhook** as the action. See the Workiz help article for a step-by-step guide.\n\nThe `trigger.type` value reflects the automation event (e.g. `estimate_created`). The `data` object is identical to the response from the corresponding GET /:id endpoint.\n\n**Authorization header**: When an auth key is configured on the automation rule, Workiz includes `Authorization: Bearer ` in the request. This header is optional — your endpoint does not need to require it.\n\nYour endpoint should return any **2xx** status code to acknowledge receipt.", "parameters": [ { "in": "header", "name": "Authorization", "description": "Optional Bearer token sent by Workiz when an auth key is configured on the automation rule.", "schema": { "type": "string", "example": "Bearer sk_live_1234567890" }, "required": false } ], "requestBody": { "description": "The webhook payload Workiz sends to your endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEstimatePayloadV2Dto" } } } }, "responses": { "200": { "description": "Return any 2xx to acknowledge receipt." } } } } } }