---
title: "Create a dispatch on a matter"
method: POST
path: "/api/v1/dispatches"
---

# Create a dispatch on a matter

`POST /api/v1/dispatches`

## Request

- Base URL: `https://scope.bid`
- URL: `https://scope.bid/api/v1/dispatches`
- Auth: HTTP bearer

Sets the matter's service category, opens it, and runs the rate-card dispatcher. A dispatch requested through the API does NOT go out on its own: it parks for human approval and returns 409 (see responses). RBAC: the dispatch.create capability.

## Request body

- object
  - `scope_id` string, required: Matter id (SC-XXXX or UUID).
  - `service_category` string, required: Service category slug.

## Response `201`

The request was accepted; the outcome object says what happened, and it may be that nothing was dispatched. outcome.status 'no_coverage' means no qualified professional covers this matter (dispatch_id is null and nothing was sent); 'incomplete_intake' means required intake fields are missing (listed in missing_fields; nothing was sent). A dispatch that parks for approval or is held returns 409, not 201.

## Other responses

- `400`: Missing fields or unknown category.
- `401`: Missing or invalid access token.
- `403`: The caller is not authorized: the caller's role does not grant the required capability, the partner token lacks the required scope, or the partner is not authorized to act for this firm.
- `404`: Scope not found.
- `409`: Nothing was dispatched and nothing is committed by this request (committed: false). The body is one of: error 'approval_required' with outcome.status 'pending_approval' (a person at the firm must approve this professional at this price; the approver is notified with a release link and can release it from /approvals); error 'no_approver_at_firm' (the firm has no user on Scope to route the approval to); a spend-ceiling hold, outcome.status 'blocked_by_ceiling' (the dispatch crosses the firm's period spend ceiling and nothing was sent; it can go out once Scope raises the firm's ceiling, as the resolution field says: contact info@scope.bid); error 'records_card_incomplete' (no available records professional lists their at-cost rates on their rate card for this category); error 'already_engaged' (the matter already has a work order); error 'award_pending_approval' or 'award_being_released' (an award on this matter is waiting for approval, or is being committed, under its current service category, so the category was not changed; 'award_being_released' is retryable); or error 'requested_by_conflict' (requested_by_user_id names someone other than the matter's current contact; resend without it to dispatch). On 'approval_required', outcome.total_cents is the professional's price. Beside the professional's price, five fields say what the firm will be billed if it approves. firm_total_cents (integer or null): the estimated firm total, the professional's price plus Scope's fee line, computed with the invoice's own arithmetic on the terms on file now; null when Scope cannot determine the fee before the job is sent. scope_fee_cents (integer or null): Scope's fee line as it would be billed; null when firm_total_cents is null. scope_fee_label (string): the invoice line Scope's fee appears under, "Service coordination and compliance record". firm_total_is_estimate (boolean or null): true whenever firm_total_cents is a number, because the amount billed is set when the job is sent (for example, the professional's current rates apply then); null when firm_total_cents is null. billing_note (string): one sentence for a person: the estimated firm total with the invoice's two lines and why it can move; or the professional's price and the sentence that Scope's fee is added on the invoice; or, when Scope could not read the price, that sentence alone. These fields describe the bill; they do not change what is approved or sent. Only the 'approval_required' body carries these fields.
- `429`: Per-tenant rate limit exceeded.
- `500`: Dispatch failed; nothing was sent.
- `503`: A transient read failure stopped the approval step. Nothing was dispatched, nothing is committed, and nothing was parked (committed: false, retryable: true). Retry the request.

---

[API](https://skmtc.dev/scope/apis/scope-api.md) · [All operations](https://skmtc.dev/scope/apis/scope-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scope/apis/scope-api/revisions/164347b416ac?raw)