A document is a file bound to a business, most often the signed merchant agreement. Onboarding supports wet-sign agreements: you register the file, upload the bytes to a one-time URL, and PCE virus-scans it before it is usable. Uploading always follows the same two steps, and there are two API surfaces you can register through depending on whether the business already exists. For the full field list, jump to the Request reference.

Common use cases

• Attach a signed merchant agreement to a business you are building progressively.
• Create a document up front so you can reference its id in a single-call business create.
• Register a file, upload it to the one-time URL, then read it back or fetch a temporary download link.

🚧

PENDING-PUBLISH

The boarding API Reference is pending publication; the ref: targets on this page are placeholders. Replace each with the real boarding-spec operationId once the boarding reference ships.

Scenarios

Registering a document is always the same shape: register the metadata to get a one-time, pre-signed uploadUrl, then PUT the bytes to that URL. What differs is where you register and how the document reaches the business. Pick the scenario that matches how you are building the business.

sequenceDiagram
    participant App as Your application
    participant PCE as PCE
    participant Store as Upload URL (pre-signed)

    App->>PCE: Register the document (metadata)
    PCE-->>App: 201 Created (doc_ id, uploadUrl, status pending_upload)
    App->>Store: PUT the file bytes (no x-api-key)
    Store-->>App: 200 OK
    PCE->>PCE: Virus-scan the upload
    Note over PCE: The document becomes usable once the scan clears
    App->>PCE: Reference the doc_ id on the business

Before you begin (all scenarios)

• You have the signed agreement file ready (a wet-sign PDF).
• You know the documentType you are binding (for example merchant_agreement).
• You have the businessId, or you are creating the business in the same flow.

Scenario 1: Add a document to a business you are building progressively

A business was created with minimal details (see Create a business) and now needs its signed agreement. You have two ways to do it.

Path A: register under the business (one surface, auto-bound)

Register the document on the business to get an upload URL, then upload the bytes. Because you registered under the business, the document is already bound to it; there is no separate attach step. Make a POST request to /v1/businesses/{businessId}/documents.

curl -X POST https://sandbox-api.prioritycommerce.com/v1/businesses/{businessId}/documents \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "merchant-agreement.pdf",
    "mimeType": "application/pdf",
    "documentType": "merchant_agreement"
  }'

Response: 201 Created

{
  "id": "doc_9f2a1c",
  "uploadUrl": "https://uploads.prioritycommerce.com/documents/doc_9f2a1c?token=eyJhbGciOiJ",
  "method": "PUT",
  "headers": { "Content-Type": "application/pdf" },
  "expiresAt": "2026-06-15T12:10:00Z"
}

Then upload the bytes to that URL (see Upload the file).

Path B: register globally, then attach

Register the document on the global documents surface, upload the bytes, then attach the returned doc_… id to the business. Use this when your workflow creates documents independently of a specific business. Make a POST request to /v1/documents.

curl -X POST https://sandbox-api.prioritycommerce.com/v1/documents \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "merchant-agreement.pdf",
    "mimeType": "application/pdf",
    "documentType": "merchant_agreement"
  }'

Upload the bytes, then attach the id to the business with a PATCH to /v1/businesses/{businessId}.

curl -X PATCH https://sandbox-api.prioritycommerce.com/v1/businesses/{businessId} \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      { "id": "doc_9f2a1c", "acceptedAt": "2026-06-15T12:00:00Z" }
    ]
  }'

🚧

PENDING-PUBLISH

Confirm against the boarding contract: whether PATCH /v1/businesses/{businessId} accepts a documents[] reference, and whether the global (/v1/documents) and business-scoped (/v1/businesses/{businessId}/documents) register endpoints are interchangeable or serve distinct purposes. This page presents both; reconcile the exact behavior before publish.

Scenario 2: Include a document in a single-call business create

You are sending a Complete submission (Business with complete details) and the payload needs a document reference. A document must exist before you can reference its id, so create it first, then include it in the create body.

1. Register the document globally with POST /v1/documents and upload the bytes (the same two steps as above).
2. Reference the returned doc_… id in the business create payload:

{
  "legalName": "PCETest Acme Services LLC",
  "businessType": "llc",
  "documents": [
    { "id": "doc_9f2a1c", "acceptedAt": "2026-06-15T12:00:00Z" }
  ]
}

The business is created with the document already bound. If you don't have the document yet at create time, board the business first and add it progressively (Scenario 1).

Register a document

Registering returns a one-time, pre-signed uploadUrl and a generated doc_… id; the document starts in pending_upload. There are two surfaces:

Both take the same body:

{
  "fileName": "merchant-agreement.pdf",
  "mimeType": "application/pdf",
  "documentType": "merchant_agreement"
}

Upload the file

Send the raw file bytes with a PUT to the returned uploadUrl, using the method and headers from the register response. This call takes no x-api-key: the URL is pre-signed and time-limited, so don't modify it.

curl -X PUT "https://uploads.prioritycommerce.com/documents/doc_9f2a1c?token=eyJhbGciOiJ" \
  -H "Content-Type: application/pdf" \
  --data-binary @merchant-agreement.pdf

PCE virus-scans the upload; once it clears, the document is usable. An upload does not by itself advance the business's underwriting status.

Read a document back

• Read the document: make a GET request to /v1/businesses/{businessId}/documents/{documentId}.
• Fetch a temporary download link: make a GET request to /v1/businesses/{businessId}/documents/{documentId}/content.

curl https://sandbox-api.prioritycommerce.com/v1/businesses/{businessId}/documents/{documentId} \
  -H "x-api-key: <your-key>"

Request reference

Register fields

Attach fields (on a business)

Register response

🚧

PENDING-PUBLISH

A document attaches at the business level today; attaching to a specific location, bank account, or service (and reusing one master agreement across services) is still being finalized. Confirm the document model, the exact register/upload/attach field set, and the status a document reports after the virus scan against the boarding spec before publish.

Statuses

A registered document starts in pending_upload. After you PUT the bytes and the virus scan clears, it becomes usable. See Status lifecycle for how required documents fit the boarding flow, and Underwriting exceptions for a missingDocuments entry that blocks a service.

Best practices

Next steps

See also

• Businesses: how documents fit the entity model
• Create a business: include a document in the composite create
• Underwriting exceptions: resolve a missing document