Ordering Documents

The ordering documents API lets you attach supporting files to number orders and requests. These documents are called attachments in the API.

• A request attachment belongs to one request. It can be added while the request is still in a cart and remains available after checkout.
• An order attachment belongs to the order and is made available to every request in that order.

For ADD_MESSAGING_NUMBERS, Swift forwards all attachments belonging to the request, together with attachments inherited from its order, to Tychron before the upstream cart is checked out.

The API stores the file when the attachment is created. List, show, and update operations return attachment metadata; there is currently no public endpoint for downloading the stored file.

Access requirements

Ordering Attachment Access must be enabled for the account that owns the cart, order, or request. Access is evaluated independently for each account, including subaccounts.

When using an API key, use the apik_ prefix and assign an impersonated user with the necessary permissions to the key.

For request attachments, the user needs the attachment permission for the operation and permission to view the parent in its current state:

Request state	Parent permission	Attachment permissions
Before checkout	ordering_cart_requests:show	ordering_request_attachments:index, show, create, update, or delete
After checkout	ordering_requests:show	ordering_request_attachments:index, show, create, update, or delete

Order attachments similarly require the applicable cart/order permission and an ordering_order_attachments permission.

If ordering attachments are disabled, the API returns 403 Forbidden with the error code access_denied.ordering_attachment_access.

Endpoints

Request attachment endpoints:

Method	Endpoint	Description
POST	/api/v1/requests/{request_id}/attachments	Upload a document to a request.
GET	/api/v1/requests/{request_id}/attachments	List a request’s documents.
GET	/api/v1/requests/{request_id}/attachments/{attachment_id}	Get document metadata.
PATCH	/api/v1/requests/{request_id}/attachments/{attachment_id}	Update document metadata.
DELETE	/api/v1/requests/{request_id}/attachments/{attachment_id}	Delete the metadata and stored file.

Order attachments use the same operations under /api/v1/orders/{order_id}/attachments.

Attachment schema

Name	Type	Description
id	ULID	Unique attachment identifier.
name	String	Display name. Required when uploading.
notes	String or null	Optional notes about the attachment.
file_hint	String	DEFAULT for a general document or LOA for a letter of authorization. Defaults to DEFAULT.
reference_id	UUID or null	Optional caller-supplied identifier. It must be unique within the order or request.
filename	String	Filename used when the file is referenced. Defaults to the uploaded file’s name and can be overridden.
inserted_at	String (datetime)	Creation timestamp in ISO 8601 format.
updated_at	String (datetime)	Last update timestamp in ISO 8601 format.

The response type is request_attachment for request documents and order_attachment for order documents.

Upload a request document

Uploads use multipart/form-data, not JSON. Send the file as data[file] and the display name as data[name]. Other data[...] fields are optional.

curl --request POST \
  'https://api.swift-api.com/api/v1/requests/01KBC5AHZPC0TNB2N9B0000000/attachments' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer apik_ABC123' \
  --form 'type=request_attachment' \
  --form 'data[name]=Letter of authorization' \
  --form 'data[notes]=Authorization for the numbers in this request' \
  --form 'data[file_hint]=LOA' \
  --form 'data[reference_id]=c4e782c4-07b8-4f33-916c-cd7b83985780' \
  --form 'data[file]=@./letter-of-authorization.pdf'

A successful upload returns 201 Created:

{
  "associations": {
    "request": {
      "data": {
        "id": "01KBC5AHZPC0TNB2N9B0000000"
      },
      "type": "request"
    }
  },
  "data": {
    "file_hint": "LOA",
    "filename": "letter-of-authorization.pdf",
    "id": "01KBC6NKAPZKFRN3FA00000000",
    "inserted_at": "2026-10-19T14:22:31.410000Z",
    "name": "Letter of authorization",
    "notes": "Authorization for the numbers in this request",
    "reference_id": "c4e782c4-07b8-4f33-916c-cd7b83985780",
    "updated_at": "2026-10-19T14:22:31.410000Z"
  },
  "type": "request_attachment"
}

The request_id returned when a cart request is created remains the same after checkout, so the same attachment URLs work before and after checkout.

List documents

List endpoints support the standard cursor pagination parameters, including first, after, last, and before.

GET /api/v1/requests/{request_id}/attachments?first=20 HTTP/1.1
Accept: application/json
Authorization: Bearer apik_ABC123

The response contains attachment documents in data.items and pagination details in data.page_info.

Get document metadata

GET /api/v1/requests/{request_id}/attachments/{attachment_id} HTTP/1.1
Accept: application/json
Authorization: Bearer apik_ABC123

Update document metadata

Updating an attachment changes its metadata without replacing the stored file. Omitted properties retain their current values.

PATCH /api/v1/requests/{request_id}/attachments/{attachment_id} HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer apik_ABC123

{
  "type": "request_attachment",
  "data": {
    "name": "Updated letter of authorization",
    "notes": "Signed by the account owner",
    "file_hint": "LOA"
  }
}

The response is 200 OK with the updated attachment document.

Delete a document

Deleting an attachment permanently removes both its metadata and stored file.

DELETE /api/v1/requests/{request_id}/attachments/{attachment_id} HTTP/1.1
Accept: application/json
Authorization: Bearer apik_ABC123

The response is 200 OK and contains the deleted attachment document.

Errors

Status	Meaning
401 Unauthorized	The access token is missing or invalid.
403 Forbidden	Ordering attachments are disabled for the owning account, or the user lacks a required permission.
404 Not Found	The parent or attachment does not exist, or the attachment does not belong to the parent in the URL.
422 Unprocessable Content	The request is invalid, such as a missing file or name, an invalid file_hint, or a duplicate reference_id.
503 Service Unavailable	Attachment storage is temporarily unavailable during an upload or delete operation.