17 KiB
Executable File
17 KiB
Executable File
List all Job Allocations
Filtering
This endpoint supports result filtering. For more information on how to filter this request, go here.
OAuth Scope
This endpoint requires the following OAuth scope read_schedule.
OpenAPI definition
{
"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"
}
]
}