scope-bid Dispatches API

openapi: 3.2.0
info:
  title: Scope Bid Dispatches API
  version: 1.1.0
  description: 'Operations tagged Dispatches across 2 of this provider''s published API definitions: scope-bid-openapi.json, scope-bid-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://scope.bid
  description: Production
security:
- bearerAuth: []
tags:
- name: Dispatches
paths:
  /api/v1/dispatches:
    post:
      summary: Create a dispatch on a matter
      description: '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.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - scope_id
              - service_category
              properties:
                scope_id:
                  type: string
                  description: Matter id (SC-XXXX or UUID).
                service_category:
                  type: string
                  description: Service category slug.
      responses:
        '201':
          description: 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.
        '400':
          description: Missing fields or unknown category.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Scope not found.
        '409':
          description: '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':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: Dispatch failed; nothing was sent.
        '503':
          description: '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.'
      tags:
      - Dispatches
      operationId: postApiV1Dispatches
      x-operation-id-source: derived
    servers:
    - url: https://scope.bid
      description: Production
  /api/v1/dispatches/{dispatch_id}:
    get:
      summary: Read dispatch status
      parameters:
      - name: dispatch_id
        in: path
        required: true
        schema:
          type: string
        description: PJ-XXXX or UUID.
      responses:
        '200':
          description: 'Full dispatch state: the professional, pricing, lifecycle timestamps, UTBMS codes, recent audit events, and dashboard, the matter envelope (the same one scope_get_matter returns), whose data.execution is the matter''s execution record.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  dispatch_id:
                    type: string
                  scope_id:
                    type:
                    - string
                    - 'null'
                  status:
                    type: string
                  vendor:
                    type:
                    - object
                    - 'null'
                    properties:
                      vendor_id:
                        type: string
                      name:
                        type: string
                      slug:
                        type: string
                  pricing:
                    type: object
                    properties:
                      awarded_amount:
                        type:
                        - number
                        - 'null'
                  utbms:
                    type: object
                    properties:
                      task_code:
                        type:
                        - string
                        - 'null'
                      activity_code:
                        type:
                        - string
                        - 'null'
                  lifecycle:
                    type: object
                    properties:
                      awarded_at:
                        type:
                        - string
                        - 'null'
                        format: date-time
                      completed_at:
                        type:
                        - string
                        - 'null'
                        format: date-time
                      confirmed_at:
                        type:
                        - string
                        - 'null'
                        format: date-time
                  recent_events:
                    type: array
                    items:
                      type: object
                  dashboard:
                    type:
                    - object
                    - 'null'
                    description: The matter envelope for the dispatch's matter. Null when the dispatch has no matter or the envelope could not be built.
                    properties:
                      summary:
                        type: string
                      data:
                        type: object
                        properties:
                          type:
                            type: string
                            enum:
                            - matter
                          title:
                            type: string
                          totals:
                            type: object
                          rows:
                            type: array
                            items:
                              type: object
                          metadata:
                            type: object
                            description: scope_id, display_id, status, dispatch_id, awarded_vendor_id, work_order_status, work_completed, work_accepted, work_disputed, unread_messages.
                          execution:
                            type:
                            - object
                            - 'null'
                            description: The matter's execution record, built by the same loader and builder as the firm's matter page, so the two never disagree. Null for a draft, or when the record or its work order could not be read; never a partial guess.
                            properties:
                              stages:
                                type: array
                                description: Every step of the record, in the order the firm's matter page shows them.
                                items:
                                  type: object
                                  properties:
                                    stage:
                                      type: string
                                      enum:
                                      - requested
                                      - approval
                                      - dispatched
                                      - documents
                                      - accepted
                                      - started
                                      - progress
                                      - delivered
                                      - checked
                                      - review
                                      - completed
                                      - invoiced
                                      - paid
                                      - exception
                                    key:
                                      type: string
                                    label:
                                      type: string
                                    state:
                                      type: string
                                      enum:
                                      - done
                                      - current
                                      - alert
                                      - unknown
                                      - reported
                                      - superseded
                                      description: 'done: recorded. current: in progress. alert: needs attention. unknown: not confirmed, or not checked (read check). reported: the professional''s own report, not a fact Scope checked. superseded: it happened and does not hold for the live work order. Used for a CORE records milestone from an earlier work order, or from an earlier award of this work order (its note says which), and for the live run''s ''Record checked'' and ''Records checked'' steps once a file the run now lists as checked was rejected, replaced or withdrawn. The marking is per run: the trail does not say which file a ''Record checked'' step checked, so a check of an item the run later checked again with a new file reads by that new file.'
                                    at:
                                      type:
                                      - string
                                      - 'null'
                                      format: date-time
                                    note:
                                      type:
                                      - string
                                      - 'null'
                                    detail:
                                      type:
                                      - string
                                      - 'null'
                              next:
                                type:
                                - string
                                - 'null'
                                description: The next expected step, when it is known.
                              headline:
                                type:
                                - string
                                - 'null'
                                description: Set when a professional came off the matter and nothing holds it now.
                              check:
                                type:
                                - object
                                - 'null'
                                description: 'Records matters only. A person at Scope worked the CORE records run for the live work order and checked the records available against the firm''s request: result checked means that person completed the run''s check and every file it checked is still on the matter (not rejected, replaced or withdrawn). Nothing else is checked. Null on every other matter: serves, court runs and every other category carry no check step today (a serve''s record states facts only, such as the attempts logged and a declaration signed in Scope, and none of them is a check), and a records matter with no run carries none either.'
                                properties:
                                  rule:
                                    type:
                                    - string
                                    - 'null'
                                    enum:
                                    - records
                                    - null
                                  result:
                                    type: string
                                    enum:
                                    - checked
                                    - not_yet_checked
                                    - not_checked
                                    - unreadable
                                    description: 'checked: a person at Scope completed the run''s check and every file it checked is still on the matter. not_yet_checked: the run is open and the work order is not finished. not_checked: the work order finished with the run open, a file the run checked was rejected, replaced or withdrawn, or the run names no file for an item. unreadable: a read behind it failed.'
                                  found:
                                    type: array
                                    items:
                                      type: string
                                    description: Each fact Scope read that held.
                                  missing:
                                    type: array
                                    items:
                                      type: string
                                    description: 'Full sentences: what is not there, or what could not be read.'
                                  at:
                                    type:
                                    - string
                                    - 'null'
                                    format: date-time
                              exceptions:
                                type: array
                                description: 'Open exceptions: those that are still the latest word on the matter.'
                                items:
                                  type: object
                                  properties:
                                    key:
                                      type: string
                                    label:
                                      type: string
                                    note:
                                      type:
                                      - string
                                      - 'null'
                                    at:
                                      type:
                                      - string
                                      - 'null'
                                      format: date-time
                                    owner:
                                      type: string
                                      enum:
                                      - scope
                                      - firm
                                      - professional
                                      description: Who acts next. scope only where Scope wrote the event or was alerted by it; never a promise that anyone is working on it.
                                    decision:
                                      type:
                                      - object
                                      - 'null'
                                      description: The decision needed from the firm, when one is.
                                      properties:
                                        text:
                                          type: string
                                        href:
                                          type:
                                          - string
                                          - 'null'
                                          description: A path on scope.bid, only where a page exists to make the decision.
                                        link_label:
                                          type:
                                          - string
                                          - 'null'
                                    contact:
                                      type: string
                                      description: How to reach Scope.
                              incomplete:
                                type: boolean
                                description: A read behind the record failed, so steps may be missing.
                      render_hints:
                        type: object
                      deep_link:
                        type: string
        '404':
          description: Dispatch not found.
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Dispatches
      operationId: getApiV1DispatchesByDispatchId
      x-operation-id-source: derived
    servers:
    - url: https://scope.bid
      description: Production
  /api/v1/dispatches/{dispatch_id}/award:
    post:
      summary: Award a dispatch to a vendor
      description: '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.'
      parameters:
      - name: dispatch_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - vendor_name
              properties:
                vendor_name:
                  type: string
      responses:
        '200':
          description: '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.'
        '400':
          description: vendor_name is required.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Dispatch not found.
        '409':
          description: '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':
          description: 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':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: '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.'
      tags:
      - Dispatches
      operationId: postApiV1DispatchesByDispatchIdAward
      x-operation-id-source: derived
    servers:
    - url: https://scope.bid
      description: Production
components:
  responses:
    Forbidden:
      description: '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.'
    Unauthorized:
      description: Missing or invalid access token.
    RateLimited:
      description: Per-tenant rate limit exceeded.
      headers:
        Retry-After:
          description: Seconds until the window resets.
          schema:
            type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'OAuth 2.0 access token, or a personal access token (PAT) for CI and power users. Pass as Authorization: Bearer <token>. Every token resolves to exactly one tenant.'
x-refined-from:
- scope-bid-openapi.json
- scope-bid-openapi.json