Dispatch Work Orders API

openapi: 3.2.0
info:
  title: Dispatch REST API v3 Work Orders API
  version: '3'
  summary: Field-service orchestration API for jobs, customers, organizations, appointments and work orders.
  description: The Dispatch REST API lets job sources (warranty companies, equipment manufacturers, lead-generation platforms) and service enterprises interact with Dispatch's core business objects to implement their service workflow on the Dispatch platform. Job sources authenticate with OAuth 2.0 client credentials; individual service providers authenticate with the resource-owner password grant.
  contact:
    name: Dispatch
    url: https://dispatch.me/contact
    email: sales@dispatch.me
  x-documentation: https://github.com/DispatchMe/v3-api-docs
servers:
- url: https://api.dispatch.me
  description: Production
- url: https://api-sandbox.dispatch.me
  description: Sandbox
security:
- bearerAuth: []
tags:
- name: Work Orders
  description: Composite object creating jobs, customers, organizations and appointments in one call.
paths:
  /v3/work_orders:
    post:
      operationId: createWorkOrder
      tags:
      - Work Orders
      summary: Create a work order
      description: The recommended entry point. A work order carries all the information needed to create the job, customer, organization and appointment windows in one call, and selects an orchestration algorithm for offering or assigning the work.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkOrder'
      responses:
        '201':
          description: Work order created
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /v3/work_orders/{id}:
    parameters:
    - $ref: '#/components/parameters/id'
    patch:
      operationId: updateWorkOrder
      tags:
      - Work Orders
      summary: Update a work order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkOrder'
      responses:
        '200':
          description: The updated work order
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /v3/work_orders/{id}/cancel:
    parameters:
    - $ref: '#/components/parameters/id'
    post:
      operationId: cancelWorkOrder
      tags:
      - Work Orders
      summary: Cancel a work order
      description: Canceling cancels the job and the status of all child appointments.
      responses:
        '200':
          description: Work order canceled
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    AppointmentWindow:
      type: object
      properties:
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
    Organization:
      type: object
      required:
      - name
      - email
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
        external_ids:
          type: array
          items:
            type: string
        address:
          $ref: '#/components/schemas/Location'
        phone_number:
          type: string
          description: RFC 3966 format
        email:
          type: string
          format: email
        logo_token:
          type: string
          description: Token for the organization logo in the Dispatch file system
    Contact:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        first_name:
          type: string
        last_name:
          type: string
        company_name:
          type: string
        external_id:
          type: string
        primary:
          type: boolean
        notes:
          type: string
        phone_numbers:
          type: array
          items:
            $ref: '#/components/schemas/ContactMethod'
        email_addresses:
          type: array
          items:
            $ref: '#/components/schemas/ContactMethod'
        billing_address:
          $ref: '#/components/schemas/Location'
    ContactMethod:
      type: object
      properties:
        label:
          type: string
          description: 'For example: mobile, work'
        value:
          type: string
        preferred:
          type: boolean
    WorkOrder:
      type: object
      description: The recommended integration surface - carries everything needed to create a job, its customer, its organization and appointment windows in one request.
      required:
      - title
      - location
      properties:
        title:
          type: string
        description:
          type: string
          description: Markdown is supported
        service_type:
          type: string
        brand_id:
          type: integer
        orchestration:
          $ref: '#/components/schemas/OrchestrationAlgorithm'
        external_id:
          type: string
        location:
          $ref: '#/components/schemas/Location'
        appointment_windows:
          type: array
          description: Optional windows for the organization to choose from.
          items:
            $ref: '#/components/schemas/AppointmentWindow'
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        organizations:
          type: array
          description: Organizations to send or offer the work to. In direct_* orchestration only a single organization is permitted.
          items:
            $ref: '#/components/schemas/Organization'
    OrchestrationAlgorithm:
      type: string
      description: direct_offer offers the job to a single organization (job starts in offered status); direct_assign assigns the job to a single organization (job starts in unscheduled status).
      enum:
      - direct_offer
      - direct_assign
    Location:
      type: object
      description: Locations are not business objects, but attributes on several core objects. Dispatch currently supports locations in the US and Canada only.
      required:
      - street_1
      - city
      properties:
        street_1:
          type: string
        street_2:
          type: string
        city:
          type: string
        state:
          type: string
          description: Two-character state/province abbreviation
        postal_code:
          type: string
          description: 5-digit US or 6-character Canadian postal code
        timezone:
          type: string
          description: IANA timezone. If not provided Dispatch attempts to derive it from the postal code.
  parameters:
    id:
      name: id
      in: path
      required: true
      schema:
        type: integer
  responses:
    NotFound:
      description: Not Found - requested resource could not be found.
    Unauthorized:
      description: Unauthorized - your OAuth2 bearer token is incorrect or expired.
    UnprocessableEntity:
      description: Unprocessable Entity - your request payload did not pass validation rules. See the response body for details.
    Forbidden:
      description: Forbidden - your credentials are correct, but you are not allowed to perform this action.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 bearer token obtained from POST /v3/oauth/token. Tokens are temporary (expires_in is returned with the token) and must be refreshed on 401.
    oauth2:
      type: oauth2
      description: OAuth 2.0. Job sources use client_credentials; individual service providers use the resource-owner password grant. Dispatch does not document a scope vocabulary - access is governed by an account-level ACL agreed with the account manager.
      flows:
        clientCredentials:
          tokenUrl: https://api.dispatch.me/v3/oauth/token
          refreshUrl: https://api.dispatch.me/v3/oauth/token
          scopes: {}
        password:
          tokenUrl: https://api.dispatch.me/v3/oauth/token
          refreshUrl: https://api.dispatch.me/v3/oauth/token
          scopes: {}
x-apievangelist:
  generated: '2026-07-20'
  method: generated
  source: https://github.com/DispatchMe/v3-api-docs/blob/master/source/index.html.md
  note: Dispatch publishes no machine-readable specification. This document was generated faithfully from the provider's own public REST API v3 documentation repository (DispatchMe/v3-api-docs, a public Slate docs site). Paths, methods, entity attributes, query parameters, statuses and error codes are transcribed from that source. Nothing was invented. Where the docs describe a list operation in prose without printing the endpoint line, the operation is flagged with x-path-inferred.