--- updatedAt: 2026-07-01T11:37:16.000Z --- Fetch the complete documentation index at: https://developer.servicem8.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version. # Create a new Job #### OAuth Scope This endpoint requires the following OAuth scope **create_jobs**. #### Record UUID UUID 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. # 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\n\n## Opening Records in ServiceM8\nWhen you need to send a staff member from an external app to a ServiceM8 record in the web app, build the URL using the record UUID on the primary app domain:\n\n* Job: `https://go.servicem8.com/OpenJob/{job_uuid}`\n* Client: `https://go.servicem8.com/OpenClient/{company_uuid}`\n\nClient records are exposed by the Company endpoint in the REST API, so use the Company record `uuid` as `{company_uuid}`. These URLs are web app links, not REST API endpoints, and do not use API authentication. Users who are not signed in are redirected through login and then back to the requested record. The signed-in staff member must have access to the record and the relevant ServiceM8 menu permission.\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": { "/job.json": { "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/JobCreate" } } } }, "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." } } } } } } } } } }, "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", "read_service_templates": "Read access to ServiceTemplates", "manage_service_templates": "Full access to manage ServiceTemplates", "read_email": "Read job email history", "read_sms": "Read job SMS history", "create_notifications": "Create staff notifications", "publish_diary_items": "Create immutable Add-on Job Diary items", "read_job_admin_activity": "Read-only access to job administration time records" } } } } }, "schemas": { "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." } } }, "Error": { "type": "object", "properties": { "errorCode": { "type": "number", "format": "int32", "example": "1000" }, "message": { "type": "string", "example": "An error occurred completing your request" } } }, "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." } } }, "JobCreate": { "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-820f-7d94-8a1e-a64d9f43bccb", "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-820f-7d94-8a1e-840ead6191ab", "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" }, "lng": { "description": "Longitude coordinate of the job location. Used for mapping and geolocation features. This is automatically populated based on the job address through geocoding." }, "lat": { "description": "Latitude coordinate of the job location. Used for mapping and geolocation features. This is automatically populated based on the job address through geocoding." }, "payment_date": { "description": "Not used. Refer to JobPayment endpoint.", "example": "2026-09-01 12:00:00", "type": "string" }, "payment_actioned_by_uuid": { "description": "Not used. Refer to JobPayment endpoint.", "format": "uuid", "example": "123e4567-820f-7d94-8a1f-cae2f9076acb", "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-820f-7d94-8a1e-eca3d5b88f4b", "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 was successful. When true, the latitude and longitude coordinates are considered accurate for mapping and location-based features." }, "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.. Valid values are [0,1]", "type": "integer", "enum": [ 0, 1 ] }, "invoice_sent_stamp": { "description": "Timestamp when the invoice was sent to the client. Format is YYYY-MM-DD HH:MM:SS." }, "invoice_date": { "description": "The date the invoice was issued. This determines when payment is due based on the client's payment terms. Automatically set when a job is completed or manually when invoice is created.", "example": "2026-09-01 12:00:00", "type": "string" }, "ready_to_invoice": { "description": "DEPRECATED" }, "ready_to_invoice_stamp": { "description": "DEPRECATED" }, "geo_country": { "description": "The country component extracted from the geocoded job address. Automatically populated when an address is geocoded." }, "geo_postcode": { "description": "The postal/zip code component extracted from the geocoded job address. Automatically populated when an address is geocoded." }, "geo_state": { "description": "The state/province component extracted from the geocoded job address. Automatically populated when an address is geocoded." }, "geo_city": { "description": "The city/locality component extracted from the geocoded job address. Automatically populated when an address is geocoded." }, "geo_street": { "description": "The street name component extracted from the geocoded job address. Automatically populated when an address is geocoded." }, "geo_number": { "description": "The street number component extracted from the geocoded job address. Automatically populated when an address is geocoded." }, "queue_uuid": { "description": "The UUID of the queue this job belongs to.", "format": "uuid", "example": "123e4567-820f-7d94-8a1f-717de042d03b", "type": "string" }, "queue_expiry_date": { "description": "The date and time when the job expires from the queue.", "example": "2026-09-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-820f-7d94-8a1e-5f8aa1a0661b", "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": "2026-09-01 12:00:00", "type": "string" }, "quote_sent": { "description": "Boolean flag indicating whether a quote has been sent to the client for this job.. 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." }, "work_order_date": { "description": "The date and time that the job status was changed to Work Order.", "example": "2026-09-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-820f-7d94-8a1f-dee7696d3d3b", "type": "string" }, "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" }, "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_received": { "type": "integer", "description": "Indicates whether full payment has been received for this job.. Valid values are [0,1]", "enum": [ 0, 1 ] }, "completion_date": { "example": "2026-09-01 12:00:00", "type": "string", "description": "The date and time that the job status was changed to Completed." }, "unsuccessful_date": { "example": "2026-09-01 12:00:00", "type": "string", "description": "The date and time that the job status was changed to Unsuccessful." } }, "required": [ "status" ] }, "RateLimitError": { "type": "object", "properties": { "errorCode": { "type": "number", "format": "int32", "example": "429" }, "message": { "type": "string", "example": "Number of allowed API requests per minute exceeded" } } }, "Result": { "type": "object", "properties": { "errorCode": { "type": "number", "format": "int32", "example": "0" }, "message": { "type": "string", "example": "OK" } } } } }, "x-speakeasy-retries": { "strategy": "backoff", "backoff": { "initialInterval": 500, "maxInterval": 60000, "maxElapsedTime": 3600000, "exponent": 1.5 }, "statusCodes": [ "5XX", "429" ], "retryConnectionErrors": true }, "tags": [ { "name": "Jobs", "description": "Operations related to Jobs" } ] } ```