Before Priority approves a business, it reviews some of the business's paperwork. The main document is the signed merchant agreement. Each service lists the documents it still needs in missingDocuments. Accept Payments needs the signed merchant agreement; a business-owned deposit account needs the account agreement.

A document is a file used in boarding. Registering one is always two steps: register the metadata to get a one-time, pre-signed uploadUrl, then upload the file to that URL. There are two surfaces, used for different things. For the full field list, jump to the Request reference.

Common use cases

• Attach the signed merchant agreement to a business. See Scenario 1.
• Register a business-specific file, such as a business license. See Scenario 2.
• Include the merchant agreement in a single-call business create. See Scenario 3.

Scenarios

Registering a document is always the same shape: register the metadata for a one-time uploadUrl, then upload the file to it. What differs is which surface you register on and how the document reaches the business.

Before you begin (all scenarios)

• You have a sandbox API key. See Getting started.
• You have the signed file ready, and know its documentType (for example merchant_agreement).
• You have the businessId, or you are creating the business in the same flow.

Scenario 1: Attach a library document to a business

The merchant agreement is the contract your merchant signs with Priority. It is signed by hand, and you upload a scan or PDF of the signed copy. It lives in your document library, not on one business. Find an existing one with GET /v1/documents, or register a new one with 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 '{
    "documentType": "merchant_agreement",
    "fileName": "merchant-agreement.pdf",
    "mimeType": "application/pdf",
    "externalId": "merchant-agreement-v4"
  }'

Response: 201 Created with the upload link.

{
  "id": "doc_9f2a1c",
  "externalId": "merchant-agreement-v4",
  "uploadUrl": "<opaque-upload-url>",
  "method": "PUT",
  "headers": {
    "Content-Type": "application/pdf",
    "If-None-Match": "*"
  },
  "expiresAt": "2026-06-15T12:10:00Z"
}

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

curl -X PATCH https://sandbox-api.prioritycommerce.com/v1/businesses/bus_8f3a2c \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "id": "doc_9f2a1c"
      }
    ]
  }'

Scenario 2: Register a business-specific document

For a file that belongs to one business, such as a business license, register it under the business. It is bound to the business in one step, with no separate attach. Make a POST request to /v1/businesses/{businessId}/documents.

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

The response returns the same upload link shape as Scenario 1. Upload the file to finish.

Scenario 3: Include a document in a single-call create

A library document must exist before you can reference it. Register and upload it first, then pass its id in the business create payload.

{
  "legalName": "Example Online Goods LLC",
  "businessType": "llc",
  "documents": [
    {
      "id": "doc_9f2a1c"
    }
  ]
}

The business is created with the document already attached. See Create a business.

Upload the file

Send the file with a PUT to the returned uploadUrl, using the method and headers from the register response, including If-None-Match: *. This call takes no x-api-key: the URL is pre-signed and time-limited, so don't modify it and upload before expiresAt.

curl -X PUT "<opaque-upload-url>" \
  -H "Content-Type: application/pdf" \
  -H "If-None-Match: *" \
  --data-binary @merchant-agreement.pdf

Each document takes one upload. A second upload to the same link fails with 412 and does not replace the file. If the first upload did not store the file, you can retry the same link until expiresAt.

Until the file is received, the document stays PENDING_UPLOAD. An upload does not by itself advance the business's underwriting.

Read a document back

• Read the document: make a GET request to /v1/businesses/{businessId}/documents/{documentId} (library equivalent: GET /v1/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/bus_8f3a2c/documents/doc_9f2a1c \
  -H "x-api-key: <your-key>"

The GET response includes the document's current status.

Request reference

Register fields

Document types

Attach a library document (on a business)

The merchant agreement is needed to activate card processing (payin.card). The account agreement (account_agreement) is needed to activate a business-owned deposit account (treasury.owned).

Register response

Documents attach at the business level only. Attaching to a specific location, bank account, or service, and reusing one master agreement across services, are not supported.

Statuses

A registered document starts in PENDING_UPLOAD. After a successful upload it becomes ACCEPTED. If the file fails the security scan, for example a virus or a corrupted file, it becomes REJECTED and the reason is in statusReason. A missing or rejected agreement shows on the service's missingDocuments. See Status lifecycle and Underwriting exceptions.

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