Skip to main content

Download Order Documents

Documents attached to an order — whether uploaded by the customer, a partner, or Swyft staff — can be retrieved and downloaded through the API. See Upload Order Documents for how documents get onto an order in the first place.

Retrieving uploaded documents​

The Get order response includes a documents array of the order's partner-visible documents:

"documents": [
    {
        "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "driver-license.pdf",
        "type": "general",
        "field_key": null,
        "description": null,
        "uploaded_by": "customer",
        "uploaded_at": "2026-07-01",
        "timestamp": "2026-07-01T14:32:00-05:00",
        "download_url": "https://swyftfilings-docs.s3.amazonaws.com/documents/driver-license.pdf?X-Amz-Signature=..."
    },
    {
        "uuid": "b6a1c9de-8f2a-4b3d-9c1e-7a5f0d2e4b91",
        "name": "ra-agreement.pdf",
        "type": "reg_agent",
        "field_key": null,
        "description": "Signed registered agent agreement",
        "uploaded_by": "agent",
        "uploaded_at": "2026-07-02",
        "timestamp": "2026-07-02T09:15:00-05:00",
        "download_url": "https://swyftfilings-docs.s3.amazonaws.com/documents/ra-agreement.pdf?X-Amz-Signature=..."
    }
]
  • A document is included when it's visible to everyone (type: "general") or restricted to the registered agent (type: "reg_agent") — internal-only documents are excluded.
  • uuid is the document's internal identifier, usable with the id filter on List or retrieve order documents below. null for documents that existed before this field was introduced — only newly created documents are assigned one.
  • field_key is the key of the service's document-type input field this document answers (e.g. state_specific.county_liquor_license_document), when it's related to one. Null for a plain attachment not tied to any input field.
  • description echoes back the free-text description sent at upload time, if any.
  • timestamp is the full upload timestamp in ISO 8601 format — uploaded_at remains the date-only field for backward compatibility.
  • download_url is a short-lived signed link that expires 15 minutes after the response is generated. Download the file promptly, or request the order again to obtain a fresh link.
  • The array is empty ("documents": []) when no visible documents exist on the order.

List or retrieve order documents​

To fetch an order's documents without pulling the full Get order payload, use:

GET {baseUrl}/orders/{order_uuid}/documents
Authorization: Bearer {token}

This returns the same document objects described above. Two optional, mutually exclusive query parameters narrow the result — sending both returns a 422:

ParamTypeNotes
idstring (query, optional)A document's uuid (see above). Returns a list containing just that document, or an empty list if no document with that uuid exists on this order (including one that predates the uuid field).
typestring (query, optional)general or reg_agent. Returns only documents of that visibility type.

Omit both to return every partner-visible document on the order. For a bundle order, documents from the parent and all child orders are merged into one list, same as on Get order.

# All documents
curl "{baseUrl}/orders/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents" \
  -H "Authorization: Bearer {token}"

# A single document by uuid
curl "{baseUrl}/orders/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents?id=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}"

# Only registered-agent-restricted documents
curl "{baseUrl}/orders/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents?type=reg_agent" \
  -H "Authorization: Bearer {token}"

Success​

{
  "data": [
    {
      "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "driver-license.pdf",
      "type": "general",
      "field_key": null,
      "description": null,
      "uploaded_by": "customer",
      "uploaded_at": "2026-07-01",
      "timestamp": "2026-07-01T14:32:00-05:00",
      "download_url": "https://swyftfilings-docs.s3.amazonaws.com/documents/driver-license.pdf?X-Amz-Signature=..."
    }
  ],
  "success": true
}

Errors and edge cases​

  • 401 / 403: The order is not associated with your partner account.
  • 422 Validation: id and type were both sent on GET .../documents — send at most one.