{ "openapi": "3.1.0", "info": { "title": "ServiceM8 API", "description": "Move your app forward with the ServiceM8 API\n\n\n\n## Limits and Throttling\nTo ensure continuous quality of service, API usage can be subject to throttling. The throttle will be applied once an API consumer reaches a certain \nthreshold in terms of a maximum number of requests per minute. Most clients will never hit this threshold, but those that do, will get met by a \nHTTP 429 Too Many Requests response code. \n \nThere is a limit of 180 requests per minute, if you reach this you will receive a HTTP 429 with a text body of \"Number of allowed API requests per minute exceeded\".\nThere is a limit of 20000 requests per day, if you reach this you will receive a HTTP 429 with a text body of \"Number of allowed API requests per day exceeded\".\n\nWe encourage all API developers to anticipate this error, and take appropriate measures like e.g. using a cached value from a previous call, or passing on a message to the end user that gets subjected to this behaviour (if any).\n\nLimits are per Addon per account.\n", "termsOfService": "https://www.servicem8.com/terms-of-service", "version": "1.0.0" }, "servers": [ { "url": "https://api.servicem8.com/api_1.0" } ], "security": [ { "apiKey": [] }, { "oauth2": [] } ], "paths": { "/allocationwindow.json": { "get": { "tags": [ "Allocation Windows" ], "operationId": "listAllocationWindows", "summary": "List all Allocation Windows", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_schedule**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_schedule" ] } ], "responses": { "200": { "description": "An array of Allocation Windows", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AllocationWindow" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-d673-44dc-847c-231feb6f05bb", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string", "start_time": "string", "end_time": "string", "sort_priority": "string" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Allocation Windows" ], "operationId": "createAllocationWindows", "summary": "Create a new Allocation Window", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_schedule**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_schedule" ] } ], "parameters": [], "requestBody": { "description": "Allocation Window record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllocationWindow" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Allocation Window record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/allocationwindow/{uuid}.json": { "get": { "tags": [ "Allocation Windows" ], "operationId": "getAllocationWindows", "summary": "Retrieve an Allocation Window", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_schedule**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_schedule" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Allocation Window", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Allocation Window record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllocationWindow" }, "examples": { "success": { "value": { "uuid": "123e4567-dc22-42c0-86c9-231fed67accb", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string", "start_time": "string", "end_time": "string", "sort_priority": "string" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Allocation Windows" ], "operationId": "updateAllocationWindows", "summary": "Update an Allocation Window", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_schedule**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_schedule" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Allocation Window", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Allocation Window fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllocationWindow" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Allocation Windows" ], "operationId": "deleteAllocationWindows", "summary": "Delete an Allocation Window", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_schedule**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_schedule" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Allocation Window", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Allocation Window successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/asset.json": { "get": { "tags": [ "Assets" ], "operationId": "listAssets", "summary": "List all Assets", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_assets**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_assets" ] } ], "responses": { "200": { "description": "An array of Assets", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-f680-4a11-80aa-231fe2a09bab", "active": 1, "edit_date": "2025-08-01 12:00:00", "company_uuid": "123e4567-48ab-4a36-999e-231fe703e50b", "asset_code": "string", "asset_type_uuid": "123e4567-49e3-4973-b26d-231fe7cf6f8b", "name": "string", "lat": "number", "lng": "number", "geo_timestamp": "2025-08-01 12:00:00", "altitude": "number", "field_data": [ { "uuid": "string", "fieldType": "string", "fieldName": "string", "fieldValue": "string", "sortOrder": "number" } ] } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/asset/{uuid}.json": { "get": { "tags": [ "Assets" ], "operationId": "getAssets", "summary": "Retrieve an Asset", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_assets**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_assets" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Asset", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Asset record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" }, "examples": { "success": { "value": { "uuid": "123e4567-33d8-4f80-ac48-231fe537c21b", "active": 1, "edit_date": "2025-08-01 12:00:00", "company_uuid": "123e4567-b8ef-43af-849c-231fe5d1116b", "asset_code": "string", "asset_type_uuid": "123e4567-c6f3-4b5e-93d4-231feb28602b", "name": "string", "lat": "number", "lng": "number", "geo_timestamp": "2025-08-01 12:00:00", "altitude": "number", "field_data": [ { "uuid": "string", "fieldType": "string", "fieldName": "string", "fieldValue": "string", "sortOrder": "number" } ] } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Assets" ], "operationId": "updateAssets", "summary": "Update an Asset", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_assets**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_assets" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Asset", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Asset fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Assets" ], "operationId": "deleteAssets", "summary": "Delete an Asset", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_assets**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_assets" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Asset", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Asset successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/assettype.json": { "get": { "tags": [ "Asset Types" ], "operationId": "listAssetTypes", "summary": "List all Asset Types", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_assets**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_assets" ] } ], "responses": { "200": { "description": "An array of Asset Types", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AssetType" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-5fcd-4b40-aaff-231feb508e7b", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Asset Types" ], "operationId": "createAssetTypes", "summary": "Create a new Asset Type", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_assets**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_assets" ] } ], "parameters": [], "requestBody": { "description": "Asset Type record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetType" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Asset Type record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/assettype/{uuid}.json": { "get": { "tags": [ "Asset Types" ], "operationId": "getAssetTypes", "summary": "Retrieve an Asset Type", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_assets**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_assets" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Asset Type", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Asset Type record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetType" }, "examples": { "success": { "value": { "uuid": "123e4567-3df3-45ca-b68b-231fe82fa6db", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Asset Types" ], "operationId": "updateAssetTypes", "summary": "Update an Asset Type", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_assets**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_assets" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Asset Type", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Asset Type fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetType" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Asset Types" ], "operationId": "deleteAssetTypes", "summary": "Delete an Asset Type", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_assets**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_assets" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Asset Type", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Asset Type successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/assettypefield.json": { "get": { "tags": [ "Asset Type Fields" ], "operationId": "listAssetTypeFields", "summary": "List all Asset Type Fields", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_assets**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_assets" ] } ], "responses": { "200": { "description": "An array of Asset Type Fields", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AssetTypeField" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-2b75-4cc9-a446-231fe6894bbb", "active": 1, "edit_date": "2025-08-01 12:00:00", "asset_type_uuid": "123e4567-d31f-481c-a7d8-231fea03e31b", "name": "string", "field_data": { "fieldType": "string", "mandatory": "string", "choices": [ "string" ] }, "sort_order": "string" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Asset Type Fields" ], "operationId": "createAssetTypeFields", "summary": "Create a new Asset Type Field", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_assets**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_assets" ] } ], "parameters": [], "requestBody": { "description": "Asset Type Field record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetTypeField" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Asset Type Field record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/assettypefield/{uuid}.json": { "get": { "tags": [ "Asset Type Fields" ], "operationId": "getAssetTypeFields", "summary": "Retrieve an Asset Type Field", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_assets**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_assets" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Asset Type Field", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Asset Type Field record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetTypeField" }, "examples": { "success": { "value": { "uuid": "123e4567-643d-49fb-8269-231fe7f0b38b", "active": 1, "edit_date": "2025-08-01 12:00:00", "asset_type_uuid": "123e4567-46aa-44ed-bef9-231fea088f1b", "name": "string", "field_data": { "fieldType": "string", "mandatory": "string", "choices": [ "string" ] }, "sort_order": "string" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Asset Type Fields" ], "operationId": "updateAssetTypeFields", "summary": "Update an Asset Type Field", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_assets**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_assets" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Asset Type Field", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Asset Type Field fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetTypeField" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Asset Type Fields" ], "operationId": "deleteAssetTypeFields", "summary": "Delete an Asset Type Field", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_assets**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_assets" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Asset Type Field", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Asset Type Field successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/badge.json": { "get": { "tags": [ "Badges" ], "operationId": "listBadges", "summary": "List all Badges", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_badges**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_badges" ] } ], "responses": { "200": { "description": "An array of Badges", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Badge" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-4d50-48e8-bc13-231fede4028b", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string", "automatically_allocated": "string", "file_name": "string", "regarding_form_uuid": "123e4567-dd3b-4f1e-b5dc-231fe0826dfb", "regarding_asset_type_uuid": "123e4567-4df7-4e7d-9be5-231fef1160eb" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Badges" ], "operationId": "createBadges", "summary": "Create a new Badge", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_badges**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_badges" ] } ], "parameters": [], "requestBody": { "description": "Badge record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Badge" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Badge record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/badge/{uuid}.json": { "get": { "tags": [ "Badges" ], "operationId": "getBadges", "summary": "Retrieve a Badge", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_badges**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_badges" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Badge", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Badge record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Badge" }, "examples": { "success": { "value": { "uuid": "123e4567-83b8-4ae2-b3f4-231feb43f54b", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string", "automatically_allocated": "string", "file_name": "string", "regarding_form_uuid": "123e4567-a3b5-4a15-9643-231fe674870b", "regarding_asset_type_uuid": "123e4567-f958-46a3-a920-231fe446b66b" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Badges" ], "operationId": "updateBadges", "summary": "Update a Badge", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_badges**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_badges" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Badge", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Badge fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Badge" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Badges" ], "operationId": "deleteBadges", "summary": "Delete a Badge", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_badges**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_badges" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Badge", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Badge successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/category.json": { "get": { "tags": [ "Categories" ], "operationId": "listCategories", "summary": "List all Categories", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_job_categories**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_job_categories" ] } ], "responses": { "200": { "description": "An array of Categories", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "examples": { "success": { "value": [ { "name": "string", "colour": "string", "uuid": "123e4567-1cfb-4348-a575-231fef704dcb", "active": 1, "edit_date": "2025-08-01 12:00:00" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Categories" ], "operationId": "createCategories", "summary": "Create a new Category", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_categories**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_categories" ] } ], "parameters": [], "requestBody": { "description": "Category record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Category record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/category/{uuid}.json": { "get": { "tags": [ "Categories" ], "operationId": "getCategories", "summary": "Retrieve a Category", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_job_categories**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_job_categories" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Category", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Category record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" }, "examples": { "success": { "value": { "name": "string", "colour": "string", "uuid": "123e4567-1cd5-4535-88fe-231fe37699eb", "active": 1, "edit_date": "2025-08-01 12:00:00" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Categories" ], "operationId": "updateCategories", "summary": "Update a Category", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_categories**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_categories" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Category", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Category fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Categories" ], "operationId": "deleteCategories", "summary": "Delete a Category", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_categories**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_categories" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Category", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Category successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/company.json": { "get": { "tags": [ "Clients" ], "operationId": "listClients", "summary": "List all Clients", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_customers**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_customers" ] } ], "responses": { "200": { "description": "An array of Clients", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "examples": { "success": { "value": [ { "name": "string", "abn_number": "string", "address": "string", "billing_address": "string", "parent_company_uuid": "string", "uuid": "123e4567-5d7a-46ca-bf22-231fef7d264b", "active": 1, "edit_date": "2025-08-01 12:00:00", "website": "string", "is_individual": "string", "address_street": "string", "address_city": "string", "address_state": "string", "address_postcode": "string", "address_country": "string", "fax_number": "string", "badges": "string", "tax_rate_uuid": "123e4567-0031-4f77-85e5-231fe8a5045b", "billing_attention": "string", "payment_terms": "string" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Clients" ], "operationId": "createClients", "summary": "Create a new Client", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_customers**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_customers" ] } ], "parameters": [], "requestBody": { "description": "Client record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Client record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/company/{uuid}.json": { "get": { "tags": [ "Clients" ], "operationId": "getClients", "summary": "Retrieve a Client", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_customers**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_customers" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Client", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Client record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" }, "examples": { "success": { "value": { "name": "string", "abn_number": "string", "address": "string", "billing_address": "string", "parent_company_uuid": "string", "uuid": "123e4567-5e53-41d2-ad85-231fef19facb", "active": 1, "edit_date": "2025-08-01 12:00:00", "website": "string", "is_individual": "string", "address_street": "string", "address_city": "string", "address_state": "string", "address_postcode": "string", "address_country": "string", "fax_number": "string", "badges": "string", "tax_rate_uuid": "123e4567-07f9-44ee-a90f-231fe629a96b", "billing_attention": "string", "payment_terms": "string" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Clients" ], "operationId": "updateClients", "summary": "Update a Client", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_customers**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_customers" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Client", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Client fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Clients" ], "operationId": "deleteClients", "summary": "Delete a Client", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_customers**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_customers" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Client", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Client successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/companycontact.json": { "get": { "tags": [ "Company Contacts" ], "operationId": "listCompanyContacts", "summary": "List all Company Contacts", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_customer_contacts**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_customer_contacts" ] } ], "responses": { "200": { "description": "An array of Company Contacts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyContact" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-3598-4b5e-94f3-231fe1c21b1b", "active": 1, "edit_date": "2025-08-01 12:00:00", "company_uuid": "123e4567-907a-439e-ac96-231fed38165b", "first": "string", "last": "string", "phone": "string", "mobile": "string", "email": "string", "type": "string", "is_primary_contact": "string" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Company Contacts" ], "operationId": "createCompanyContacts", "summary": "Create a new Company Contact", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_customer_contacts**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_customer_contacts" ] } ], "parameters": [], "requestBody": { "description": "Company Contact record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyContact" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Company Contact record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/companycontact/{uuid}.json": { "get": { "tags": [ "Company Contacts" ], "operationId": "getCompanyContacts", "summary": "Retrieve a Company Contact", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_customer_contacts**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_customer_contacts" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Company Contact", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Company Contact record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyContact" }, "examples": { "success": { "value": { "uuid": "123e4567-7259-4d61-80fb-231fe99b7d8b", "active": 1, "edit_date": "2025-08-01 12:00:00", "company_uuid": "123e4567-1874-4d42-bf41-231fe515175b", "first": "string", "last": "string", "phone": "string", "mobile": "string", "email": "string", "type": "string", "is_primary_contact": "string" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Company Contacts" ], "operationId": "updateCompanyContacts", "summary": "Update a Company Contact", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_customer_contacts**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_customer_contacts" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Company Contact", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Company Contact fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyContact" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Company Contacts" ], "operationId": "deleteCompanyContacts", "summary": "Delete a Company Contact", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_customer_contacts**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_customer_contacts" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Company Contact", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Company Contact successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/documenttemplate.json": { "get": { "tags": [ "Document Templates" ], "operationId": "listDocumentTemplates", "summary": "List all Document Templates", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_templates**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_templates" ] } ], "responses": { "200": { "description": "An array of Document Templates", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentTemplate" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-8020-4ce8-b279-231fe4b94f9b", "active": 1, "edit_date": "2025-08-01 12:00:00", "template_type": "string", "related_object": "string", "name": "string" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Document Templates" ], "operationId": "createDocumentTemplates", "summary": "Create a new Document Template", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_templates**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_templates" ] } ], "parameters": [], "requestBody": { "description": "Document Template record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentTemplate" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Document Template record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/documenttemplate/{uuid}.json": { "get": { "tags": [ "Document Templates" ], "operationId": "getDocumentTemplates", "summary": "Retrieve a Document Template", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_templates**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_templates" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Document Template", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Document Template record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentTemplate" }, "examples": { "success": { "value": { "uuid": "123e4567-876b-4a3a-a453-231feb26d32b", "active": 1, "edit_date": "2025-08-01 12:00:00", "template_type": "string", "related_object": "string", "name": "string" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Document Templates" ], "operationId": "updateDocumentTemplates", "summary": "Update a Document Template", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_templates**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_templates" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Document Template", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Document Template fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentTemplate" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Document Templates" ], "operationId": "deleteDocumentTemplates", "summary": "Delete a Document Template", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_templates**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_templates" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Document Template", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Document Template successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/emailtemplate.json": { "get": { "tags": [ "Email Templates" ], "operationId": "listEmailTemplates", "summary": "List all Email Templates", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_templates**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_templates" ] } ], "responses": { "200": { "description": "An array of Email Templates", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EmailTemplate" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-5847-45a8-9fd9-231feec1cf2b", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string", "subject": "string", "message": "string" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Email Templates" ], "operationId": "createEmailTemplates", "summary": "Create a new Email Template", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_templates**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_templates" ] } ], "parameters": [], "requestBody": { "description": "Email Template record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplate" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Email Template record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/emailtemplate/{uuid}.json": { "get": { "tags": [ "Email Templates" ], "operationId": "getEmailTemplates", "summary": "Retrieve an Email Template", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_templates**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_templates" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Email Template", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Email Template record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplate" }, "examples": { "success": { "value": { "uuid": "123e4567-ee0c-4680-9e28-231fe2ce729b", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string", "subject": "string", "message": "string" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Email Templates" ], "operationId": "updateEmailTemplates", "summary": "Update an Email Template", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_templates**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_templates" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Email Template", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Email Template fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplate" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Email Templates" ], "operationId": "deleteEmailTemplates", "summary": "Delete an Email Template", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_templates**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_templates" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Email Template", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Email Template successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/feedback.json": { "get": { "tags": [ "Feedback" ], "operationId": "listFeedback", "summary": "List all Feedback", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_feedback**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_feedback" ] } ], "responses": { "200": { "description": "An array of Feedback", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Feedback" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-21e2-4a85-8cf7-231fe468bd9b", "active": 1, "edit_date": "2025-08-01 12:00:00", "timestamp": "string", "related_object": "string", "related_object_uuid": "123e4567-4290-4cc0-867d-231fe6eb7a0b", "rating": "string", "comment": "string" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Feedback" ], "operationId": "createFeedback", "summary": "Create a new Feedback", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_feedback**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_feedback" ] } ], "parameters": [], "requestBody": { "description": "Feedback record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Feedback" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Feedback record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/feedback/{uuid}.json": { "get": { "tags": [ "Feedback" ], "operationId": "getFeedback", "summary": "Retrieve a Feedback", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_feedback**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_feedback" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Feedback", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Feedback record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Feedback" }, "examples": { "success": { "value": { "uuid": "123e4567-8acd-4d3d-8ef7-231fe483fadb", "active": 1, "edit_date": "2025-08-01 12:00:00", "timestamp": "string", "related_object": "string", "related_object_uuid": "123e4567-08ce-402a-93a1-231fe0b3d55b", "rating": "string", "comment": "string" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Feedback" ], "operationId": "updateFeedback", "summary": "Update a Feedback", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_feedback**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_feedback" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Feedback", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Feedback fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Feedback" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Feedback" ], "operationId": "deleteFeedback", "summary": "Delete a Feedback", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_feedback**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_feedback" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Feedback", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Feedback successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/form.json": { "get": { "tags": [ "Forms" ], "operationId": "listForms", "summary": "List all Forms", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_forms**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_forms" ] } ], "responses": { "200": { "description": "An array of Forms", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Form" } }, "examples": { "success": { "value": [ { "name": "string", "document_template_uuid": "123e4567-239c-4809-a39e-231fe163d37b", "can_be_used_independently": "string", "badge_mandatory_state": "string", "template_fields": [ { "name": "string", "fieldType": "string", "value": "string", "sortOrder": "string" } ], "uuid": "123e4567-7f01-4aff-b77a-231fe8837b5b", "active": 1, "edit_date": "2025-08-01 12:00:00", "badge_name": "string" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Forms" ], "operationId": "createForms", "summary": "Create a new Form", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_forms**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_forms" ] } ], "parameters": [], "requestBody": { "description": "Form record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Form" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Form record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/form/{uuid}.json": { "get": { "tags": [ "Forms" ], "operationId": "getForms", "summary": "Retrieve a Form", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_forms**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_forms" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Form", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Form record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Form" }, "examples": { "success": { "value": { "name": "string", "document_template_uuid": "123e4567-3006-4bf1-b61c-231fe52b543b", "can_be_used_independently": "string", "badge_mandatory_state": "string", "template_fields": [ { "name": "string", "fieldType": "string", "value": "string", "sortOrder": "string" } ], "uuid": "123e4567-df10-4c0b-b064-231fe917e78b", "active": 1, "edit_date": "2025-08-01 12:00:00", "badge_name": "string" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Forms" ], "operationId": "updateForms", "summary": "Update a Form", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_forms**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_forms" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Form", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Form fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Form" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Forms" ], "operationId": "deleteForms", "summary": "Delete a Form", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_forms**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_forms" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Form", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Form successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/formfield.json": { "get": { "tags": [ "Form Fields" ], "operationId": "listFormFields", "summary": "List all Form Fields", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_forms**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_forms" ] } ], "responses": { "200": { "description": "An array of Form Fields", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FormField" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-212f-4029-8402-231febefbfdb", "active": 1, "edit_date": "2025-08-01 12:00:00", "form_uuid": "123e4567-edb9-4c36-a3f1-231fec5eef5b", "name": "string", "field_data_json": "string", "sort_order": "string" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Form Fields" ], "operationId": "createFormFields", "summary": "Create a new Form Field", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_forms**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_forms" ] } ], "parameters": [], "requestBody": { "description": "Form Field record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormField" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Form Field record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/formfield/{uuid}.json": { "get": { "tags": [ "Form Fields" ], "operationId": "getFormFields", "summary": "Retrieve a Form Field", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_forms**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_forms" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Form Field", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Form Field record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormField" }, "examples": { "success": { "value": { "uuid": "123e4567-221c-462b-a4b1-231fe903077b", "active": 1, "edit_date": "2025-08-01 12:00:00", "form_uuid": "123e4567-7abc-4187-b4d0-231fe5b70e9b", "name": "string", "field_data_json": "string", "sort_order": "string" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Form Fields" ], "operationId": "updateFormFields", "summary": "Update a Form Field", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_forms**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_forms" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Form Field", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Form Field fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormField" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Form Fields" ], "operationId": "deleteFormFields", "summary": "Delete a Form Field", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_forms**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_forms" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Form Field", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Form Field successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/formresponse.json": { "get": { "tags": [ "Form Responses" ], "operationId": "listFormResponses", "summary": "List all Form Responses", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_forms**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_forms" ] } ], "responses": { "200": { "description": "An array of Form Responses", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FormResponse" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-1f2f-4143-9b5a-231fec5727db", "active": 1, "edit_date": "2025-08-01 12:00:00", "form_uuid": "123e4567-08b7-4c87-9bf5-231fec827f7b", "staff_uuid": "123e4567-15b6-4a75-abf6-231fe0401fbb", "regarding_object": "string", "regarding_object_uuid": "123e4567-209b-4a4f-af1e-231fe84144ab", "field_data": "string", "timestamp": "2025-08-01 12:00:00", "form_by_staff_uuid": "123e4567-e0f1-4d6f-ac4f-231fe7a52deb", "document_attachment_uuid": "123e4567-c700-4219-9bb5-231fecb008eb", "asset_uuid": "123e4567-4daf-4b1f-a018-231febadc59b" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/formresponse/{uuid}.json": { "get": { "tags": [ "Form Responses" ], "operationId": "getFormResponses", "summary": "Retrieve a Form Response", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_forms**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_forms" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Form Response", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Form Response record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormResponse" }, "examples": { "success": { "value": { "uuid": "123e4567-5272-4071-af39-231fe46f977b", "active": 1, "edit_date": "2025-08-01 12:00:00", "form_uuid": "123e4567-4cf2-4c25-8322-231fe450337b", "staff_uuid": "123e4567-b449-4f35-94f2-231fe5a54c7b", "regarding_object": "string", "regarding_object_uuid": "123e4567-50ba-4ee3-8e84-231fe9d4e17b", "field_data": "string", "timestamp": "2025-08-01 12:00:00", "form_by_staff_uuid": "123e4567-8b12-4f0f-bf75-231fe812199b", "document_attachment_uuid": "123e4567-386b-4c19-b614-231febdb85fb", "asset_uuid": "123e4567-becc-426b-ae4d-231fe8b13e3b" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/job.json": { "get": { "tags": [ "Jobs" ], "operationId": "listJobs", "summary": "List all Jobs", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_jobs**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_jobs" ] } ], "responses": { "200": { "description": "An array of Jobs", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "examples": { "success": { "value": [ { "created_by_staff_uuid": "123e4567-15d0-4d60-a118-231fed00864b", "date": "YYYY-MM-DD", "company_uuid": "123e4567-0c4b-4ef0-9716-231feb4f783b", "billing_address": "string", "status": "string", "lng": "number", "lat": "number", "payment_date": "2025-08-01 12:00:00", "payment_actioned_by_uuid": "123e4567-7e7a-4e09-855b-231fee1765cb", "payment_method": "string", "payment_amount": "string", "category_uuid": "123e4567-4b1d-4b41-a1a9-231fedbe95cb", "payment_note": "string", "geo_is_valid": "string", "purchase_order_number": "string", "invoice_sent": "string", "invoice_sent_stamp": "2025-08-01 12:00:00", "ready_to_invoice": "string", "ready_to_invoice_stamp": "string", "geo_country": "string", "geo_postcode": "string", "geo_state": "string", "geo_city": "string", "geo_street": "string", "geo_number": "string", "queue_uuid": "123e4567-0e0a-4fa0-840c-231fe20ed00b", "queue_expiry_date": "2025-08-01 12:00:00", "queue_assigned_staff_uuid": "123e4567-7591-4f07-99a5-231fe7c80ceb", "badges": "string", "quote_date": "2025-08-01 12:00:00", "quote_sent": "string", "quote_sent_stamp": "2025-08-01 12:00:00", "work_order_date": "2025-08-01 12:00:00", "active_network_request_uuid": "string", "related_knowledge_articles": "string", "uuid": "123e4567-caae-42d1-a1cc-231feb55677b", "active": 1, "edit_date": "2025-08-01 12:00:00", "job_address": "string", "job_description": "string", "work_done_description": "string", "generated_job_id": "string", "total_invoice_amount": "string", "payment_processed": "string", "payment_processed_stamp": "2025-08-01 12:00:00", "payment_received": "string", "payment_received_stamp": "2025-08-01 12:00:00", "completion_date": "2025-08-01 12:00:00", "completion_actioned_by_uuid": "123e4567-acdb-48c1-ac5b-231feb52230b", "unsuccessful_date": "2025-08-01 12:00:00", "job_is_scheduled_until_stamp": "2025-08-01 12:00:00" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Jobs" ], "operationId": "createJobs", "summary": "Create a new Job", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **create_jobs**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "create_jobs" ] } ], "parameters": [], "requestBody": { "description": "Job record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Job record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/job/{uuid}.json": { "get": { "tags": [ "Jobs" ], "operationId": "getJobs", "summary": "Retrieve a Job", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_jobs**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_jobs" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "examples": { "success": { "value": { "created_by_staff_uuid": "123e4567-519b-462f-90ca-231feb5141db", "date": "YYYY-MM-DD", "company_uuid": "123e4567-fad6-4ef0-9f31-231fef563adb", "billing_address": "string", "status": "string", "lng": "number", "lat": "number", "payment_date": "2025-08-01 12:00:00", "payment_actioned_by_uuid": "123e4567-374f-4df3-bfdf-231feaf3735b", "payment_method": "string", "payment_amount": "string", "category_uuid": "123e4567-5b29-4706-a68e-231fe2374a2b", "payment_note": "string", "geo_is_valid": "string", "purchase_order_number": "string", "invoice_sent": "string", "invoice_sent_stamp": "2025-08-01 12:00:00", "ready_to_invoice": "string", "ready_to_invoice_stamp": "string", "geo_country": "string", "geo_postcode": "string", "geo_state": "string", "geo_city": "string", "geo_street": "string", "geo_number": "string", "queue_uuid": "123e4567-59ca-4ca0-a459-231fe8f47cdb", "queue_expiry_date": "2025-08-01 12:00:00", "queue_assigned_staff_uuid": "123e4567-ab0e-4d18-ac7d-231fe1c124eb", "badges": "string", "quote_date": "2025-08-01 12:00:00", "quote_sent": "string", "quote_sent_stamp": "2025-08-01 12:00:00", "work_order_date": "2025-08-01 12:00:00", "active_network_request_uuid": "string", "related_knowledge_articles": "string", "uuid": "123e4567-0b37-4112-bd2e-231fe9a3e89b", "active": 1, "edit_date": "2025-08-01 12:00:00", "job_address": "string", "job_description": "string", "work_done_description": "string", "generated_job_id": "string", "total_invoice_amount": "string", "payment_processed": "string", "payment_processed_stamp": "2025-08-01 12:00:00", "payment_received": "string", "payment_received_stamp": "2025-08-01 12:00:00", "completion_date": "2025-08-01 12:00:00", "completion_actioned_by_uuid": "123e4567-9c7f-4b2d-9a3e-231fea1f387b", "unsuccessful_date": "2025-08-01 12:00:00", "job_is_scheduled_until_stamp": "2025-08-01 12:00:00" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Jobs" ], "operationId": "updateJobs", "summary": "Update a Job", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_jobs**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_jobs" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Job fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Jobs" ], "operationId": "deleteJobs", "summary": "Delete a Job", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_jobs**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_jobs" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/jobactivity.json": { "get": { "tags": [ "Job Activities" ], "operationId": "listJobActivities", "summary": "List all Job Activities", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_schedule**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_schedule" ] } ], "responses": { "200": { "description": "An array of Job Activities", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JobActivity" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-428f-4357-bc8c-231fe00cff0b", "active": 1, "edit_date": "2025-08-01 12:00:00", "job_uuid": "123e4567-90bb-432f-8fde-231fe7e3670b", "staff_uuid": "123e4567-adc3-43a0-812c-231fe6f9224b", "start_date": "2025-08-01 12:00:00", "end_date": "2025-08-01 12:00:00", "activity_was_scheduled": "string", "activity_was_recorded": "string", "activity_was_automated": "string", "has_been_opened": "string", "has_been_opened_timestamp": "2025-08-01 12:00:00", "travel_time_in_seconds": "string", "travel_distance_in_meters": "string", "allocated_by_staff_uuid": "123e4567-22ba-4b08-934a-231fe7207aeb", "allocated_timestamp": "2025-08-01 12:00:00", "material_uuid": "123e4567-7ed2-454d-8dba-231fe27ff84b", "edit_by_staff_uuid": "123e4567-6d1b-485d-b3a2-231fe4adfb7b" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Job Activities" ], "operationId": "createJobActivities", "summary": "Create a new Job Activity", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_schedule**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_schedule" ] } ], "parameters": [], "requestBody": { "description": "Job Activity record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobActivity" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Job Activity record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/jobactivity/{uuid}.json": { "get": { "tags": [ "Job Activities" ], "operationId": "getJobActivities", "summary": "Retrieve a Job Activity", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_schedule**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_schedule" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Activity", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job Activity record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobActivity" }, "examples": { "success": { "value": { "uuid": "123e4567-2cd5-476b-89ea-231fe267cb5b", "active": 1, "edit_date": "2025-08-01 12:00:00", "job_uuid": "123e4567-a658-4fc0-9e04-231feb2351db", "staff_uuid": "123e4567-02ee-416f-a4ec-231fe29fb38b", "start_date": "2025-08-01 12:00:00", "end_date": "2025-08-01 12:00:00", "activity_was_scheduled": "string", "activity_was_recorded": "string", "activity_was_automated": "string", "has_been_opened": "string", "has_been_opened_timestamp": "2025-08-01 12:00:00", "travel_time_in_seconds": "string", "travel_distance_in_meters": "string", "allocated_by_staff_uuid": "123e4567-1ed9-44a8-bb9e-231fe6d8414b", "allocated_timestamp": "2025-08-01 12:00:00", "material_uuid": "123e4567-8c0f-42c4-b891-231fecb25c0b", "edit_by_staff_uuid": "123e4567-442d-45c0-b699-231fe213ba6b" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Job Activities" ], "operationId": "updateJobActivities", "summary": "Update a Job Activity", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_schedule**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_schedule" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Activity", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Job Activity fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobActivity" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Job Activities" ], "operationId": "deleteJobActivities", "summary": "Delete a Job Activity", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_schedule**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_schedule" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Activity", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job Activity successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/joballocation.json": { "get": { "tags": [ "Job Allocations" ], "operationId": "listJobAllocations", "summary": "List all Job Allocations", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_schedule**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_schedule" ] } ], "responses": { "200": { "description": "An array of Job Allocations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JobAllocation" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-7a24-4f11-8df6-231fee6f3c3b", "active": 1, "edit_date": "2025-08-01 12:00:00", "job_uuid": "123e4567-eec0-43db-8865-231fe7fac8db", "queue_uuid": "123e4567-139e-495b-a6d9-231fe810396b", "staff_uuid": "123e4567-e0e4-431d-ba51-231fea15775b", "allocation_date": "2025-08-01 12:00:00", "allocation_window_uuid": "123e4567-fbd9-45ae-bde7-231fe70af1cb", "allocated_by_staff_uuid": "123e4567-8555-4046-9235-231fe765194b", "allocated_timestamp": "2025-08-01 12:00:00", "expiry_timestamp": "2025-08-01 12:00:00", "read_timestamp": "2025-08-01 12:00:00", "completion_timestamp": "2025-08-01 12:00:00", "estimated_duration": "string", "revised_duration": "string", "sort_priority": "string", "requires_acceptance": "string", "acceptance_status": "string", "acceptance_timestamp": "2025-08-01 12:00:00" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Job Allocations" ], "operationId": "createJobAllocations", "summary": "Create a new Job Allocation", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_schedule**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_schedule" ] } ], "parameters": [], "requestBody": { "description": "Job Allocation record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAllocation" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Job Allocation record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/joballocation/{uuid}.json": { "get": { "tags": [ "Job Allocations" ], "operationId": "getJobAllocations", "summary": "Retrieve a Job Allocation", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_schedule**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_schedule" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Allocation", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job Allocation record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAllocation" }, "examples": { "success": { "value": { "uuid": "123e4567-b6cb-4198-9cca-231fe8fd325b", "active": 1, "edit_date": "2025-08-01 12:00:00", "job_uuid": "123e4567-0d4f-46d6-8830-231fe350a7fb", "queue_uuid": "123e4567-1682-48ae-b7cf-231fe4052f9b", "staff_uuid": "123e4567-430a-4e34-8485-231fe0bae70b", "allocation_date": "2025-08-01 12:00:00", "allocation_window_uuid": "123e4567-29d2-4d46-b7e8-231fe32bb55b", "allocated_by_staff_uuid": "123e4567-4ee5-45dc-a99f-231fefd508eb", "allocated_timestamp": "2025-08-01 12:00:00", "expiry_timestamp": "2025-08-01 12:00:00", "read_timestamp": "2025-08-01 12:00:00", "completion_timestamp": "2025-08-01 12:00:00", "estimated_duration": "string", "revised_duration": "string", "sort_priority": "string", "requires_acceptance": "string", "acceptance_status": "string", "acceptance_timestamp": "2025-08-01 12:00:00" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Job Allocations" ], "operationId": "updateJobAllocations", "summary": "Update a Job Allocation", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_schedule**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_schedule" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Allocation", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Job Allocation fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAllocation" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Job Allocations" ], "operationId": "deleteJobAllocations", "summary": "Delete a Job Allocation", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_schedule**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_schedule" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Allocation", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job Allocation successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/jobchecklist.json": { "get": { "tags": [ "Job Checklists" ], "operationId": "listJobChecklists", "summary": "List all Job Checklists", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_job_checklists**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_job_checklists" ] } ], "responses": { "200": { "description": "An array of Job Checklists", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JobChecklist" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-2b07-453d-b466-231fe8e39fcb", "active": 1, "edit_date": "2025-08-01 12:00:00", "job_uuid": "123e4567-d92b-4497-ad0f-231fe971c31b", "name": "string", "section_name": "string", "item_type": "string", "sort_order": "string", "completed_timestamp": "2025-08-01 12:00:00", "completed_by_staff_uuid": "123e4567-1081-4379-953d-231fe1ae230b", "completed_during_checkin_uuid": "123e4567-ee50-44ab-b428-231fe184a4eb", "reminder_type": "string", "reminder_data": "string", "regarding_object": "string", "regarding_object_uuid": "123e4567-8d70-4e4a-b0ff-231fe2b09f5b", "fulfilled_by_object_name": "string", "fulfilled_by_object_uuid": "123e4567-6f1c-4815-9f60-231fe98cf59b", "assigned_to_staff_uuids": "123e4567-ccc3-4f0c-bf38-231fee56b9eb", "is_locked": "string", "assigned_timestamp": "2025-08-01 12:00:00", "assigned_by_staff_uuid": "123e4567-d83f-415e-8661-231feb8dde0b" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Job Checklists" ], "operationId": "createJobChecklists", "summary": "Create a new Job Checklist", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_checklists**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_checklists" ] } ], "parameters": [], "requestBody": { "description": "Job Checklist record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobChecklist" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Job Checklist record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/jobchecklist/{uuid}.json": { "get": { "tags": [ "Job Checklists" ], "operationId": "getJobChecklists", "summary": "Retrieve a Job Checklist", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_job_checklists**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_job_checklists" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Checklist", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job Checklist record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobChecklist" }, "examples": { "success": { "value": { "uuid": "123e4567-fdd5-40bc-91e0-231fe55fd27b", "active": 1, "edit_date": "2025-08-01 12:00:00", "job_uuid": "123e4567-772a-42fa-82fb-231fe6bd728b", "name": "string", "section_name": "string", "item_type": "string", "sort_order": "string", "completed_timestamp": "2025-08-01 12:00:00", "completed_by_staff_uuid": "123e4567-80e4-45ae-83c4-231fed8db8eb", "completed_during_checkin_uuid": "123e4567-ef4e-4726-8223-231fe29aa57b", "reminder_type": "string", "reminder_data": "string", "regarding_object": "string", "regarding_object_uuid": "123e4567-a04e-48b5-ad43-231feca092cb", "fulfilled_by_object_name": "string", "fulfilled_by_object_uuid": "123e4567-ebdc-4671-a694-231fede5df3b", "assigned_to_staff_uuids": "123e4567-772b-44e7-8856-231fe9a0bc2b", "is_locked": "string", "assigned_timestamp": "2025-08-01 12:00:00", "assigned_by_staff_uuid": "123e4567-e671-4027-ab35-231fe07c00fb" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Job Checklists" ], "operationId": "updateJobChecklists", "summary": "Update a Job Checklist", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_checklists**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_checklists" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Checklist", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Job Checklist fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobChecklist" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Job Checklists" ], "operationId": "deleteJobChecklists", "summary": "Delete a Job Checklist", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_checklists**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_checklists" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Checklist", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job Checklist successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/jobcontact.json": { "get": { "tags": [ "Job Contacts" ], "operationId": "listJobContacts", "summary": "List all Job Contacts", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_job_contacts**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_job_contacts" ] } ], "responses": { "200": { "description": "An array of Job Contacts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JobContact" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-d373-4279-94fb-231fe4ff50eb", "active": 1, "edit_date": "2025-08-01 12:00:00", "job_uuid": "123e4567-8bdc-4b94-994a-231fe90d2bfb", "first": "string", "last": "string", "phone": "string", "mobile": "string", "email": "string", "type": "string", "is_primary_contact": "string" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Job Contacts" ], "operationId": "createJobContacts", "summary": "Create a new Job Contact", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_contacts**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_contacts" ] } ], "parameters": [], "requestBody": { "description": "Job Contact record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobContact" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Job Contact record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/jobcontact/{uuid}.json": { "get": { "tags": [ "Job Contacts" ], "operationId": "getJobContacts", "summary": "Retrieve a Job Contact", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_job_contacts**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_job_contacts" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Contact", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job Contact record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobContact" }, "examples": { "success": { "value": { "uuid": "123e4567-7232-46ba-b1ee-231fe3d2ecdb", "active": 1, "edit_date": "2025-08-01 12:00:00", "job_uuid": "123e4567-63ea-4ed0-a1b9-231fe4c07f0b", "first": "string", "last": "string", "phone": "string", "mobile": "string", "email": "string", "type": "string", "is_primary_contact": "string" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Job Contacts" ], "operationId": "updateJobContacts", "summary": "Update a Job Contact", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_contacts**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_contacts" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Contact", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Job Contact fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobContact" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Job Contacts" ], "operationId": "deleteJobContacts", "summary": "Delete a Job Contact", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_contacts**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_contacts" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Contact", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job Contact successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/jobmaterial.json": { "get": { "tags": [ "Job Materials" ], "operationId": "listJobMaterials", "summary": "List all Job Materials", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_job_materials**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_job_materials" ] } ], "responses": { "200": { "description": "An array of Job Materials", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JobMaterial" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-7ba7-47ad-9ae8-231fe7ab461b", "active": 1, "edit_date": "2025-08-01 12:00:00", "job_uuid": "123e4567-94f0-424a-b635-231febc7d5bb", "material_uuid": "123e4567-002b-4897-a539-231feb93709b", "name": "string", "quantity": "string", "price": "string", "displayed_amount": "string", "displayed_amount_is_tax_inclusive": "string", "tax_rate_uuid": "123e4567-c29a-4f54-9f2b-231fe6469dbb", "sort_order": "string", "cost": "string", "displayed_cost": "string", "job_material_bundle_uuid": "123e4567-b2df-4893-9cff-231feba81c7b" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Job Materials" ], "operationId": "createJobMaterials", "summary": "Create a new Job Material", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_materials**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_materials" ] } ], "parameters": [], "requestBody": { "description": "Job Material record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobMaterial" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Job Material record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/jobmaterial/{uuid}.json": { "get": { "tags": [ "Job Materials" ], "operationId": "getJobMaterials", "summary": "Retrieve a Job Material", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_job_materials**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_job_materials" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Material", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job Material record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobMaterial" }, "examples": { "success": { "value": { "uuid": "123e4567-b07d-4e9d-98aa-231fe2c2e27b", "active": 1, "edit_date": "2025-08-01 12:00:00", "job_uuid": "123e4567-7d22-484a-bada-231fe21d33eb", "material_uuid": "123e4567-17f1-44d1-8312-231fe1ee327b", "name": "string", "quantity": "string", "price": "string", "displayed_amount": "string", "displayed_amount_is_tax_inclusive": "string", "tax_rate_uuid": "123e4567-2082-4581-a803-231fe17da36b", "sort_order": "string", "cost": "string", "displayed_cost": "string", "job_material_bundle_uuid": "123e4567-dd8b-4f98-a567-231fe762972b" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Job Materials" ], "operationId": "updateJobMaterials", "summary": "Update a Job Material", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_materials**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_materials" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Material", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Job Material fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobMaterial" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Job Materials" ], "operationId": "deleteJobMaterials", "summary": "Delete a Job Material", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_materials**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_materials" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Material", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job Material successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/jobmaterialbundle.json": { "get": { "tags": [ "Job Material Bundles" ], "operationId": "listJobMaterialBundles", "summary": "List all Job Material Bundles", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_job_materials**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_job_materials" ] } ], "responses": { "200": { "description": "An array of Job Material Bundles", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JobMaterialBundle" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-6358-4246-965a-231fe589616b", "active": 1, "edit_date": "2025-08-01 12:00:00", "item_number": "string", "name": "string", "quantity": "string", "sort_order": "string", "material_bundle_uuid": "123e4567-d8a1-485c-8a18-231fef5ffaeb", "job_uuid": "123e4567-6e8b-40c9-bde5-231fe46dd74b" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Job Material Bundles" ], "operationId": "createJobMaterialBundles", "summary": "Create a new Job Material Bundle", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_materials**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_materials" ] } ], "parameters": [], "requestBody": { "description": "Job Material Bundle record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobMaterialBundle" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Job Material Bundle record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/jobmaterialbundle/{uuid}.json": { "get": { "tags": [ "Job Material Bundles" ], "operationId": "getJobMaterialBundles", "summary": "Retrieve a Job Material Bundle", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_job_materials**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_job_materials" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Material Bundle", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job Material Bundle record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobMaterialBundle" }, "examples": { "success": { "value": { "uuid": "123e4567-910f-4ab6-9225-231fe2d6fdfb", "active": 1, "edit_date": "2025-08-01 12:00:00", "item_number": "string", "name": "string", "quantity": "string", "sort_order": "string", "material_bundle_uuid": "123e4567-9163-47f2-b2c5-231fecff2d0b", "job_uuid": "123e4567-137a-41fd-b656-231fedec14ab" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Job Material Bundles" ], "operationId": "updateJobMaterialBundles", "summary": "Update a Job Material Bundle", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_materials**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_materials" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Material Bundle", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Job Material Bundle fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobMaterialBundle" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Job Material Bundles" ], "operationId": "deleteJobMaterialBundles", "summary": "Delete a Job Material Bundle", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_materials**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_materials" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Material Bundle", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job Material Bundle successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/jobpayment.json": { "get": { "tags": [ "Job Payments" ], "operationId": "listJobPayments", "summary": "List all Job Payments", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_job_payments**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_job_payments" ] } ], "responses": { "200": { "description": "An array of Job Payments", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JobPayment" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-d046-4361-8ba9-231fe158d82b", "active": 1, "edit_date": "2025-08-01 12:00:00", "job_uuid": "123e4567-7182-4aaf-ae21-231fecd810db", "actioned_by_uuid": "123e4567-39e3-4a8b-b249-231fea72114b", "timestamp": "2025-08-01 12:00:00", "amount": "string", "method": "string", "note": "string", "attachment_uuid": "123e4567-f198-4550-9a00-231fec07ee6b", "is_deposit": "string" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Job Payments" ], "operationId": "createJobPayments", "summary": "Create a new Job Payment", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_payments**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_payments" ] } ], "parameters": [], "requestBody": { "description": "Job Payment record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobPayment" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Job Payment record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/jobpayment/{uuid}.json": { "get": { "tags": [ "Job Payments" ], "operationId": "getJobPayments", "summary": "Retrieve a Job Payment", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_job_payments**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_job_payments" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Payment", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job Payment record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobPayment" }, "examples": { "success": { "value": { "uuid": "123e4567-ac70-4200-b686-231fe474706b", "active": 1, "edit_date": "2025-08-01 12:00:00", "job_uuid": "123e4567-ffc1-45a3-993a-231fefb6fcbb", "actioned_by_uuid": "123e4567-3c1c-4714-8de1-231fe397b70b", "timestamp": "2025-08-01 12:00:00", "amount": "string", "method": "string", "note": "string", "attachment_uuid": "123e4567-c0df-4a2e-8c08-231fed9f098b", "is_deposit": "string" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Job Payments" ], "operationId": "updateJobPayments", "summary": "Update a Job Payment", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_payments**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_payments" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Payment", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Job Payment fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobPayment" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Job Payments" ], "operationId": "deleteJobPayments", "summary": "Delete a Job Payment", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_payments**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_payments" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Payment", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job Payment successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/jobtemplate.json": { "get": { "tags": [ "Job Templates" ], "operationId": "listJobTemplates", "summary": "List all Job Templates", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_jobs**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_jobs" ] } ], "responses": { "200": { "description": "An array of Job Templates", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JobTemplate" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-f225-47e9-8af3-231fe41f76cb", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/jobtemplate/{uuid}.json": { "get": { "tags": [ "Job Templates" ], "operationId": "getJobTemplates", "summary": "Retrieve a Job Template", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_jobs**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_jobs" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Template", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job Template record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobTemplate" }, "examples": { "success": { "value": { "uuid": "123e4567-0eb6-461e-b740-231fe4dcca0b", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/knowledgearticle.json": { "get": { "tags": [ "Knowledge Articles" ], "operationId": "listKnowledgeArticles", "summary": "List all Knowledge Articles", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_knowledge**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_knowledge" ] } ], "responses": { "200": { "description": "An array of Knowledge Articles", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeArticle" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-8da5-4b05-a60e-231fe74b011b", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string", "content": "string", "article_type": "string", "tags": "string", "relationships": [ { "object_name": "string", "object_uuid": "string", "object_description": "string", "create_date": "string" } ] } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Knowledge Articles" ], "operationId": "createKnowledgeArticles", "summary": "Create a new Knowledge Article", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_knowledge**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_knowledge" ] } ], "parameters": [], "requestBody": { "description": "Knowledge Article record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeArticle" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Knowledge Article record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/knowledgearticle/{uuid}.json": { "get": { "tags": [ "Knowledge Articles" ], "operationId": "getKnowledgeArticles", "summary": "Retrieve a Knowledge Article", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_knowledge**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_knowledge" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Knowledge Article", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Knowledge Article record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeArticle" }, "examples": { "success": { "value": { "uuid": "123e4567-eebb-4480-ad78-231feeb5ab5b", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string", "content": "string", "article_type": "string", "tags": "string", "relationships": [ { "object_name": "string", "object_uuid": "string", "object_description": "string", "create_date": "string" } ] } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Knowledge Articles" ], "operationId": "updateKnowledgeArticles", "summary": "Update a Knowledge Article", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_knowledge**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_knowledge" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Knowledge Article", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Knowledge Article fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeArticle" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Knowledge Articles" ], "operationId": "deleteKnowledgeArticles", "summary": "Delete a Knowledge Article", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_knowledge**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_knowledge" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Knowledge Article", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Knowledge Article successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/location.json": { "get": { "tags": [ "Locations" ], "operationId": "listLocations", "summary": "List all Locations", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_locations**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_locations" ] } ], "responses": { "200": { "description": "An array of Locations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } }, "examples": { "success": { "value": [ { "name": "string", "line1": "string", "line2": "string", "line3": "string", "city": "string", "country": "string", "post_code": "string", "phone_1": "string", "state": "string", "lng": "number", "lat": "number", "uuid": "123e4567-81da-4d05-8a26-231fe4c7b0bb", "active": 1, "edit_date": "2025-08-01 12:00:00" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Locations" ], "operationId": "createLocations", "summary": "Create a new Location", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_locations**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_locations" ] } ], "parameters": [], "requestBody": { "description": "Location record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Location record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/location/{uuid}.json": { "get": { "tags": [ "Locations" ], "operationId": "getLocations", "summary": "Retrieve a Location", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_locations**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_locations" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Location", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Location record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" }, "examples": { "success": { "value": { "name": "string", "line1": "string", "line2": "string", "line3": "string", "city": "string", "country": "string", "post_code": "string", "phone_1": "string", "state": "string", "lng": "number", "lat": "number", "uuid": "123e4567-890c-45f2-b38f-231fee17984b", "active": 1, "edit_date": "2025-08-01 12:00:00" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Locations" ], "operationId": "updateLocations", "summary": "Update a Location", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_locations**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_locations" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Location", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Location fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Locations" ], "operationId": "deleteLocations", "summary": "Delete a Location", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_locations**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_locations" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Location", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Location successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/material.json": { "get": { "tags": [ "Materials" ], "operationId": "listMaterials", "summary": "List all Materials", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_inventory**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_inventory" ] } ], "responses": { "200": { "description": "An array of Materials", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Material" } }, "examples": { "success": { "value": [ { "name": "string", "item_number": "string", "price": "string", "cost": "string", "quantity_in_stock": "number", "price_includes_taxes": "string", "barcode": "string", "item_is_inventoried": "string", "uuid": "123e4567-4be5-4b7a-8988-231fe8bb15bb", "active": 1, "edit_date": "2025-08-01 12:00:00", "item_description": "string", "use_description_for_invoicing": "string", "tax_rate_uuid": "123e4567-9892-4a34-83ba-231fe97d89ab" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Materials" ], "operationId": "createMaterials", "summary": "Create a new Material", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_inventory**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_inventory" ] } ], "parameters": [], "requestBody": { "description": "Material record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Material" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Material record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/material/{uuid}.json": { "get": { "tags": [ "Materials" ], "operationId": "getMaterials", "summary": "Retrieve a Material", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_inventory**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_inventory" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Material", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Material record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Material" }, "examples": { "success": { "value": { "name": "string", "item_number": "string", "price": "string", "cost": "string", "quantity_in_stock": "number", "price_includes_taxes": "string", "barcode": "string", "item_is_inventoried": "string", "uuid": "123e4567-90be-4da2-944b-231fe60a48eb", "active": 1, "edit_date": "2025-08-01 12:00:00", "item_description": "string", "use_description_for_invoicing": "string", "tax_rate_uuid": "123e4567-7a9c-4179-8f2f-231fe406677b" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Materials" ], "operationId": "updateMaterials", "summary": "Update a Material", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_inventory**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_inventory" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Material", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Material fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Material" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Materials" ], "operationId": "deleteMaterials", "summary": "Delete a Material", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_inventory**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_inventory" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Material", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Material successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/materialbundle.json": { "get": { "tags": [ "Bundles" ], "operationId": "listBundles", "summary": "List all Bundles", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_inventory**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_inventory" ] } ], "responses": { "200": { "description": "An array of Bundles", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MaterialBundle" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-f879-4b92-ba19-231feabf209b", "active": 1, "edit_date": "2025-08-01 12:00:00", "item_number": "string", "name": "string", "material_list": [ { "uuid": "string", "quantity": "number" } ] } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Bundles" ], "operationId": "createBundles", "summary": "Create a new Bundle", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_inventory**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_inventory" ] } ], "parameters": [], "requestBody": { "description": "Bundle record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaterialBundle" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Bundle record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/materialbundle/{uuid}.json": { "get": { "tags": [ "Bundles" ], "operationId": "getBundles", "summary": "Retrieve a Bundle", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_inventory**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_inventory" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Bundle", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Bundle record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaterialBundle" }, "examples": { "success": { "value": { "uuid": "123e4567-b7e0-456c-9466-231fedb29e1b", "active": 1, "edit_date": "2025-08-01 12:00:00", "item_number": "string", "name": "string", "material_list": [ { "uuid": "string", "quantity": "number" } ] } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Bundles" ], "operationId": "updateBundles", "summary": "Update a Bundle", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_inventory**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_inventory" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Bundle", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Bundle fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaterialBundle" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Bundles" ], "operationId": "deleteBundles", "summary": "Delete a Bundle", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_inventory**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_inventory" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Bundle", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Bundle successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/queue.json": { "get": { "tags": [ "Job Queues" ], "operationId": "listJobQueues", "summary": "List all Job Queues", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_job_queues**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_job_queues" ] } ], "responses": { "200": { "description": "An array of Job Queues", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Queue" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-28f3-4a1c-b4b9-231fe035b12b", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string", "default_timeframe": "string", "subscribed_staff": "string", "requires_assignment": "string" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Job Queues" ], "operationId": "createJobQueues", "summary": "Create a new Job Queue", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_queues**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_queues" ] } ], "parameters": [], "requestBody": { "description": "Job Queue record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Queue" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Job Queue record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/queue/{uuid}.json": { "get": { "tags": [ "Job Queues" ], "operationId": "getJobQueues", "summary": "Retrieve a Job Queue", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_job_queues**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_job_queues" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Queue", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job Queue record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Queue" }, "examples": { "success": { "value": { "uuid": "123e4567-1116-4755-b995-231fe619a26b", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string", "default_timeframe": "string", "subscribed_staff": "string", "requires_assignment": "string" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Job Queues" ], "operationId": "updateJobQueues", "summary": "Update a Job Queue", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_queues**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_queues" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Queue", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Job Queue fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Queue" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Job Queues" ], "operationId": "deleteJobQueues", "summary": "Delete a Job Queue", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_job_queues**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_job_queues" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Job Queue", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job Queue successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/securityrole.json": { "get": { "tags": [ "Security Roles" ], "operationId": "listSecurityRoles", "summary": "List all Security Roles", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_security_roles**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_security_roles" ] } ], "responses": { "200": { "description": "An array of Security Roles", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SecurityRole" } }, "examples": { "success": { "value": [ { "name": "string", "role_description": "string", "uuid": "123e4567-4062-4935-a10d-231fe30200ab", "active": 1, "edit_date": "2025-08-01 12:00:00" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/securityrole/{uuid}.json": { "get": { "tags": [ "Security Roles" ], "operationId": "getSecurityRoles", "summary": "Retrieve a Security Role", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_security_roles**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_security_roles" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Security Role", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Security Role record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityRole" }, "examples": { "success": { "value": { "name": "string", "role_description": "string", "uuid": "123e4567-444b-4bb2-95a5-231feac495ab", "active": 1, "edit_date": "2025-08-01 12:00:00" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/smstemplate.json": { "get": { "tags": [ "SMS Templates" ], "operationId": "listSMSTemplates", "summary": "List all SMS Templates", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_templates**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_templates" ] } ], "responses": { "200": { "description": "An array of SMS Templates", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SmsTemplate" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-43ef-47ac-a2a2-231fec67b4cb", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string", "message": "string" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "SMS Templates" ], "operationId": "createSMSTemplates", "summary": "Create a new SMS Template", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_templates**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_templates" ] } ], "parameters": [], "requestBody": { "description": "SMS Template record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsTemplate" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created SMS Template record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/smstemplate/{uuid}.json": { "get": { "tags": [ "SMS Templates" ], "operationId": "getSMSTemplates", "summary": "Retrieve a SMS Template", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_templates**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_templates" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the SMS Template", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "SMS Template record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsTemplate" }, "examples": { "success": { "value": { "uuid": "123e4567-45c3-454f-97a4-231fe808f88b", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string", "message": "string" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "SMS Templates" ], "operationId": "updateSMSTemplates", "summary": "Update a SMS Template", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_templates**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_templates" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the SMS Template", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "SMS Template fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsTemplate" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "SMS Templates" ], "operationId": "deleteSMSTemplates", "summary": "Delete a SMS Template", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_templates**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_templates" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the SMS Template", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "SMS Template successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/staff.json": { "get": { "tags": [ "Staff Members" ], "operationId": "listStaffMembers", "summary": "List all Staff Members", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_staff**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_staff" ] } ], "responses": { "200": { "description": "An array of Staff Members", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Staff" } }, "examples": { "success": { "value": [ { "first": "string", "last": "string", "email": "string", "mobile": "string", "lng": "number", "lat": "number", "geo_timestamp": "2025-08-01 12:00:00", "job_title": "string", "navigating_to_job_uuid": "123e4567-758f-4f8e-a58d-231fe9d8da9b", "navigating_timestamp": "2025-08-01 12:00:00", "navigating_expiry_timestamp": "2025-08-01 12:00:00", "color": "string", "custom_icon_url": "string", "status_message": "string", "status_message_timestamp": "2025-08-01 12:00:00", "hide_from_schedule": "string", "security_role_uuid": "123e4567-d2e0-422f-bfcd-231fedc184ab", "uuid": "123e4567-2162-4577-81b7-231fefed443b", "active": 1, "edit_date": "2025-08-01 12:00:00", "can_receive_push_notification": "string" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Staff Members" ], "operationId": "createStaffMembers", "summary": "Create a new Staff Member", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_staff**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_staff" ] } ], "parameters": [], "requestBody": { "description": "Staff Member record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Staff" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Staff Member record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/staff/{uuid}.json": { "get": { "tags": [ "Staff Members" ], "operationId": "getStaffMembers", "summary": "Retrieve a Staff Member", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_staff**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_staff" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Staff Member", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Staff Member record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Staff" }, "examples": { "success": { "value": { "first": "string", "last": "string", "email": "string", "mobile": "string", "lng": "number", "lat": "number", "geo_timestamp": "2025-08-01 12:00:00", "job_title": "string", "navigating_to_job_uuid": "123e4567-0992-41d6-acba-231fe7b9219b", "navigating_timestamp": "2025-08-01 12:00:00", "navigating_expiry_timestamp": "2025-08-01 12:00:00", "color": "string", "custom_icon_url": "string", "status_message": "string", "status_message_timestamp": "2025-08-01 12:00:00", "hide_from_schedule": "string", "security_role_uuid": "123e4567-3bf4-46de-9df6-231fea57616b", "uuid": "123e4567-4ed3-4c27-a167-231fed39523b", "active": 1, "edit_date": "2025-08-01 12:00:00", "can_receive_push_notification": "string" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Staff Members" ], "operationId": "updateStaffMembers", "summary": "Update a Staff Member", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_staff**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_staff" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Staff Member", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Staff Member fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Staff" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Staff Members" ], "operationId": "deleteStaffMembers", "summary": "Delete a Staff Member", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_staff**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_staff" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Staff Member", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Staff Member successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/staffmessage.json": { "get": { "tags": [ "Staff Messages" ], "operationId": "listStaffMessages", "summary": "List all Staff Messages", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_messages**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_messages" ] } ], "responses": { "200": { "description": "An array of Staff Messages", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StaffMessage" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-410b-491d-8d48-231fe929712b", "active": 1, "edit_date": "2025-08-01 12:00:00", "from_staff_uuid": "123e4567-b15c-45d2-b6e4-231fe846014b", "to_staff_uuid": "123e4567-6a91-4149-b8d3-231fee7ec56b", "sent_timestamp": "2025-08-01 12:00:00", "delivered_timestamp": "2025-08-01 12:00:00", "read_timestamp": "2025-08-01 12:00:00", "message": "string", "regarding_job_uuid": "123e4567-07f4-4508-a2a1-231fe925f92b", "attached_json": "string" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/staffmessage/{uuid}.json": { "get": { "tags": [ "Staff Messages" ], "operationId": "getStaffMessages", "summary": "Retrieve a Staff Message", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_messages**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_messages" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Staff Message", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Staff Message record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffMessage" }, "examples": { "success": { "value": { "uuid": "123e4567-5d5c-4042-836b-231fe0433cfb", "active": 1, "edit_date": "2025-08-01 12:00:00", "from_staff_uuid": "123e4567-6e5b-43a8-bd1e-231fe8c19a1b", "to_staff_uuid": "123e4567-8d78-42e7-9c47-231fed07c2eb", "sent_timestamp": "2025-08-01 12:00:00", "delivered_timestamp": "2025-08-01 12:00:00", "read_timestamp": "2025-08-01 12:00:00", "message": "string", "regarding_job_uuid": "123e4567-8e9a-4960-8ae5-231fe9c821ab", "attached_json": "string" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/task.json": { "get": { "tags": [ "Tasks" ], "operationId": "listTasks", "summary": "List all Tasks", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_tasks**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_tasks" ] } ], "responses": { "200": { "description": "An array of Tasks", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "examples": { "success": { "value": [ { "due_date": "YYYY-MM-DD", "task_details": "string", "name": "string", "related_object": "string", "related_object_uuid": "123e4567-7856-4ba9-ba7d-231fe84b9d6b", "task_complete": "string", "completed_timestamp": "2025-08-01 12:00:00", "completed_by_staff_uuid": "123e4567-5934-4965-a6d3-231fe85b8ceb", "assigned_to_staff_uuid": "123e4567-9ebb-43c1-8482-231feba60e7b", "lng": "string", "lat": "string", "uuid": "123e4567-d681-4379-b539-231fe5e4c53b", "active": 1, "edit_date": "2025-08-01 12:00:00", "created_by_staff_uuid": "123e4567-4013-4516-b480-231fee94ebfb", "create_date": "2025-08-01 12:00:00" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Tasks" ], "operationId": "createTasks", "summary": "Create a new Task", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_tasks**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_tasks" ] } ], "parameters": [], "requestBody": { "description": "Task record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Task record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/task/{uuid}.json": { "get": { "tags": [ "Tasks" ], "operationId": "getTasks", "summary": "Retrieve a Task", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_tasks**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_tasks" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Task", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Task record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" }, "examples": { "success": { "value": { "due_date": "YYYY-MM-DD", "task_details": "string", "name": "string", "related_object": "string", "related_object_uuid": "123e4567-9050-48bb-aa2b-231fe1a6a5eb", "task_complete": "string", "completed_timestamp": "2025-08-01 12:00:00", "completed_by_staff_uuid": "123e4567-7eca-4a04-b5ba-231fe520ff6b", "assigned_to_staff_uuid": "123e4567-db4e-4adb-97ad-231fe4c547cb", "lng": "string", "lat": "string", "uuid": "123e4567-0edd-4a8a-8b92-231fe58f638b", "active": 1, "edit_date": "2025-08-01 12:00:00", "created_by_staff_uuid": "123e4567-5f27-437e-b0ce-231fed90cd6b", "create_date": "2025-08-01 12:00:00" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Tasks" ], "operationId": "updateTasks", "summary": "Update a Task", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_tasks**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_tasks" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Task", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Task fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Tasks" ], "operationId": "deleteTasks", "summary": "Delete a Task", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_tasks**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_tasks" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Task", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Task successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/taxrate.json": { "get": { "tags": [ "Tax Rates" ], "operationId": "listTaxRates", "summary": "List all Tax Rates", "description": "\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_tax_rates**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_tax_rates" ] } ], "responses": { "200": { "description": "An array of Tax Rates", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaxRate" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-f797-4378-a1e8-231fe5c5d4cb", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string", "amount": "string", "is_default_tax_rate": "string" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Tax Rates" ], "operationId": "createTaxRates", "summary": "Create a new Tax Rate", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_tax_rates**.\n\n\t\t\t\n\t\t\t\n#### Record UUID\nUUID is optional for record creation. If no UUID is supplied, a UUID will be automatically generated for the new record and returned in the `x-record-uuid` response header.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_tax_rates" ] } ], "parameters": [], "requestBody": { "description": "Tax Rate record to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxRate" } } } }, "responses": { "200": { "headers": { "x-record-uuid": { "description": "UUID of newly created Tax Rate record", "schema": { "type": "string", "format": "uuid" } } }, "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to create this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/taxrate/{uuid}.json": { "get": { "tags": [ "Tax Rates" ], "operationId": "getTaxRates", "summary": "Retrieve a Tax Rate", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **read_tax_rates**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "read_tax_rates" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Tax Rate", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Tax Rate record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxRate" }, "examples": { "success": { "value": { "uuid": "123e4567-acd0-41dc-b4c9-231fee778d5b", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string", "amount": "string", "is_default_tax_rate": "string" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "post": { "tags": [ "Tax Rates" ], "operationId": "updateTaxRates", "summary": "Update a Tax Rate", "description": "\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_tax_rates**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_tax_rates" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Tax Rate", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Tax Rate fields to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxRate" } } } }, "responses": { "200": { "description": "Success - The record was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to update this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to update does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "Tax Rates" ], "operationId": "deleteTaxRates", "summary": "Delete a Tax Rate", "description": "\n\t\t\t\nIn ServiceM8, deleting a record sets its `active` field to `0`. Inactive records are still accessible on the API, but are hidden in the UI. Inactive records can be restored by setting their `active` field to `1`.\n\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **manage_tax_rates**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_tax_rates" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Tax Rate", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Tax Rate successfully archived (soft deleted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "examples": { "success": { "value": { "errorCode": "0", "message": "OK" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to delete this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The record to delete does not exist or has already been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/vendor.json": { "get": { "tags": [ "Vendors" ], "operationId": "listVendors", "summary": "List all Vendors", "description": "Vendor account information\n\n\n\t\t\t\n#### Filtering\nThis endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering).\n\t\t\t\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **vendor**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "vendor" ] } ], "responses": { "200": { "description": "An array of Vendors", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Vendor" } }, "examples": { "success": { "value": [ { "uuid": "123e4567-5e60-4ade-aa07-231feae80afb", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string", "abn_number": "string", "business_number": "string", "website": "string", "email": "string", "email_accounts": "string", "billing_address": "string", "accepted_payment_methods": "string", "default_region": "string", "currency": "string", "opening_time_monday": "string", "closing_time_monday": "string", "opening_time_tuesday": "string", "closing_time_tuesday": "string", "opening_time_wednesday": "string", "closing_time_wednesday": "string", "opening_time_thursday": "string", "closing_time_thursday": "string", "opening_time_friday": "string", "closing_time_friday": "string", "opening_time_saturday": "string", "closing_time_saturday": "string", "opening_time_sunday": "string", "closing_time_sunday": "string", "timezone_name": "string", "invoice_terms": "string", "job_default_status": "string" } ] } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/vendor/{uuid}.json": { "get": { "tags": [ "Vendors" ], "operationId": "getVendors", "summary": "Retrieve a Vendor", "description": "Vendor account information\n\n\n\t\t\t\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **vendor**.\n\n\t\t\t", "security": [ { "apiKey": [] }, { "oauth2": [ "vendor" ] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the Vendor", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Vendor record retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vendor" }, "examples": { "success": { "value": { "uuid": "123e4567-3b21-41d7-9317-231fe601f38b", "active": 1, "edit_date": "2025-08-01 12:00:00", "name": "string", "abn_number": "string", "business_number": "string", "website": "string", "email": "string", "email_accounts": "string", "billing_address": "string", "accepted_payment_methods": "string", "default_region": "string", "currency": "string", "opening_time_monday": "string", "closing_time_monday": "string", "opening_time_tuesday": "string", "closing_time_tuesday": "string", "opening_time_wednesday": "string", "closing_time_wednesday": "string", "opening_time_thursday": "string", "closing_time_thursday": "string", "opening_time_friday": "string", "closing_time_friday": "string", "opening_time_saturday": "string", "closing_time_saturday": "string", "opening_time_sunday": "string", "closing_time_sunday": "string", "timezone_name": "string", "invoice_terms": "string", "job_default_status": "string" } } } } } }, "400": { "description": "Bad Request - The request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badRequest": { "value": { "errorCode": "1000", "message": "An error occurred completing your request" } } } } } }, "401": { "description": "Unauthorized - Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationError" }, "examples": { "unauthorized": { "value": { "errorCode": "401", "message": "Authentication failed. Please check your API key or OAuth token." } } } } } }, "403": { "description": "Forbidden - You don't have permission to access this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "forbidden": { "value": { "errorCode": "403", "message": "Access forbidden. You don't have permission to access this resource." } } } } } }, "404": { "description": "Not Found - The requested record does not exist or has been deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "notFound": { "value": { "errorCode": "404", "message": "Resource not found. The requested record does not exist or has been deleted." } } } } } }, "429": { "description": "Too Many Requests - You have exceeded the rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "examples": { "rateLimitMinute": { "value": { "errorCode": 429, "message": "Number of allowed API requests per minute exceeded" } }, "rateLimitDay": { "value": { "errorCode": 429, "message": "Number of allowed API requests per day exceeded" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "value": { "errorCode": 500, "message": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/inboxmessage.json": { "get": { "tags": [ "Inbox" ], "operationId": "listInboxMessages", "summary": "List inbox messages", "description": "Retrieves a paginated list of inbox messages with optional filtering", "security": [ { "apiKey": [] }, { "oauth2": [ "read_inbox" ] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of messages to return (1-500)", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "description": "Number of messages to skip for pagination", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "filter", "in": "query", "description": "Filter messages by status", "schema": { "type": "string", "enum": [ "all", "unread", "archived", "snoozed" ], "default": "all" } }, { "name": "search", "in": "query", "description": "Search messages by subject, from name, or from email", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxMessagesResponse" } } } }, "403": { "description": "Forbidden - Missing permission or OAuth scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Service Unavailable - Inbox not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inboxmessage/{uuid}.json": { "get": { "tags": [ "Inbox" ], "operationId": "getInboxMessage", "summary": "Get inbox message details", "description": "Retrieves detailed information about a specific inbox message including attachments and conversation history", "security": [ { "apiKey": [] }, { "oauth2": [ "read_inbox" ] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "UUID of the inbox message", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxMessageDetail" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inboxmessage/{uuid}/read.json": { "put": { "tags": [ "Inbox" ], "operationId": "markInboxMessageAsRead", "summary": "Mark message as read", "description": "Marks an inbox message as read", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_inbox" ] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "UUID of the inbox message", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Message marked as read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inboxmessage/{uuid}/archive.json": { "put": { "tags": [ "Inbox" ], "operationId": "archiveInboxMessage", "summary": "Archive or unarchive message", "description": "Archives or unarchives an inbox message", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_inbox" ] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "UUID of the inbox message", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveRequest" } } } }, "responses": { "200": { "description": "Message archived/unarchived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/inboxmessage/{uuid}/snooze.json": { "put": { "tags": [ "Inbox" ], "operationId": "snoozeInboxMessage", "summary": "Snooze or unsnooze message", "description": "Snoozes a message until a specified date/time or unsnoozes it", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_inbox" ] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "UUID of the inbox message", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnoozeRequest" } } } }, "responses": { "200": { "description": "Message snoozed/unsnoozed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request - Invalid snooze date", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inboxmessage/{uuid}/convert-to-job.json": { "post": { "tags": [ "Inbox" ], "operationId": "convertInboxMessageToJob", "summary": "Convert message to job", "description": "Converts an inbox message into a new job, optionally using a job template", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_inbox" ] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "UUID of the inbox message", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertToJobRequest" } } } }, "responses": { "201": { "description": "Job created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertToJobResponse" } } } } } } }, "/inboxmessage/{uuid}/attach-to-job.json": { "post": { "tags": [ "Inbox" ], "operationId": "attachInboxMessageToJob", "summary": "Attach message to existing job", "description": "Attaches an inbox message to an existing job", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_inbox" ] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "UUID of the inbox message", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachToJobRequest" } } } }, "responses": { "200": { "description": "Message attached to job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachToJobResponse" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inboxmessage/{uuid}/notes.json": { "post": { "tags": [ "Inbox" ], "operationId": "addNoteToInboxMessage", "summary": "Add note to message", "description": "Adds a note to an inbox message", "security": [ { "apiKey": [] }, { "oauth2": [ "manage_inbox" ] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "UUID of the inbox message", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddNoteRequest" } } } }, "responses": { "201": { "description": "Note added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request - Empty note", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/jobtemplate/{uuid}/job.json": { "post": { "tags": [ "Job Templates" ], "operationId": "createJobFromTemplate", "summary": "Create a job from a template", "description": "Creates a new job by cloning an existing job template. All template entities (tasks, materials, checklists, quotes, custom fields) are cloned to the new job.\n\n#### Field Overrides\nOnly the following fields can be overridden when creating a job from a template:\n- `job_description` - Job description\n- `company_uuid` - UUID of the company/client\n- `company_name` - Name of the company/client (will lookup existing or create new)\n- `job_address` - Street address for the job\n\n**Note:** You cannot specify both `company_uuid` and `company_name`. If `company_name` is provided, the system will first search for an existing company with that name. If found, it will use that company's UUID. If not found, a new company will be created.\n\nAny other fields in the request body will be ignored.\n\n#### OAuth Scope\nThis endpoint requires the following OAuth scope **create_jobs**.", "security": [ { "apiKey": [] }, { "oauth2": [ "create_jobs" ] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "UUID of the job template to clone from", "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440000" } ], "requestBody": { "description": "Optional field overrides for the new job", "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobTemplateOverrides" }, "examples": { "minimal": { "summary": "Minimal override example", "value": { "company_uuid": "550e8400-e29b-41d4-a716-446655440001" } }, "companyName": { "summary": "Using company name", "value": { "company_name": "ACME Corporation", "job_address": "456 Oak Avenue" } }, "full": { "summary": "All allowed overrides with UUID", "value": { "job_description": "Annual HVAC maintenance", "company_uuid": "550e8400-e29b-41d4-a716-446655440001", "job_address": "123 Main Street" } } } } } }, "responses": { "201": { "description": "Job created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobUUID": { "type": "string", "format": "uuid", "description": "UUID of the created job" }, "location": { "type": "string", "description": "API path to the created job resource" }, "message": { "type": "string", "description": "Success message" } }, "required": [ "jobUUID", "location", "message" ] }, "examples": { "success": { "summary": "Successful job creation", "value": { "jobUUID": "550e8400-e29b-41d4-a716-446655440003", "location": "/api_1.0/job/550e8400-e29b-41d4-a716-446655440003.json", "message": "Job created successfully" } } } } } }, "400": { "description": "Bad request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalidUUID": { "summary": "Invalid UUID format", "value": { "errorCode": 400, "message": "Invalid job template UUID format" } }, "invalidJSON": { "summary": "Invalid JSON in request body", "value": { "errorCode": 400, "message": "Invalid JSON in request body" } }, "bothCompanyFields": { "summary": "Both company_uuid and company_name provided", "value": { "errorCode": 400, "message": "Cannot specify both company_uuid and company_name. Please provide only one." } } } } } }, "403": { "description": "Forbidden - Missing required OAuth scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "summary": "Missing OAuth scope", "value": { "errorCode": 403, "message": "OAuth token missing required scope: create_jobs" } } } } } }, "404": { "description": "Not Found - Template UUID not found or inactive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "notFound": { "summary": "Template not found", "value": { "errorCode": 404, "message": "Job template not found" } } } } } }, "405": { "description": "Method Not Allowed", "headers": { "Allow": { "description": "Allowed HTTP methods", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "methodNotAllowed": { "summary": "Wrong HTTP method", "value": { "errorCode": 405, "message": "Method not allowed. Use POST to create a job from template." } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "serverError": { "summary": "Internal server error", "value": { "errorCode": 500, "message": "Failed to create job from template" } } } } } } } } }, "/search.json": { "get": { "tags": [ "Search" ], "operationId": "generalSearch", "summary": "Search across multiple object types", "description": "Performs a text search across jobs, companies, and materials. Returns combined results sorted by relevance.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query string", "schema": { "type": "string", "minLength": 1, "maxLength": 100, "example": "plumbing repair" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results to return (max 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "description": "Bad request - Missing query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/search/{objectType}.json": { "get": { "tags": [ "Search" ], "operationId": "objectSearch", "summary": "Search within a specific object type", "description": "Performs a text search within a specific object type. Supported types: job, company, material, knowledgearticle, attachment, formresponse, asset, materialbundle", "parameters": [ { "name": "objectType", "in": "path", "required": true, "description": "Type of object to search", "schema": { "type": "string", "enum": [ "job", "company", "material", "knowledgearticle", "attachment", "formresponse", "asset", "materialbundle" ] } }, { "name": "q", "in": "query", "required": true, "description": "Search query string", "schema": { "type": "string", "minLength": 1, "maxLength": 100, "example": "emergency repair" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results to return (max 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectSearchResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests - Search throttled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/search/job/embedding.json": { "get": { "tags": [ "Search" ], "operationId": "jobEmbeddingSearch", "summary": "Semantic search for jobs", "description": "Harness the power of advanced AI embeddings to revolutionise how you search through job data. This endpoint transforms your search query into high-dimensional vector embeddings, then intelligently matches it against our entire job database using semantic similarity algorithms.\n\nHow it works:\n1. AI Query Understanding - Your search terms are processed through neural embedding models that understand context, intent, and meaning\n2. Vector-Based Matching - The system compares your query against vector representations of all job content in real-time\n3. Intelligent Ranking - Returns results ranked by semantic similarity, not just keyword matching\n\nWhy this matters:\n- Find jobs about \"plumbing repairs\" even when searching for \"fixing pipes\"\n- Discover relevant work orders that use different terminology but share the same intent\n- Uncover hidden patterns and connections in your job data that traditional search would miss\n\nThis isn't just search\u2014it's AI that truly understands what you're looking for and delivers the most relevant results, even when the exact words don't match.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query string", "schema": { "type": "string", "minLength": 1, "example": "replace hot water system" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results to return (max 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "similarity_threshold", "in": "query", "required": false, "description": "Minimum similarity score (0.0 to 1.0)", "schema": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "default": 0.7 } } ], "responses": { "200": { "description": "Embedding search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingSearchResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable - Embedding search not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "name": "X-Api-Key", "in": "header" }, "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://api.servicem8.com/oauth/authorize", "tokenUrl": "https://api.servicem8.com/oauth/access_token", "scopes": { "staff_locations": "Access to real-time GPS information about staff", "staff_activity": "Access to clock on, lunch break and clock off information about staff", "publish_sms": "Access to send SMS messages to customers and/or staff on your behalf. Note sending SMS messages will incur account charges.", "publish_email": "Access to send Email messages to customers and/or staff on your behalf", "vendor": "Access to basic account information", "vendor_logo": "Access to account logo", "vendor_email": "Access to account holder email address", "read_locations": "Read-only access to Location Endpoint", "manage_locations": "Full access to Location Endpoint", "read_staff": "Read-only access to Staff Endpoint", "manage_staff": "Full access to Staff Endpoint", "read_customers": "Read-only access to Company Endpoint", "manage_customers": "Full access to Company Endpoint", "read_customer_contacts": "Read-only access to CompanyContact Endpoint", "manage_customer_contacts": "Full access to CompanyContact Endpoint", "read_jobs": "Read-only access to Job Endpoint", "manage_jobs": "Full access to Job Endpoint", "create_jobs": "Ability to create jobs on behalf of account. Note creating jobs may incur account charges.", "read_job_contacts": "Read-only access to JobContact Endpoint", "manage_job_contacts": "Full access to JobContact Endpoint", "read_job_materials": "Read-only access to JobMaterials Endpoint", "manage_job_materials": "Full access to JobMaterials Endpoint", "read_job_categories": "Read-only access to Categories Endpoint", "manage_job_categories": "Full access to Categories Endpoint", "read_job_queues": "Read-only access to Job Queues Endpoint", "manage_job_queues": "Full access to Job Queues Endpoint", "read_tasks": "Read-only access to Tasks Endpoint", "manage_tasks": "Full access to Tasks Endpoint", "read_schedule": "Read-only access to JobActivity Endpoint", "manage_schedule": "Full access to JobActivity Endpoint", "read_inventory": "Read-only access to Materials Endpoint", "manage_inventory": "Full access to Materials Endpoint", "read_job_notes": "Read-only access to job notes", "publish_job_notes": "Ability to add new job notes", "read_job_photos": "Read-only access to job photos", "publish_job_photos": "Ability to add new job photos", "read_attachments": "Read-only access to Attachments Endpoint", "manage_attachments": "Full access to Attachments Endpoint", "read_inbox": "Read-only access to inbox messages", "read_messages": "Read-only access to staff messages", "manage_notifications": "Ability to read notifications and mark as read", "manage_templates": "Full-access to email, sms and document templates", "manage_badges": "Full-access to create/modify job badges", "read_assets": "Read-only access to Assets Endpoint", "manage_assets": "Full access to Assets Endpoint", "read_knowledge_base": "Read-only access to Knowledge Base Endpoint", "manage_knowledge_base": "Full access to Knowledge Base Endpoint" } } } } }, "schemas": { "WebhookEvent": { "type": "object", "required": [ "event_type", "timestamp", "data" ], "properties": { "event_type": { "type": "string", "pattern": "^[a-z]+\\.[a-z]+$", "description": "Type of event (e.g., job.created, company.updated)", "example": "job.updated" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the event occurred" }, "data": { "type": "object", "description": "Event-specific payload containing the affected resource" }, "metadata": { "type": "object", "properties": { "attempt": { "type": "integer", "minimum": 1, "description": "Delivery attempt number" }, "signature": { "type": "string", "description": "HMAC-SHA256 signature for webhook verification" } } } } }, "Result": { "type": "object", "properties": { "errorCode": { "type": "number", "format": "int32", "example": "0" }, "message": { "type": "string", "example": "OK" } } }, "Error": { "type": "object", "properties": { "errorCode": { "type": "number", "format": "int32", "example": "1000" }, "message": { "type": "string", "example": "An error occurred completing your request" } } }, "RateLimitError": { "type": "object", "properties": { "errorCode": { "type": "number", "format": "int32", "example": "429" }, "message": { "type": "string", "example": "Number of allowed API requests per minute exceeded" } } }, "AuthenticationError": { "type": "object", "properties": { "errorCode": { "type": "number", "format": "int32", "example": "401" }, "message": { "type": "string", "example": "Authentication failed. Please check your API key or OAuth token." } } }, "ForbiddenError": { "type": "object", "properties": { "errorCode": { "type": "number", "format": "int32", "example": "403" }, "message": { "type": "string", "example": "Access forbidden. You don't have permission to access this resource." } } }, "NotFoundError": { "type": "object", "properties": { "errorCode": { "type": "number", "format": "int32", "example": "404" }, "message": { "type": "string", "example": "Resource not found. The requested record does not exist or has been deleted." } } }, "AllocationWindow": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-432c-46f8-9e63-231fe6e3674b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "name": { "type": "string" }, "start_time": { "type": "integer" }, "end_time": { "type": "integer" }, "sort_priority": { "type": "integer" } } }, "Asset": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-f180-4508-94d8-231fe39e62db", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "company_uuid": { "format": "uuid", "example": "123e4567-2d31-4640-814a-231fe1887bcb", "type": "string", "description": "UUID of the Client to which this Asset is attached" }, "asset_code": { "type": "string", "description": "The unique code printed on this Asset's attached label (read only)" }, "asset_type_uuid": { "format": "uuid", "example": "123e4567-875a-4da5-8fed-231fecc7c98b", "type": "string", "description": "UUID of an Asset Type which defines the fields that can be stored for this Asset (read only)" }, "name": { "type": "string", "description": "User-facing description of this asset", "maxLength": 100 }, "lat": { "type": "number", "format": "float", "description": "Latitude component of the Asset's location in degrees" }, "lng": { "type": "number", "format": "float", "description": "Longitude component of the Asset's location in degrees" }, "geo_timestamp": { "example": "2025-08-01 12:00:00", "type": "string", "description": "Timestamp at which the Asset's location was last updated" }, "altitude": { "type": "number", "description": "Altitude component of the Asset's location in metres" }, "field_data": { "type": "array", "description": "JSON array containing field values for this asset. Each entry represents a field value defined by the associated AssetType, with field values stored as strings. Date fields use Y-m-d format. This field stores all custom fields defined in the asset type template.", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Must be the UUID of an AssetTypeField" }, "fieldType": { "type": "string" }, "fieldName": { "type": "string" }, "fieldValue": { "type": "string", "description": "Convert all values to string. Dates shall be in Y-m-d format." }, "sortOrder": { "type": "number" } }, "required": [ "uuid", "fieldType", "fieldName", "fieldValue", "sortOrder" ] } } } }, "AssetType": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-7536-4e74-a3d6-231fe19e7f7b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "name": { "type": "string", "description": "The name of the asset type. Used to identify different categories of assets that can be tracked in the system. Examples might include 'Air Conditioner', 'Fire Extinguisher', etc." } } }, "AssetTypeField": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-b81b-47e3-88ec-231febe8ddcb", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "asset_type_uuid": { "format": "uuid", "example": "123e4567-f85a-4885-aece-231fefd3f86b", "type": "string", "description": "UUID of the Asset Type to which this field belongs. This field is read-only in the API. (Read only)" }, "name": { "type": "string", "description": "Name of the field that will be displayed to users. Used as a label for the input field when managing assets." }, "field_data": { "type": "object", "description": "Configuration data for the field", "properties": { "fieldType": { "type": "string", "enum": [ "Text", "Number", "Date", "Multiple Choice" ] }, "mandatory": { "type": "boolean" }, "choices": { "type": "array", "items": { "type": "string" } } }, "required": [ "fieldType", "mandatory" ] }, "sort_order": { "type": "integer", "description": "The order in which this field should be displayed relative to other fields of the same asset type. Lower values display first." } }, "required": [ "name" ] }, "Attachment": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-c7af-4e30-9452-231fe6639f7b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "related_object": { "type": "string" }, "related_object_uuid": { "format": "uuid", "example": "123e4567-02e9-47d6-8b47-231fe4edbf8b", "type": "string" }, "attachment_name": { "type": "string", "description": "The security roles description", "maxLength": 127 }, "file_type": { "type": "string", "description": "Location's name", "maxLength": 50 }, "created_by_staff_uuid": { "format": "uuid", "example": "123e4567-2b16-4297-beea-231fe483e7bb", "type": "string" }, "timestamp": { "type": "string" }, "attachment_source": { "type": "string" }, "tags": { "type": "string" }, "lng": { "type": "number", "format": "float" }, "lat": { "type": "number", "format": "float" }, "photo_width": { "type": "string" }, "photo_height": { "type": "string" }, "extracted_info": { "type": "string" }, "is_favourite": { "type": "string" }, "class_name": { "type": "string" }, "metadata": { "type": "string" } } }, "Badge": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-8231-4021-b4eb-231fe94c883b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "name": { "type": "string", "description": "The display name of the badge. Used to identify the badge in the system. Examples include 'Warranty', 'VIP', 'Take Payment Facilities', etc.", "maxLength": 50 }, "automatically_allocated": { "type": "string" }, "file_name": { "type": "string" }, "regarding_form_uuid": { "format": "uuid", "example": "123e4567-ca88-43dc-aff4-231fee1d78eb", "type": "string" }, "regarding_asset_type_uuid": { "format": "uuid", "example": "123e4567-7928-4a5c-9909-231fef0917eb", "type": "string", "description": "UUID of the asset type that this badge is associated with. Only applicable for asset-based badges. When set, the badge represents a specific asset type in the system and will appear on assets of this type." } }, "required": [ "name" ] }, "Category": { "type": "object", "properties": { "name": { "description": "The name of the job category. Used to classify and organize jobs.", "type": "string" }, "colour": { "description": "The colour associated with this job category. This colour is used to visually identify the category on the dispatch board and in calendar views. The value is a hexadecimal colour code (6 characters 0-9a-f).", "type": "string" }, "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-06f7-4533-a831-231fe2295bfb", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" } }, "required": [ "name" ] }, "Company": { "type": "object", "properties": { "name": { "description": "Company Name", "type": "string", "maxLength": 100 }, "abn_number": { "description": "Australian Business Number. A unique 11-digit identifier issued by the Australian Taxation Office to businesses. Required for tax compliance and validation of business identity in Australia.", "type": "string" }, "address": { "description": "Password", "type": "string", "maxLength": 500 }, "billing_address": { "description": "Confirm Password", "type": "string", "maxLength": 500 }, "parent_company_uuid": { "description": "If provided, specifies the UUID of this Site's parent Company. If blank, this record is a Head Office rather than a Site. This field is only present on ServiceM8 Accounts with the Company Sites addon activated." }, "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-02a9-40ef-baca-231fea25164b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "website": { "type": "string" }, "is_individual": { "type": "string" }, "address_street": { "type": "string", "maxLength": 500 }, "address_city": { "type": "string" }, "address_state": { "type": "string" }, "address_postcode": { "type": "string" }, "address_country": { "type": "string" }, "fax_number": { "type": "string" }, "badges": { "type": "string", "description": "JSON Array of Badge UUIDs" }, "tax_rate_uuid": { "format": "uuid", "example": "123e4567-0e84-47a8-8cb4-231feab79e7b", "type": "string" }, "billing_attention": { "type": "string" }, "payment_terms": { "type": "string" } }, "required": [ "name" ] }, "CompanyContact": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-8123-4a40-bb1c-231feb14351b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "company_uuid": { "format": "uuid", "example": "123e4567-97e0-48f1-845a-231fe9f9d65b", "type": "string", "description": "The UUID of the company this contact belongs to" }, "first": { "type": "string" }, "last": { "type": "string" }, "phone": { "type": "string" }, "mobile": { "type": "string" }, "email": { "format": "email", "type": "string" }, "type": { "type": "string" }, "is_primary_contact": { "type": "string" } } }, "DocumentTemplate": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-b79e-4ca8-8bd7-231feaf93e7b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "template_type": { "type": "string", "description": "(Read only)" }, "related_object": { "type": "string", "description": "(Read only)" }, "name": { "type": "string" } } }, "EmailTemplate": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-7616-40d6-833d-231fe70195eb", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "name": { "type": "string", "maxLength": 50 }, "subject": { "type": "string", "maxLength": 100 }, "message": { "type": "string", "maxLength": 1000 } }, "required": [ "name" ] }, "Feedback": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-5a52-4cfc-9900-231fe933b16b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "timestamp": { "type": "string" }, "related_object": { "type": "string" }, "related_object_uuid": { "format": "uuid", "example": "123e4567-1561-4fdb-aff2-231fefc0b22b", "type": "string" }, "rating": { "type": "string" }, "comment": { "type": "string" } } }, "Form": { "type": "object", "properties": { "name": { "description": "The name of the form. Used to identify the form in the system and displayed to users in the form selector. Must be unique within an account. Maximum length is 255 characters.", "type": "string" }, "document_template_uuid": { "description": "UUID of the document template associated with this form. The template defines the layout and appearance of the form when it's generated as a document. References a document template object in the system.", "format": "uuid", "example": "123e4567-2945-466c-9720-231feebb008b", "type": "string" }, "can_be_used_independently": { "description": "Boolean flag indicating whether this form can be used independently of a job. When set to true (1), the form can be filled out as a standalone form. When false (0), the form must be associated with a job to be completed.", "type": "string" }, "badge_mandatory_state": { "description": "Controls when badge completion is mandatory for this form. Valid values are: 0 (not mandatory), 1 (mandatory on check-in), 2 (mandatory on check-out). This determines at which stage in the job lifecycle a staff member must complete this form.", "type": "string" }, "template_fields": { "description": "JSON array of template fields that are used when generating form documents. Each field contains a name, fieldType, value, and sortOrder. Maximum of 10 fields allowed.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "fieldType": { "type": "string", "enum": [ "Text" ] }, "value": { "type": "string" }, "sortOrder": { "type": "integer" } }, "required": [ "name", "fieldType", "value", "sortOrder" ] }, "minItems": 0, "maxItems": 10 }, "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-86c0-4fed-9445-231fee4a3b7b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "badge_name": { "type": "string", "maxLength": 12 } } }, "FormField": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-9459-422f-862e-231fe4518e5b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "form_uuid": { "format": "uuid", "example": "123e4567-25c8-421a-b49d-231fe7247fcb", "type": "string", "description": "The UUID of the form this field belongs to." }, "name": { "type": "string", "description": "The name of the form field." }, "field_data_json": { "type": "string", "description": "JSON configuration for this question, including type, mandatory, choices and conditions." }, "sort_order": { "type": "integer", "description": "The sort order of the form field." } } }, "FormResponse": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-18cd-4ac0-9a45-231fe9f9ab1b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "form_uuid": { "format": "uuid", "example": "123e4567-e984-44b7-bab7-231fe768de9b", "type": "string" }, "staff_uuid": { "format": "uuid", "example": "123e4567-2365-4d26-adef-231fe0553aab", "type": "string" }, "regarding_object": { "type": "string" }, "regarding_object_uuid": { "format": "uuid", "example": "123e4567-64c5-4808-bcfc-231fe0b583db", "type": "string" }, "field_data": { "type": "string" }, "timestamp": { "type": "string", "example": "2025-08-01 12:00:00" }, "form_by_staff_uuid": { "format": "uuid", "example": "123e4567-ce88-40c3-9a43-231fe5e100ab", "type": "string" }, "document_attachment_uuid": { "format": "uuid", "example": "123e4567-4076-4e55-9665-231feec6803b", "type": "string" }, "asset_uuid": { "format": "uuid", "example": "123e4567-989d-443b-a45c-231fed1b70db", "type": "string" } } }, "InboxMessage": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "active": { "type": "boolean" }, "edit_date": { "type": "string", "format": "date-time" }, "timestamp": { "type": "string", "format": "date-time" }, "read_timestamp": { "type": "string", "format": "date-time", "nullable": true }, "last_reply_timestamp": { "type": "string", "format": "date-time", "nullable": true }, "snooze_until_timestamp": { "type": "string", "format": "date-time", "nullable": true }, "read_by_staff_uuid": { "type": "string", "format": "uuid", "nullable": true }, "from_name": { "type": "string" }, "from_email": { "type": "string" }, "to_email": { "type": "string" }, "subject": { "type": "string" }, "message_text": { "type": "string" }, "message_html": { "type": "string" }, "is_archived": { "type": "boolean" }, "archived_timestamp": { "type": "string", "format": "date-time", "nullable": true }, "archived_by_staff_uuid": { "type": "string", "format": "uuid", "nullable": true }, "regarding_company_uuid": { "type": "string", "format": "uuid", "nullable": true }, "converted_to_job_uuid": { "type": "string", "format": "uuid", "nullable": true }, "job_template_uuid": { "type": "string", "format": "uuid", "nullable": true }, "message_type": { "type": "string", "enum": [ "email", "sms", "online_booking", "phone_call", "reminder", "form", "network_request", "supplier_invoice", "asset", "partner_lead", "automation" ] } } }, "Job": { "type": "object", "properties": { "created_by_staff_uuid": { "description": "UUID of the staff member who created this job. Records which staff member initially added the job to the system.", "format": "uuid", "example": "123e4567-6e3d-47bb-bfdc-231fe37dd8bb", "type": "string" }, "date": { "description": "The date the job was created or scheduled. Used for organizing jobs chronologically and for reference in reports.", "example": "YYYY-MM-DD", "type": "string" }, "company_uuid": { "description": "UUID reference to the client/company record associated with this job. Links the job to a client in the system, establishing the client-job relationship for billing and contact purposes.", "format": "uuid", "example": "123e4567-99a5-459b-84af-231fe3c1c11b", "type": "string" }, "billing_address": { "description": "The address where invoices and billing information should be sent. If not specified, defaults to the job address.", "type": "string", "maxLength": 500 }, "status": { "description": "Current status of the job. Controls where the Job appears in the Dispatch Board.. Valid values are [Quote,Work Order,Unsuccessful,Completed]", "enum": [ "Quote", "Work Order", "Unsuccessful", "Completed" ], "type": "string", "maxLength": 20 }, "lng": { "description": "The longitude coordinate of the job location.", "type": "number", "format": "float" }, "lat": { "description": "The latitude coordinate of the job location.", "type": "number", "format": "float" }, "payment_date": { "description": "Not used. Refer to JobPayment endpoint.", "example": "2025-08-01 12:00:00", "type": "string" }, "payment_actioned_by_uuid": { "description": "Not used. Refer to JobPayment endpoint.", "format": "uuid", "example": "123e4567-949b-4f36-96d0-231fe060aacb", "type": "string" }, "payment_method": { "description": "Not used. Refer to JobPayment endpoint.", "type": "string" }, "payment_amount": { "description": "Not used. Refer to JobPayment endpoint.", "type": "string" }, "category_uuid": { "description": "UUID reference to the job category this job belongs to. Categories help organize jobs by type of work or department.", "format": "uuid", "example": "123e4567-2549-4c86-86a7-231fe1a3a9bb", "type": "string" }, "payment_note": { "description": "Not used. Refer to JobPayment endpoint.", "type": "string" }, "geo_is_valid": { "description": "Indicates whether the geocoding for the job address is valid. If this is false, the lat, lng, and other geo_ fields should not be used. (Read only). Valid values are [0,1]", "type": "integer", "enum": [ 0, 1 ] }, "purchase_order_number": { "description": "Client purchase order reference number for this job. Used for cross-referencing with external accounting or order management systems.", "type": "string", "maxLength": 100 }, "invoice_sent": { "description": "Indicates whether an invoice has been sent for this job. (Read only). Valid values are [0,1]", "type": "integer", "enum": [ 0, 1 ] }, "invoice_sent_stamp": { "description": "The date and time when the invoice was sent. (Read only)", "example": "2025-08-01 12:00:00", "type": "string" }, "ready_to_invoice": { "description": "DEPRECATED" }, "ready_to_invoice_stamp": { "description": "DEPRECATED" }, "geo_country": { "description": "The country field of the job address. (Read only)", "type": "string" }, "geo_postcode": { "description": "The postcode/ZIP code field of the job address. (Read only)", "type": "string" }, "geo_state": { "description": "The state/province field of the job address. (Read only)", "type": "string" }, "geo_city": { "description": "The city/suburb field of the job address. (Read only)", "type": "string" }, "geo_street": { "description": "The street name field of the job address. (Read only)", "type": "string" }, "geo_number": { "description": "The street number field of the job address. (Read only)", "type": "string" }, "queue_uuid": { "description": "The UUID of the queue this job belongs to.", "format": "uuid", "example": "123e4567-a8b7-4552-b316-231fe249983b", "type": "string" }, "queue_expiry_date": { "description": "The date and time when the job expires from the queue.", "example": "2025-08-01 12:00:00", "type": "string" }, "queue_assigned_staff_uuid": { "description": "The UUID of the staff member assigned to this job in the queue.", "format": "uuid", "example": "123e4567-4574-4816-a1c3-231fedefbb1b", "type": "string" }, "badges": { "description": "JSON Array of Badge UUIDs", "type": "string" }, "quote_date": { "description": "The date and time that the job status was changed to Quote.", "example": "2025-08-01 12:00:00", "type": "string" }, "quote_sent": { "description": "Boolean flag indicating whether a quote has been sent to the client for this job. (Read only). Valid values are [0,1]", "type": "integer", "enum": [ 0, 1 ] }, "quote_sent_stamp": { "description": "Timestamp when the quote was sent to the client. Format is YYYY-MM-DD HH:MM:SS. (Read only)", "example": "2025-08-01 12:00:00", "type": "string" }, "work_order_date": { "description": "The date and time that the job status was changed to Work Order.", "example": "2025-08-01 12:00:00", "type": "string" }, "active_network_request_uuid": { "description": "DEPRECATED" }, "related_knowledge_articles": { "description": "DEPRECATED" }, "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-d773-48f0-ac26-231fe1edc5eb", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "job_address": { "type": "string", "description": "Physical address where the job is to be performed. This address is used for geocoding to place the job on the map.", "maxLength": 500 }, "job_description": { "type": "string" }, "work_done_description": { "type": "string", "description": "Email Address" }, "generated_job_id": { "type": "string", "description": "System-generated unique job identifier. This is read-only and automatically assigned when a job is created. (Read only)" }, "total_invoice_amount": { "type": "string", "description": "The total amount to be invoiced for this job." }, "payment_processed": { "type": "integer", "description": "Indicates whether the job has been exported to the connected Accounting Package.. Valid values are [0,1]", "enum": [ 0, 1 ] }, "payment_processed_stamp": { "example": "2025-08-01 12:00:00", "type": "string", "description": "The date and time the job has been exported to the connected Accounting Package." }, "payment_received": { "type": "integer", "description": "Indicates whether full payment has been received for this job.. Valid values are [0,1]", "enum": [ 0, 1 ] }, "payment_received_stamp": { "example": "2025-08-01 12:00:00", "type": "string", "description": "The date and time when full payment was received." }, "completion_date": { "example": "2025-08-01 12:00:00", "type": "string", "description": "The date and time that the job status was changed to Completed." }, "completion_actioned_by_uuid": { "format": "uuid", "example": "123e4567-7f85-48df-a414-231fe531965b", "type": "string", "description": "UUID of the staff member who marked this job as completed. References a staff record in the system." }, "unsuccessful_date": { "example": "2025-08-01 12:00:00", "type": "string", "description": "The date and time that the job status was changed to Unsuccessful." }, "job_is_scheduled_until_stamp": { "example": "2025-08-01 12:00:00", "type": "string", "description": "The end date/time of the last scheduled activity for this job. After this date, the job is considered Unscheduled." } }, "required": [ "status" ] }, "JobActivity": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-146d-4b3b-8201-231fe8d8249b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "job_uuid": { "format": "uuid", "example": "123e4567-46c2-44aa-8272-231fe389fa9b", "type": "string", "description": "The UUID of the job this activity belongs to" }, "staff_uuid": { "format": "uuid", "example": "123e4567-6fb5-4111-8eef-231feb52e4ab", "type": "string", "description": "The UUID of the staff member assigned to this activity" }, "start_date": { "example": "2025-08-01 12:00:00", "type": "string", "description": "The scheduled start date and time of the activity" }, "end_date": { "example": "2025-08-01 12:00:00", "type": "string", "description": "The scheduled end date and time of the activity" }, "activity_was_scheduled": { "type": "string" }, "activity_was_recorded": { "type": "string" }, "activity_was_automated": { "type": "string" }, "has_been_opened": { "type": "string" }, "has_been_opened_timestamp": { "example": "2025-08-01 12:00:00", "type": "string" }, "travel_time_in_seconds": { "type": "integer", "description": "The estimated travel time to reach this activity location in seconds" }, "travel_distance_in_meters": { "type": "integer", "description": "The estimated travel distance to reach this activity location in meters" }, "allocated_by_staff_uuid": { "format": "uuid", "example": "123e4567-061a-4c62-8536-231fe18e06ab", "type": "string" }, "allocated_timestamp": { "example": "2025-08-01 12:00:00", "type": "string" }, "material_uuid": { "format": "uuid", "example": "123e4567-6516-4a80-8b11-231fe862fd7b", "type": "string", "description": "The UUID of the material associated with this activity. Used to determine the cost of the activity." }, "edit_by_staff_uuid": { "format": "uuid", "example": "123e4567-7356-4b53-8206-231fe2eb0d5b", "readOnly": true, "description": "UUID of Staff Member who last modified record" } } }, "JobAllocation": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-a4b2-472d-a123-231fe640755b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "job_uuid": { "format": "uuid", "example": "123e4567-67a3-41e0-8643-231fe9edfb0b", "type": "string" }, "queue_uuid": { "format": "uuid", "example": "123e4567-502e-4a9a-89e9-231fe3423ddb", "type": "string" }, "staff_uuid": { "format": "uuid", "example": "123e4567-0982-463c-a12e-231feadd72ab", "type": "string" }, "allocation_date": { "example": "2025-08-01 12:00:00", "type": "string" }, "allocation_window_uuid": { "format": "uuid", "example": "123e4567-e0a6-4e63-84e3-231fe31716bb", "type": "string" }, "allocated_by_staff_uuid": { "format": "uuid", "example": "123e4567-87bf-4114-ab63-231fe4cca40b", "type": "string" }, "allocated_timestamp": { "example": "2025-08-01 12:00:00", "type": "string" }, "expiry_timestamp": { "example": "2025-08-01 12:00:00", "type": "string" }, "read_timestamp": { "example": "2025-08-01 12:00:00", "type": "string" }, "completion_timestamp": { "example": "2025-08-01 12:00:00", "type": "string" }, "estimated_duration": { "type": "string" }, "revised_duration": { "type": "string" }, "sort_priority": { "type": "string" }, "requires_acceptance": { "type": "string" }, "acceptance_status": { "type": "string" }, "acceptance_timestamp": { "example": "2025-08-01 12:00:00", "type": "string" } } }, "JobChecklist": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-94a9-4b32-9a0b-231fe173cf2b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "job_uuid": { "format": "uuid", "example": "123e4567-bb2e-4ebf-89e9-231fedfe2f9b", "type": "string", "description": "UUID of the job this checklist item belongs to. This links the checklist item to a specific job in the system." }, "name": { "type": "string", "description": "The name or description of the checklist item. This is displayed to users in the mobile app and web interface.", "maxLength": 512 }, "section_name": { "type": "string", "description": "The section or category name under which this checklist item is grouped. This helps organize related checklist items together.", "maxLength": 256 }, "item_type": { "type": "string", "description": "The type of checklist item. Valid values are: 'Todo', 'Asset', 'Photo', 'Form', and 'Document'. Defaults to 'Todo' if not specified. This determines the functionality and appearance of the checklist item." }, "sort_order": { "type": "integer", "description": "A numeric value determining the order in which checklist items appear in the user interface. Lower values appear first. Used to customize the display sequence of items." }, "completed_timestamp": { "example": "2025-08-01 12:00:00", "type": "string", "description": "The date and time when the checklist item was marked as completed. Empty or '0000-00-00 00:00:00' indicates the item is not completed." }, "completed_by_staff_uuid": { "format": "uuid", "example": "123e4567-ba9f-4adb-b209-231fe616570b", "type": "string", "description": "UUID of the staff member who completed this checklist item. References a Staff object. Empty if the item is not completed." }, "completed_during_checkin_uuid": { "format": "uuid", "example": "123e4567-a069-4589-8301-231fe4008abb", "type": "string", "description": "UUID of the job check-in during which this checklist item was completed. This links the checklist completion to a specific check-in event in the job history." }, "reminder_type": { "type": "string", "description": "The type of reminder associated with this checklist item. Valid values are: '' (no reminder), 'CHECK_IN', 'NAVIGATE', 'CHECK_OUT', 'ABSOLUTE_DATETIME', or 'RELATIVE_DATETIME'. Determines when the system will remind users about this checklist item." }, "reminder_data": { "type": "string", "description": "JSON data containing additional information for the reminder. Format depends on the reminder_type. For ABSOLUTE_DATETIME, includes 'absoluteDateTime'. For RELATIVE_DATETIME, includes 'relativeDateTime' with 'baseDate', 'unit', and 'quantity'. Exposed via API as 'reminder_data'.", "oneOf": [ { "type": "object", "properties": { "absoluteDateTime": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}\\ \\d{2}:\\d{2}:\\d{2}$" } }, "required": [ "absoluteDateTime" ], "additionalProperties": false }, { "type": "object", "properties": { "relativeDateTime": { "type": "object", "properties": { "baseDate": { "type": "string", "enum": [ "JOB_CREATE_TIME", "NEXT_BOOKING_TIME" ] }, "unit": { "type": "string", "enum": [ "DAY", "HOUR", "MINUTE" ] }, "quantity": { "type": "integer", "description": "Number of units to add/subtract from base date. Negative quantities mean the reminder occurs before the base date. Reminders scheduled into the past will not occur." } }, "required": [ "baseDate", "unit", "quantity" ] } }, "required": [ "relativeDateTime" ], "additionalProperties": false } ] }, "regarding_object": { "type": "string", "description": "The type of object which this checklist item is related to. For example, for Form checklists, this will be 'Form'." }, "regarding_object_uuid": { "format": "uuid", "example": "123e4567-d957-444e-ae41-231fe671917b", "type": "string", "description": "The UUID of the object which this checklists item is related to. For example, for Form checklists, this is the UUID of the Form that must be completed to complete the checklist item." }, "fulfilled_by_object_name": { "type": "string", "description": "The type of object which completes this checklist item. For example, for Form checklists, this will be 'FormResponse'." }, "fulfilled_by_object_uuid": { "format": "uuid", "example": "123e4567-b3dd-49da-a903-231fe1bbd62b", "type": "string", "description": "The UUID of the object which completes this checklist item. For example, for Form checklists, this references the UUID of a FormResponse record." }, "assigned_to_staff_uuids": { "format": "uuid", "example": "123e4567-34b4-4031-83d0-231fea476a4b", "type": "array", "description": "JSON array of staff UUIDs to whom this checklist item is assigned. Determines which staff members are responsible for completing this checklist item. Currently limited to a maximum of 1 staff member.", "items": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Must be the UUID of a Staff record" }, "maxItems": 1 }, "is_locked": { "type": "integer", "description": "If this checklist item is locked (read-only) and cannot be modified. This is set by the system when the checklist item is created from a Task or Network Request. (Read only). Valid values are [0,1]", "enum": [ 0, 1 ] }, "assigned_timestamp": { "example": "2025-08-01 12:00:00", "type": "string", "description": "The timestamp when the checklist item was assigned to the staff member. (Read only)" }, "assigned_by_staff_uuid": { "format": "uuid", "example": "123e4567-0a21-438c-9868-231fe25489ab", "type": "string", "description": "The UUID of the staff member who assigned the checklist item to the staff member. (Read only)" } } }, "JobContact": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-4e88-44ff-bce9-231fe055036b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "job_uuid": { "format": "uuid", "example": "123e4567-8c94-4581-8d7c-231fe2af612b", "type": "string" }, "first": { "type": "string" }, "last": { "type": "string" }, "phone": { "type": "string" }, "mobile": { "type": "string" }, "email": { "format": "email", "type": "string" }, "type": { "type": "string" }, "is_primary_contact": { "type": "string" } } }, "JobMaterial": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-7fbe-4fa5-a449-231fe25f905b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "job_uuid": { "format": "uuid", "example": "123e4567-e80c-4f95-af78-231fe8cf450b", "type": "string" }, "material_uuid": { "format": "uuid", "example": "123e4567-aae0-4ea2-a2e9-231fe1ee41eb", "type": "string" }, "name": { "type": "string", "maxLength": 500 }, "quantity": { "type": "string", "maxLength": 100 }, "price": { "type": "string" }, "displayed_amount": { "type": "string" }, "displayed_amount_is_tax_inclusive": { "type": "string" }, "tax_rate_uuid": { "format": "uuid", "example": "123e4567-0195-43e5-9d1a-231fe92e08cb", "type": "string" }, "sort_order": { "type": "string" }, "cost": { "type": "string", "description": "The cost of the material for this job. This is the ex-tax amount." }, "displayed_cost": { "type": "string", "description": "The cost of the material for this job, displayed as inc-tax or ex-tax depending on jobMaterial.displayed_amount_is_tax_inclusive." }, "job_material_bundle_uuid": { "format": "uuid", "example": "123e4567-4f02-4800-8b33-231fe98fad0b", "type": "string", "description": "UUID of a JobMaterialBundle which this JobMaterial belongs to. The default value is blank, which means that the JobMaterial is not part of a JobMaterialBundle." } }, "required": [ "quantity" ] }, "JobMaterialBundle": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-7ce3-4a7e-b80c-231fe218d73b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "item_number": { "type": "string", "description": "Unique identifier for the material bundle within the job. Displayed on the Quote/Invoice in the same way as for JobMaterials." }, "name": { "type": "string", "description": "Descriptive name of the job material bundle. Displayed on the Quote/Invoice in the same way as for JobMaterials." }, "quantity": { "type": "string", "description": "The quantity shown for the bundle line item on the invoice. Must be greater than zero. The quantity of each JobMaterial within the bundle is determined by dividing by this value." }, "sort_order": { "type": "integer", "description": "Defines the display order of the JobMaterialBundle relative to other JobMaterials and JobMaterialBundles on the Job. Lower values are displayed first." }, "material_bundle_uuid": { "format": "uuid", "example": "123e4567-f98b-4da5-a6f0-231fef0058fb", "type": "string", "description": "UUID of the MaterialBundle which this JobMaterialBundle was originally created from." }, "job_uuid": { "format": "uuid", "example": "123e4567-33ae-471a-96c2-231fe64b12db", "type": "string", "description": "UUID of the job that this material bundle is associated with. Links the bundle to a specific job record." } } }, "JobPayment": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-3ef9-45ec-aa1c-231fef09d0cb", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "job_uuid": { "format": "uuid", "example": "123e4567-7c88-43a8-87e0-231fe7e7707b", "type": "string" }, "actioned_by_uuid": { "format": "uuid", "example": "123e4567-b70e-4b5b-b68b-231feda912db", "type": "string" }, "timestamp": { "type": "string", "example": "2025-08-01 12:00:00" }, "amount": { "type": "string" }, "method": { "type": "string" }, "note": { "type": "string" }, "attachment_uuid": { "format": "uuid", "example": "123e4567-c48c-42ae-8a2d-231fe31e5ceb", "type": "string" }, "is_deposit": { "type": "integer", "description": "Boolean flag indicating whether this payment represents a deposit against future work (true) rather than a payment for completed work (false). Read-only in the API. (Read only). Valid values are [0,1]", "enum": [ 0, 1 ] } } }, "JobTemplate": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-6d18-48b6-bf7b-231fe2dfed3b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "name": { "type": "string" } } }, "KnowledgeArticle": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-d8e4-4ad3-a684-231fe921ddab", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "name": { "type": "string", "description": "Title of the knowledge article. This is a mandatory field with a maximum length of 100 characters. Used for identifying and searching for articles in the knowledge base." }, "content": { "type": "string", "description": "The main content of the knowledge article. For 'richtext' articles, this contains HTML formatted text. For 'video' articles, this may contain supplementary information. For 'call' articles, this contains call details. Supports extended text length." }, "article_type": { "type": "string", "description": "Type of knowledge article. Valid values are 'video', 'richtext', or 'call'. This determines how the article content is presented and processed in the system." }, "tags": { "type": "string", "description": "Comma-separated list of tags associated with this knowledge article. Maximum length is 2000 characters. Tags are used for categorization, searching, and automatic relationship generation with other objects like Services, Materials, and Companies." }, "relationships": { "type": "array", "description": "JSON array of manually created relationships between this knowledge article and other objects. Contains objects with properties: object_name (e.g., 'job'), object_uuid (the related object's UUID), object_description (a description of the related object), and create_date. Used to associate articles with specific jobs or other system objects.", "items": { "type": "object", "properties": { "object_name": { "type": "string", "enum": [ "Job", "job" ] }, "object_uuid": { "type": "string", "format": "uuid" }, "object_description": { "type": "string" }, "create_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}\\ \\d{2}:\\d{2}:\\d{2}$" } }, "required": [ "object_name", "object_uuid" ] } } }, "required": [ "name" ] }, "Location": { "type": "object", "properties": { "name": { "description": "Location's name", "type": "string", "maxLength": 50 }, "line1": { "description": "First line of the location's address. Contains the street number and street name.", "type": "string", "maxLength": 100 }, "line2": { "description": "Second line of the location's address. Used for additional address information such as building/suite numbers or street details.", "type": "string", "maxLength": 100 }, "line3": { "description": "Third line of the location's address. Used for additional address details when line1 and line2 are not sufficient.", "type": "string", "maxLength": 100 }, "city": { "description": "Email Address", "type": "string", "maxLength": 50 }, "country": { "description": "Email Address", "type": "string", "maxLength": 100 }, "post_code": { "description": "Email Address", "type": "string", "maxLength": 100 }, "phone_1": { "description": "Primary contact phone number for the location. Can include formatting characters.", "type": "string", "maxLength": 100 }, "state": { "description": "Address State", "type": "string", "maxLength": 400 }, "lng": { "description": "Longitude coordinate of the location in decimal degrees format. Used for geolocation and distance calculations. Expected range is between -180 and 180 degrees.", "type": "number", "format": "float" }, "lat": { "description": "Latitude coordinate of the location in decimal degrees format. Used for geolocation and distance calculations. Expected range is between -90 and 90 degrees.", "type": "number", "format": "float" }, "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-827e-42d9-ae0a-231fe5334b4b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" } }, "required": [ "name" ] }, "Material": { "type": "object", "properties": { "name": { "description": "Name of the material, product or labour rate. The maximum length varies based on accounting package integration 30-100 characters for standard mode, up to 2000 characters for description billing mode. Required field that identifies the material in inventory lists, job forms, and invoices.", "type": "string", "maxLength": 70 }, "item_number": { "description": "Unique identifier code for the material. max length. Must be unique within an account.", "type": "string", "maxLength": 30 }, "price": { "description": "The selling price of the material. May include or exclude tax based on the price_includes_taxes field. Used as the default price when adding this material to jobs and generating invoices.", "type": "string" }, "cost": { "description": "The purchase cost of the material. May include or exclude tax depending on the price_includes_taxes setting. Used for profit calculations and reporting. This field may be hidden from users without appropriate permissions.", "type": "string" }, "quantity_in_stock": { "description": "The current inventory quantity of this material available in stock. Stored as a numeric value with decimal support. Updated automatically when materials are used in jobs or when inventory is manually adjusted. Only tracked if item_is_inventoried is enabled.", "type": "number" }, "price_includes_taxes": { "description": "Boolean flag indicating whether the price and cost values include tax (1/true) or exclude tax (0/false). Controls tax calculations when determining final pricing. New materials inherit this setting from the account's default tax display preference.. Valid values are [0,1]", "type": "integer", "enum": [ 0, 1 ] }, "barcode": { "description": "The barcode identifier for the material. Can store UPC, EAN, or other barcode formats. Used for inventory scanning and quick material lookup in the mobile app.", "type": "string" }, "item_is_inventoried": { "description": "Boolean flag indicating whether inventory tracking is enabled for this material (1/true) or disabled (0/false). When enabled, the quantity_in_stock is tracked and updated automatically when the material is used in jobs. Only physical products typically have this enabled.. Valid values are [0,1]", "type": "integer", "enum": [ 0, 1 ] }, "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-92c3-4f3a-b517-231fe7067dfb", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "item_description": { "type": "string" }, "use_description_for_invoicing": { "type": "string" }, "tax_rate_uuid": { "format": "uuid", "example": "123e4567-a398-4a27-89d1-231fea51880b", "type": "string" } }, "required": [ "name" ] }, "MaterialBundle": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-33d0-40fc-a79d-231feec4a52b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "item_number": { "type": "string", "description": "Unique identifier for this bundle. Must be 30 characters or less and unique across both Materials and Bundles. Used when adding bundles to jobs.", "maxLength": 30 }, "name": { "type": "string", "description": "The display name of the bundle. Used for identification in the system and shows on documents when the bundle is added to a job." }, "material_list": { "type": "array", "description": "A JSON array containing the materials that make up this bundle. Each item includes the material's UUID and the quantity to be added when this bundle is used. Limited to between 1 and 50 items, with all quantities being positive numbers.", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Must be the UUID of a Material record" }, "quantity": { "type": "number", "minimum": 0 } }, "required": [ "uuid", "quantity" ] }, "minItems": 1, "maxItems": 50 } }, "required": [ "item_number" ] }, "Note": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-4d86-455c-a329-231fe4f0b73b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "related_object": { "type": "string" }, "related_object_uuid": { "format": "uuid", "example": "123e4567-8f43-4eee-8bf4-231fe2bc71db", "type": "string" }, "note": { "type": "string" }, "action_required": { "type": "string" }, "action_completed_by_staff_uuid": { "format": "uuid", "example": "123e4567-8de7-4794-b7d8-231fe9ea42fb", "type": "string" }, "edit_by_staff_uuid": { "format": "uuid", "example": "123e4567-b34e-4f02-8ec2-231feaa6c21b", "readOnly": true, "description": "UUID of Staff Member who last modified record" }, "create_date": { "example": "2025-08-01 12:00:00", "description": "Timestamp at which record was last modified" } } }, "Queue": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-3935-4c29-8658-231feb60c36b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "name": { "type": "string", "description": "Name of the job queue. Used to identify the queue in the system. Examples include 'Workshop', 'Pending Quotes', etc." }, "default_timeframe": { "type": "integer", "description": "Default number of days that jobs should remain in this queue before requiring attention. Common values are 7 days (1 week) or 14 days (2 weeks)." }, "subscribed_staff": { "type": "string", "description": "Semicolon-delimited list of staff UUIDs who are subscribed to receive notifications for this queue." }, "requires_assignment": { "type": "integer", "description": "Determines if jobs in this queue require assignment to staff members. If true, jobs must be explicitly assigned to staff. If false, jobs are visible to all staff.. Valid values are [0,1]", "enum": [ 0, 1 ] } } }, "SecurityRole": { "type": "object", "properties": { "name": { "description": "The name given to the security role", "type": "string", "maxLength": 50 }, "role_description": { "description": "A detailed description of the security role's purpose and permissions. This field provides information about what access and capabilities are granted to users assigned this role.", "type": "string" }, "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-9fc8-4c04-baee-231fe3498f5b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" } }, "required": [ "name" ] }, "SmsTemplate": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-fbc9-418b-a011-231fe17615eb", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "name": { "type": "string", "maxLength": 50 }, "message": { "type": "string", "maxLength": 612 } }, "required": [ "name" ] }, "Staff": { "type": "object", "properties": { "first": { "description": "Staff First Name", "type": "string", "maxLength": 30 }, "last": { "description": "Staff Last Name", "type": "string", "maxLength": 30 }, "email": { "description": "Staff Email Address. This is also your login name.", "format": "email", "type": "string" }, "mobile": { "description": "Mobile phone number of the staff member. Used for SMS communications and identification when calling.", "type": "string" }, "lng": { "description": "Longitude coordinate of the staff member's current or last known location. Used for tracking staff locations and calculating routes and travel distances.", "type": "number", "format": "float" }, "lat": { "description": "Latitude coordinate of the staff member's current or last known location. Used for tracking staff locations and calculating routes and travel distances.", "type": "number", "format": "float" }, "geo_timestamp": { "description": "The date and time when the staff member's geographic location (lat/lng) was last updated. Format is YYYY-MM-DD HH:MM:SS. Used to determine how recent the location data is.", "example": "2025-08-01 12:00:00", "type": "string" }, "job_title": { "description": "The staff member's job title or role within the organization. Used for organizational purposes and displayed in various places throughout the system.", "type": "string" }, "navigating_to_job_uuid": { "description": "UUID of the job the staff member is currently navigating to. Used to track which job a staff member is traveling toward.", "format": "uuid", "example": "123e4567-eecf-4500-ad06-231fe421384b", "type": "string" }, "navigating_timestamp": { "description": "The date and time when the staff member started navigating to a job. Format is YYYY-MM-DD HH:MM:SS. Used to track when navigation began.", "example": "2025-08-01 12:00:00", "type": "string" }, "navigating_expiry_timestamp": { "description": "The date and time when navigation to a job is expected to complete or expire. Format is YYYY-MM-DD HH:MM:SS. Used to determine if navigation is still active.", "example": "2025-08-01 12:00:00", "type": "string" }, "color": { "description": "The color assigned to this staff member, represented as a hex color code. Used for visual identification in the schedule, dispatch board, and other interfaces.", "type": "string" }, "custom_icon_url": { "description": "DEPRECATED" }, "status_message": { "description": "Short message summarising the staff's current status.", "type": "string" }, "status_message_timestamp": { "description": "The date and time when the staff member's status message was last updated. Format is YYYY-MM-DD HH:MM:SS. Used to determine how recent the status message is.", "example": "2025-08-01 12:00:00", "type": "string" }, "hide_from_schedule": { "description": "Boolean flag controlling whether this staff member appears in the schedule view. When true (1), the staff member is hidden from the schedule. When false (0), they appear normally in scheduling interfaces.. Valid values are [0,1]", "type": "integer", "enum": [ 0, 1 ] }, "security_role_uuid": { "description": "UUID of the primary security role assigned to this staff member. Controls the staff member's permissions and access levels throughout the system.", "format": "uuid", "example": "123e4567-7a01-4347-9dc9-231fe0bf3f1b", "type": "string" }, "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-d3a1-4426-9e45-231fe561552b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "can_receive_push_notification": { "type": "string" } }, "required": [ "first", "last", "email" ] }, "StaffMessage": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-529d-4fa1-92d6-231feb4a300b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "from_staff_uuid": { "format": "uuid", "example": "123e4567-128d-4dc3-b3c0-231fed613e4b", "type": "string" }, "to_staff_uuid": { "format": "uuid", "example": "123e4567-3e6d-4f5b-9a35-231fe1da6bdb", "type": "string" }, "sent_timestamp": { "example": "2025-08-01 12:00:00", "type": "string" }, "delivered_timestamp": { "example": "2025-08-01 12:00:00", "type": "string" }, "read_timestamp": { "example": "2025-08-01 12:00:00", "type": "string" }, "message": { "type": "string" }, "regarding_job_uuid": { "format": "uuid", "example": "123e4567-a93d-4d72-8817-231fe3ae5aab", "type": "string" }, "attached_json": { "type": "string" } } }, "Task": { "type": "object", "properties": { "due_date": { "description": "The date by which the task should be completed. Format is YYYY-MM-DD. For mobile app compatibility, may be returned with time component (HHMMSS) in some contexts.", "example": "YYYY-MM-DD", "type": "string" }, "task_details": { "description": "Detailed description of the task. Contains more comprehensive information about what needs to be done, how to complete the task, or any other relevant notes.", "type": "string" }, "name": { "description": "The name or title of the task. This field is mandatory and used to identify the task in listings and the user interface.", "type": "string" }, "related_object": { "description": "The name of the object class this task is related to. Must be a valid object class name in the system (e.g., 'job', 'client', etc.). The value is always stored as lowercase regardless of input case.", "type": "string" }, "related_object_uuid": { "description": "UUID of the specific object instance this task is related to. Must be a valid UUID corresponding to an existing object of the type specified in related_object.", "format": "uuid", "example": "123e4567-2491-4411-a45a-231fe44158cb", "type": "string" }, "task_complete": { "description": "Boolean flag indicating whether the task has been completed (1) or is still pending (0). When set to 1, the completed_timestamp and completed_by_staff_uuid fields are automatically populated.", "type": "string" }, "completed_timestamp": { "description": "The date and time when the task was marked as complete. Format is YYYY-MM-DD HH:MM:SS. Automatically set when task_complete is changed to 1.", "example": "2025-08-01 12:00:00", "type": "string" }, "completed_by_staff_uuid": { "description": "UUID of the staff member who marked the task as complete. Automatically set to the current staff member's UUID when task_complete is changed to 1.", "format": "uuid", "example": "123e4567-829e-4d2f-bc11-231fea37316b", "type": "string" }, "assigned_to_staff_uuid": { "description": "UUID of the staff member assigned to complete this task. Must be a valid staff UUID in the system.", "format": "uuid", "example": "123e4567-3bd5-4f22-ae68-231febb0903b", "type": "string" }, "lng": { "description": "DEPRECATED" }, "lat": { "description": "DEPRECATED" }, "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-0d3f-49f2-a0d3-231fe8fb030b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "created_by_staff_uuid": { "format": "uuid", "example": "123e4567-0f22-4648-a7e4-231fedb357eb", "type": "string" }, "create_date": { "example": "2025-08-01 12:00:00", "description": "Timestamp at which record was last modified" } }, "required": [ "name" ] }, "TaxRate": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-c493-414a-903d-231fe887188b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "name": { "type": "string", "maxLength": 50 }, "amount": { "type": "string" }, "is_default_tax_rate": { "type": "integer", "enum": [ 0, 1 ], "description": " Valid values are [0,1]" } }, "required": [ "name" ] }, "Vendor": { "type": "object", "properties": { "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-80f3-4b52-bd4b-231fe53cd82b", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2025-08-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" }, "name": { "type": "string", "description": "Company Name", "maxLength": 200 }, "abn_number": { "type": "string" }, "business_number": { "type": "string", "description": "Company Business Number" }, "website": { "type": "string", "description": "Company Website address", "maxLength": 100 }, "email": { "format": "email", "type": "string" }, "email_accounts": { "type": "string" }, "billing_address": { "type": "string" }, "accepted_payment_methods": { "type": "string" }, "default_region": { "type": "string" }, "currency": { "type": "string" }, "opening_time_monday": { "type": "string" }, "closing_time_monday": { "type": "string" }, "opening_time_tuesday": { "type": "string" }, "closing_time_tuesday": { "type": "string" }, "opening_time_wednesday": { "type": "string" }, "closing_time_wednesday": { "type": "string" }, "opening_time_thursday": { "type": "string" }, "closing_time_thursday": { "type": "string" }, "opening_time_friday": { "type": "string" }, "closing_time_friday": { "type": "string" }, "opening_time_saturday": { "type": "string" }, "closing_time_saturday": { "type": "string" }, "opening_time_sunday": { "type": "string" }, "closing_time_sunday": { "type": "string" }, "timezone_name": { "type": "string" }, "invoice_terms": { "type": "string" }, "job_default_status": { "type": "string" } }, "required": [ "name" ] }, "InboxMessageDetail": { "allOf": [ { "$ref": "#/components/schemas/InboxMessage" }, { "type": "object", "properties": {} } ] }, "InboxMessagesResponse": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/InboxMessage" } }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean" } } } } }, "ArchiveRequest": { "type": "object", "properties": { "archived": { "type": "boolean", "default": true }, "reason": { "type": "string", "nullable": true } } }, "SnoozeRequest": { "type": "object", "properties": { "snooze_until": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 datetime to snooze until, or null to unsnooze" }, "note": { "type": "string", "nullable": true } } }, "ConvertToJobRequest": { "type": "object", "properties": { "template_uuid": { "type": "string", "format": "uuid", "nullable": true }, "note": { "type": "string", "nullable": true } } }, "ConvertToJobResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "job": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "id": { "type": "integer" }, "job_number": { "type": "string" }, "location": { "type": "string" } } }, "message": { "type": "string" } } }, "AttachToJobRequest": { "type": "object", "required": [ "job_uuid" ], "properties": { "job_uuid": { "type": "string", "format": "uuid" } } }, "AttachToJobResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "job": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "id": { "type": "integer" }, "location": { "type": "string" } } }, "message": { "type": "string" } } }, "AddNoteRequest": { "type": "object", "required": [ "note" ], "properties": { "note": { "type": "string", "minLength": 1 } } }, "SuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "JobTemplateOverrides": { "type": "object", "description": "Optional field overrides when creating a job from a template. Only the following fields can be overridden: job_description, company_uuid, company_name, and job_address. Note: You cannot specify both company_uuid and company_name.", "properties": { "job_description": { "type": "string", "description": "Job description" }, "company_uuid": { "type": "string", "format": "uuid", "description": "UUID of the company/client. Cannot be used together with company_name." }, "company_name": { "type": "string", "description": "Name of the company/client. If a company with this name exists, it will be used. Otherwise, a new company will be created. Cannot be used together with company_uuid." }, "job_address": { "type": "string", "description": "Street address for the job" } }, "additionalProperties": false }, "SearchResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, "query": { "type": "string", "description": "The search query that was used" }, "count": { "type": "integer", "description": "Number of results returned" } }, "required": [ "results", "query", "count" ] }, "ObjectSearchResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, "query": { "type": "string", "description": "The search query that was used" }, "objectType": { "type": "string", "description": "The object type that was searched" }, "count": { "type": "integer", "description": "Number of results returned" } }, "required": [ "results", "query", "objectType", "count" ] }, "EmbeddingSearchResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/EmbeddingSearchResult" } }, "query": { "type": "string", "description": "The search query that was used" }, "count": { "type": "integer", "description": "Number of results returned" }, "searchType": { "type": "string", "description": "Type of search performed", "example": "embedding" } }, "required": [ "results", "query", "count", "searchType" ] }, "SearchResult": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID of the found object" }, "type": { "type": "string", "description": "Type of the object", "example": "job" }, "title": { "type": "string", "description": "Title of the object" }, "highlights": { "type": "object", "description": "Highlighted text snippets that matched the query", "additionalProperties": true } }, "required": [ "uuid", "type", "title" ] }, "EmbeddingSearchResult": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID of the found job" }, "type": { "type": "string", "description": "Type of the object", "example": "job" }, "title": { "type": "string", "description": "Title of the job" }, "description": { "type": "string", "description": "Job description" }, "status": { "type": "string", "description": "Current job status" }, "similarity_score": { "type": "number", "format": "float", "description": "Similarity score between 0.0 and 1.0", "minimum": 0, "maximum": 1 }, "matched_content": { "type": "string", "description": "The content that was matched in the embedding search" } }, "required": [ "uuid", "type", "title", "similarity_score" ] } } }, "x-speakeasy-retries": { "strategy": "backoff", "backoff": { "initialInterval": 500, "maxInterval": 60000, "maxElapsedTime": 3600000, "exponent": 1.5 }, "statusCodes": [ "5XX", "429" ], "retryConnectionErrors": true }, "tags": [ { "name": "Allocation Windows", "description": "Operations related to Allocation Windows" }, { "name": "Assets", "description": "Operations related to Assets" }, { "name": "Asset Types", "description": "Operations related to Asset Types" }, { "name": "Asset Type Fields", "description": "Operations related to Asset Type Fields" }, { "name": "Attachments", "description": "Operations related to Attachments" }, { "name": "Badges", "description": "Operations related to Badges" }, { "name": "Categories", "description": "Operations related to Categories" }, { "name": "Clients", "description": "Operations related to Clients" }, { "name": "Company Contacts", "description": "Operations related to Company Contacts" }, { "name": "Document Templates", "description": "Operations related to Document Templates" }, { "name": "Email Templates", "description": "Operations related to Email Templates" }, { "name": "Feedback", "description": "Operations related to Feedback" }, { "name": "Forms", "description": "Operations related to Forms" }, { "name": "Form Fields", "description": "Operations related to Form Fields" }, { "name": "Form Responses", "description": "Operations related to Form Responses" }, { "name": "", "description": "Operations related to " }, { "name": "Jobs", "description": "Operations related to Jobs" }, { "name": "Job Activities", "description": "Operations related to Job Activities" }, { "name": "Job Allocations", "description": "Operations related to Job Allocations" }, { "name": "Job Checklists", "description": "Operations related to Job Checklists" }, { "name": "Job Contacts", "description": "Operations related to Job Contacts" }, { "name": "Job Materials", "description": "Operations related to Job Materials" }, { "name": "Job Material Bundles", "description": "Operations related to Job Material Bundles" }, { "name": "Job Payments", "description": "Operations related to Job Payments" }, { "name": "Job Templates", "description": "Operations related to Job Templates" }, { "name": "Knowledge Articles", "description": "Operations related to Knowledge Articles" }, { "name": "Locations", "description": "Operations related to Locations" }, { "name": "Materials", "description": "Operations related to Materials" }, { "name": "Bundles", "description": "Operations related to Bundles" }, { "name": "Notes", "description": "Operations related to Notes" }, { "name": "Job Queues", "description": "Operations related to Job Queues" }, { "name": "Security Roles", "description": "Operations related to Security Roles" }, { "name": "SMS Templates", "description": "Operations related to SMS Templates" }, { "name": "Staff Members", "description": "Operations related to Staff Members" }, { "name": "Staff Messages", "description": "Operations related to Staff Messages" }, { "name": "Tasks", "description": "Operations related to Tasks" }, { "name": "Tax Rates", "description": "Operations related to Tax Rates" }, { "name": "Vendors", "description": "Vendor account information" } ] }