440 lines
17 KiB
Markdown
Executable File
440 lines
17 KiB
Markdown
Executable File
# 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"
|
|
}
|
|
]
|
|
}
|
|
``` |