# List all Job Allocations #### Filtering This endpoint supports result filtering. For more information on how to filter this request, [go here](/docs/filtering). #### OAuth Scope This endpoint requires the following OAuth scope **read_schedule**. # OpenAPI definition ```json { "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": { "/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-aa11-4415-ac38-23f94bc904db", "active": 1, "edit_date": "2026-03-01 12:00:00", "job_uuid": "123e4567-ef33-4570-9929-23f945326d1b", "queue_uuid": "123e4567-e495-4a8d-a253-23f9408ba0db", "staff_uuid": "123e4567-e0d8-481f-b4bb-23f944e9c86b", "allocation_date": "2026-03-01 12:00:00", "allocation_window_uuid": "123e4567-0f0c-48b9-8570-23f94fcc00db", "allocated_by_staff_uuid": "123e4567-ab70-4071-8066-23f94537066b", "allocated_timestamp": "2026-03-01 12:00:00", "expiry_timestamp": "2026-03-01 12:00:00", "read_timestamp": "2026-03-01 12:00:00", "completion_timestamp": "2026-03-01 12:00:00", "estimated_duration": "string", "revised_duration": "string", "sort_priority": "string", "requires_acceptance": "string", "acceptance_status": "string", "acceptance_timestamp": "2026-03-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." } } } } } } } } } }, "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": { "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." } } }, "JobAllocation": { "type": "object", "properties": { "job_uuid": { "description": "The UUID of the job that this allocation relates to.", "format": "uuid", "example": "123e4567-796e-43d3-89b8-23f942b7f0ab", "type": "string" }, "queue_uuid": { "description": "DEPRECATED" }, "staff_uuid": { "description": "The UUID of the staff member this job is allocated to.", "format": "uuid", "example": "123e4567-4525-400b-ab3e-23f94473c62b", "type": "string" }, "allocation_date": { "description": "The minimum start date for a job allocation to be completed by a staff member. Setting this date will ensure the job allocation appears in the future on staff schedules.", "example": "2026-03-01 12:00:00", "type": "string" }, "allocation_window_uuid": { "description": "The UUID of the allocation window that defines when the job should be completed (e.g. Urgent, Early Morning, During Business Hours).", "format": "uuid", "example": "123e4567-7fd1-45f3-8068-23f945565e9b", "type": "string" }, "allocated_by_staff_uuid": { "description": "The UUID of the staff member who allocated the job.", "format": "uuid", "example": "123e4567-c873-4cca-91e7-23f943de293b", "type": "string" }, "allocated_timestamp": { "description": "The timestamp when the job was allocated.", "example": "2026-03-01 12:00:00", "type": "string" }, "expiry_timestamp": { "description": "The timestamp when the job allocation expires.", "example": "2026-03-01 12:00:00", "type": "string" }, "read_timestamp": { "description": "The timestamp when the job allocation was read by the staff member.", "example": "2026-03-01 12:00:00", "type": "string" }, "completion_timestamp": { "description": "The timestamp when the job allocation was marked as completed.", "example": "2026-03-01 12:00:00", "type": "string" }, "estimated_duration": { "description": "DEPRECATED" }, "revised_duration": { "description": "DEPRECATED" }, "sort_priority": { "description": "The sort priority for displaying this job allocation.", "type": "string" }, "requires_acceptance": { "description": "DEPRECATED" }, "acceptance_status": { "description": "DEPRECATED" }, "acceptance_timestamp": { "description": "DEPRECATED" }, "uuid": { "format": "uuid", "description": "Unique identifier for this record", "example": "123e4567-8160-4f2d-951a-23f94c5382cb", "type": "string" }, "active": { "enum": [ 0, 1 ], "type": "integer", "default": 1, "description": "Record active/deleted flag. Valid values are [0,1]" }, "edit_date": { "example": "2026-03-01 12:00:00", "readOnly": true, "description": "Timestamp at which record was last modified" } } } } }, "x-speakeasy-retries": { "strategy": "backoff", "backoff": { "initialInterval": 500, "maxInterval": 60000, "maxElapsedTime": 3600000, "exponent": 1.5 }, "statusCodes": [ "5XX", "429" ], "retryConnectionErrors": true }, "tags": [ { "name": "Job Allocations", "description": "Operations related to Job Allocations" } ] } ```