---
title: "Create a dispatch request"
method: POST
path: "/v1/dispatch_requests"
tags: ["Dispatch requests"]
---

# Create a dispatch request

`POST /v1/dispatch_requests`

## Request

- Base URL: `https://api.navigateai.co`
- URL: `https://api.navigateai.co/v1/dispatch_requests`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/navigateai/apis/navigateai-api/docs/v1/dispatch_requests/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- CreateDispatchRequestRequest
  - `location_id` string, required: NavigateAI identifier for the location where work should be performed.
  - `visit_type_slug` string, required: Slug identifying the visit type to use for this request.
  - `reference_key` string, nullable: Optional customer-provided identifier for this request, unique within your organization. Reusing a key returns the existing request unchanged with status 200 — the rest of the body is still validated but not applied; a new key creates a request and returns 201.
  - `assignee_email` string, nullable: Email address of the user to assign to this request, if any. Matching ignores case.
  - `work_order_id` string, nullable: NavigateAI identifier for the related work order, if one is provided.
  - `prefill_scope_id` string, nullable: NavigateAI identifier for the scope to prefill the visit with, if one is provided.
  - `target_scope_id` string, nullable: NavigateAI identifier for the scope whose work the visit checks or updates. Cannot be combined with prefill_scope_id.
  - `metadata` object, nullable: Customer-provided metadata to associate with this request.

## Response `200`

OK

- DispatchRequestResponse
  - `dispatch_request` DispatchRequestExternalSchema, required
    - `id` string, required: NavigateAI identifier for this dispatch request.
    - `location_id` string, required: NavigateAI identifier for the location where work should be performed.
    - `visit_type_slug` string, required: Slug identifying the visit type to use for this request.
    - `work_order_id` string, nullable, required: NavigateAI identifier for the related work order, if one was provided.
    - `prefill_scope_id` string, nullable, required: NavigateAI identifier for the scope to prefill the visit with, if one was provided.
    - `target_scope_id` string, nullable, required: NavigateAI identifier for the scope whose work the visit checks or updates, if one was provided.
    - `assignee_email` string, nullable, required: Email address of the user assigned to this request, if any.
    - `reference_key` string, nullable, required: Optional customer-provided identifier for this request, unique within your organization.
    - `status` 'unstarted' | 'started' | 'submitted' | 'completed' | 'cancelled', required: Current lifecycle status of this dispatch request, independent of assignment.
    - `created_at` string, date-time, required: When this dispatch request was created.
    - `assigned_at` string, date-time, nullable, required: When the current assignee was assigned, if applicable. Assignment is independent of lifecycle status.
    - `started_at` string, date-time, nullable, required: When work on this request began, such as a capture session starting or a visit being created for it. Null if work has not started.
    - `submitted_at` string, date-time, nullable, required: When the field work for this request was submitted, meaning capture finished or an upload of already-captured data began. Uploads may still be finishing. Capture flows that do not report submission separately set this when the request completes.
    - `completed_at` string, date-time, nullable, required: When work on this request was completed, which is when its uploads finished, if applicable.
    - `cancelled_at` string, date-time, nullable, required: When this request was cancelled, if applicable.
    - `metadata` object, required: Customer-provided metadata associated with this request.
    - `deeplink_url` string, required: Mobile deeplink that opens the NavigateAI app directly to the capture flow for this request. Share it with the assignee to have their capture tracked against this request; see the deeplinks guide.

## Other responses

- `201`: Created

## Changes

- **2026-10-15** `b928dbabd4e8`: 3 info
  - added the new optional request property `target_scope_id`
  - added the required property `dispatch_request/target_scope_id` to the response with the `200` status
  - added the required property `dispatch_request/target_scope_id` to the response with the `201` status
- **2026-10-14** `bbdde99b5256`: 2 breaking, 1 warning, 3 info
  - removed the required property `dispatch_request/assignee_user_id` from the response with the `200` status
  - removed the required property `dispatch_request/assignee_user_id` from the response with the `201` status
  - removed the request property `assignee_user_id`
  - added the new optional request property `assignee_email`
  - …2 more
- **2026-10-06** `abd5663eb6b6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/navigateai/apis/navigateai-api/changes/v1/dispatch_requests/post.md)

---

[API](https://skmtc.dev/navigateai/apis/navigateai-api.md) - [All operations](https://skmtc.dev/navigateai/apis/navigateai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/navigateai/apis/navigateai-api/revisions/912b48581de7?raw)