Request a document upload link

POST/partner/v1/business-profiles/{customerId}/documents/upload-link

Auth Bearer tokenScope partner.write

Returns a presigned URL and a documentId. Upload the file to that URL with one PUT, as described in Uploading the file. The file never passes through the API. The link is valid for 30 minutes.

Then confirm the document by sending its documentId in businessDocumentIdList on Update business profile. For an identity document, you can instead send it as idFrontDocumentUploadId.

Path

customerIduuidpathrequired

From Create business profile.

Body

documentTypestringrequired

BusinessDocument or UboIdentity. See document types.

documentCategorystringrequired

Up to 100 characters. For UboIdentity, the matching identity type code, such as PASSPORT. For BusinessDocument, the kind of document, such as ProofOfAddress.

contentTypestringrequired

application/pdf, image/jpeg or image/png. It is signed into the link, so your upload must send exactly this Content-Type.

uboIduuid

Required for UboIdentity: the person's uboId from the create response. Omit for BusinessDocument.

ownershipDetailIduuiddeprecated

The previous name for uboId, still accepted. Sending both with different values is a 400.

No file name is sent. The stored file is named from documentCategory and contentType, for example PASSPORT.jpg. A fileName sent by an older integration is ignored.

Response

documentIduuid

Use it to confirm the document.

uploadUrlstring

Presigned URL to PUT the file to.

fileKeystring

The storage key.

expiresAtdate-time

When uploadUrl stops working.

Uploading the file

Send the file bytes as the raw body of a PUT to uploadUrl, with the Content-Type header set to exactly the contentType you requested. Send no other authentication: the link carries it.

• A 200 from storage means the file landed. The document moves from NewDocument to Uploaded once it passes malware scanning, usually within seconds.
• A file that fails the scan is deleted and the document becomes Quarantined. Request a new link and upload a clean file.
• The file must really be the type you declared: a PDF for application/pdf, a JPEG for image/jpeg, a PNG for image/png.

warning

Finish each upload before you request another link with the same documentCategory for this business. Requesting a link removes any document with that category that has not been uploaded yet, even one for a different person. Two people's PASSPORT links requested back to back would lose the first.

Errors from the PUT come from storage, as XML, not from the API:

Storage error	HTTP	When	What to do
SignatureDoesNotMatch	403	The Content-Type header is missing or differs from contentType, or the URL was changed.	Send the exact contentType; use uploadUrl as returned.
AccessDenied (Request has expired)	403	The link is older than 30 minutes.	Request a new link.

Errors

Besides the common errors, the link request returns:

Code	HTTP	When
ValidationControl.Error	400	A field is invalid, uboId is missing for UboIdentity, or uboId and ownershipDetailId name different people.
OwnershipDetail.NotAuthorized	403	The person belongs to another customer.
OwnershipDetail.NotFound	404	No person on this customer has that id.
Customer.AlreadySubmitted	409	An analyst is reviewing or has decided.
DocumentUpload.PresignedUrlFailed	500	Storage could not issue a link. Retry later.

1. Request the link

curl -X POST \
  https://gateway.sandbox.rynopay.io/api/partner/v1/business-profiles/b3f1c2d4-.../documents/upload-link \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "documentType": "BusinessDocument",
    "documentCategory": "ProofOfAddress",
    "contentType": "application/pdf"
  }'

For a person's identity document

{
  "documentType": "UboIdentity",
  "documentCategory": "PASSPORT",
  "contentType": "image/jpeg",
  "uboId": "7c2a9e10-..."
}

Response

{
  "isSuccess": true,
  "error": { "code": "", "description": "", "type": 0 },
  "value": {
    "documentId": "d4e5f6a7-...",
    "uploadUrl": "https://...s3.amazonaws.com/onboarding-documents/...",
    "fileKey": "onboarding-documents/d4e5..._ProofOfAddress.pdf",
    "expiresAt": "2026-09-14T11:00:00Z"
  }
}

2. Upload the file

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @proof-of-address.pdf