---
title: "Award a dispatch to a vendor"
method: POST
path: "/api/v1/dispatches/{dispatch_id}/award"
---

# Award a dispatch to a vendor

`POST /api/v1/dispatches/{dispatch_id}/award`

## Request

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

Resolves vendor_name against the matter's qualified vendor set. An award requested through this endpoint does NOT commit the firm: it parks as a pending approval and returns 409, and the award commits when a person at the firm releases it from the approvals queue. A pre-authorization never covers a request made through this endpoint, so this holds whatever pre-authorized spending the firm has set. RBAC: the dispatch.award capability, or a partner token with the dispatch scope.

## Path parameters

- `dispatch_id` string, required

## Request body

- object
  - `vendor_name` string, required

## Response `200`

Awarded. Not returned for an award requested through this endpoint today: the unconditional human-approval gate parks every such award (see 409), and the release happens from the firm's approvals queue, not by retrying this call.

## Other responses

- `400`: vendor_name is required.
- `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`: Dispatch not found.
- `409`: Nothing was sent and nothing is committed. Parked for human approval is the ordinary outcome of a valid call: { error: 'approval_required', message, status: 'pending_approval', approval_id, committed: false, resolution } - a person at the firm is notified with a release link and releases it from /approvals. { error: 'no_approver_at_firm', status: 'no_approver_at_firm', approval_id: null } means the firm has no user on Scope to route the approval to: no approval exists and nobody was notified, and somebody has to join or claim the firm's workspace before re-running the award. A 409 with reason 'blocked_by_ceiling' means the firm's spend ceiling stopped the award before the approval gate: the body carries the ceiling detail instead of an approval, nothing was sent, and it can go out once Scope raises the firm's ceiling (contact info@scope.bid).
- `422`: vendor_name did not resolve to exactly one qualified vendor (no match or ambiguous; the body lists qualified_vendors), or the dispatch has no qualified vendors to award.
- `429`: Per-tenant rate limit exceeded.
- `503`: A transient read failure stopped the approval step. Nothing was sent, 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)