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; for example, Accept Payments needs the signed merchant 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.

Surface	Endpoint	Use it for
Document library	`/v1/documents`	Reusable documents not tied to a business, such as the merchant agreement. Attach one to a business by its `id`.
Business documents	`/v1/businesses/{businessId}/documents`	Files specific to one business, such as a business license. Registered under the business and bound in one step.

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"
  },
  "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. 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" \
  --data-binary @merchant-agreement.pdf

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

Field	Required	Description
`fileName`	Yes	The file's name, including extension. Up to 255 characters.
`mimeType`	Yes	The file format, for example `application/pdf`, `image/png`, or `image/jpeg`.
`documentType`	Yes	What the file is: `merchant_agreement`, `business_license`, `articles_of_incorporation`, `proof_of_address`, `pci_attestation`, `surcharge_disclosure`, `passport`, or `driver_license`.
`fileSizeBytes`	No	Size of the file in bytes. Maximum 104857600 (100 MB).
`externalId`	Recommended	Your own reference, up to 255 characters. Find the record later with `?externalId=`.

Document types

`documentType`	What it is
`merchant_agreement`	The merchant agreement your merchant signed.
`business_license`	A license to operate the business.
`articles_of_incorporation`	The document that legally formed the business.
`proof_of_address`	A document that shows the business address.
`pci_attestation`	A statement that the business meets the card industry's data security standard (PCI DSS).
`surcharge_disclosure`	The notice a business shows customers when it adds a card surcharge.
`passport`	A passport, used as an identity document.
`driver_license`	A driver license, used as an identity document.

Attach a library document (on a business)

Field	Required	Description
`documents[].id`	Yes	The `id` of a document in your library, such as the merchant agreement. Find it with List library documents.

The merchant agreement is needed to activate card processing (payin.card).

Register response

Field	Description
`id`	The generated document identifier.
`externalId`	Your own reference, if you set one.
`uploadUrl`	One-time, pre-signed URL to upload the file to with a `PUT`.
`method`, `headers`	The exact method (`PUT`) and headers to use on the upload.
`expiresAt`	When the upload URL expires.

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

Create a business

Reference an uploaded document in the create call.

Status lifecycle

See where required documents fit in boarding.