Shipper REST endpoints

Document quote and booking requests, webhook subscriptions and load status responses.

REST endpoint cards for POST /v2/loads/{loadId}/tender and GET /v2/loads/{loadId}, showing bearer authentication, path parameters, tender request body, tracking and stops query options, and success and error responses.

Reference diagram from Archdocs. See the YAML below for this template's contents.

A booking request needs more than a method and path. This fictional shipper API example includes authentication, an idempotency header and error responses for an expired or already booked quote.

Adapt the endpoints

Replace the paths and request schema names with your API's contract. Add headers, path parameters and query parameters to the endpoint that accepts them. Each response has a status and a description.

Names such as BookingRequest are labels here. This template does not define their JSON schemas or validate requests against an API server. Keep those definitions in your API contract and use the diagram to explain the endpoints during a design review.

Template YAML

Open in the editor Start free

apiVersion: archdocs/v1
title: Public Shipper API v2
nodes:
  - id: createQuote
    type: api-endpoint
    protocol: rest
    method: POST
    path: /v2/quotes
    description: Price a lane. Quotes hold 15 minutes.
    auth: Bearer (shipper API key)
    at:
      x: 0
      y: 0
    headers:
      - name: Idempotency-Key
        type: string
        required: true
    body:
      contentType: application/json
      schema: QuoteRequest
    responses:
      - status: "201"
        description: Quote
      - status: "422"
        description: Lane not serviceable
  - id: createWebhook
    type: api-endpoint
    protocol: rest
    method: POST
    path: /v2/webhooks
    description: Subscribe to load status and invoice events.
    auth: Bearer (shipper API key)
    at:
      x: 380
      y: 0
    body:
      contentType: application/json
      schema: WebhookSubscription
    responses:
      - status: "201"
        description: Subscription with signing secret
      - status: "400"
        description: URL must be HTTPS
  - id: createBooking
    type: api-endpoint
    protocol: rest
    method: POST
    path: /v2/bookings
    description: Accept a quote and book the load.
    auth: Bearer (shipper API key)
    at:
      x: 760
      y: 0
    headers:
      - name: Idempotency-Key
        type: string
        required: true
    body:
      contentType: application/json
      schema: BookingRequest
    responses:
      - status: "201"
        description: Booking
      - status: "409"
        description: Quote already booked
      - status: "410"
        description: Quote expired
  - id: getLoad
    type: api-endpoint
    protocol: rest
    method: GET
    path: /v2/loads/{loadId}
    description: Status, carrier, stops and live ETA.
    auth: Bearer (shipper API key)
    at:
      x: 1120
      y: 420
    pathParams:
      - name: loadId
        type: uuid
        required: true
    queryParams:
      - name: include
        type: tracking | stops
    responses:
      - status: "200"
        description: Load
      - status: "404"
        description: Not found