Skip to main content

Request a document upload link

POST/partner/v1/business-profiles/{customerId}/documents/upload-link
Auth Bearer tokenScope partner.write

Returns an uploadUrl to upload one file to, and a documentId for that file.

Steps

  1. Call this route.
  2. PUT the file to uploadUrl within 30 minutes. See Uploading the file.
  3. Use the documentId:
warning

For BusinessDocument, requesting a link deletes this business's files in the same documentCategory that are still NewDocument: not uploaded yet, or uploaded but not yet through the malware scan. A 200 from the PUT is not enough. Upload one file per documentCategory at a time. (A pending upload that replaces a different rejected document is kept.)

Path​

customerIduuidpathrequired

From Create business profile. For beneficiary and payout, it can also be your own partner id.

Body​

purposestringrequired

BusinessDocument, beneficiary or payout. Not case-sensitive. See upload purposes.

documentCategorystringrequired
  • BusinessDocument: the documentTypeCategory from Get document requirements, for example CERTIFICATE_OF_INCORPORATION. To send an extra document that isn't on that list, use any customer-uploadable code from List document types. Up to 100 characters.
  • beneficiary or payout: Invoice or Contract.
contentTypestringrequired

The file's MIME type, in lower case. One of application/pdf, image/jpeg, image/png, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, and allowed by the document's allowedFormats. Your PUT must send exactly this Content-Type.

replacesDocumentIduuid

BusinessDocument only, optional. When answering a change request: the rejected document this file replaces, from rejectedDocuments in Get verification status. Leave it out and ryno picks the oldest rejected document in this documentCategory that no pending upload already replaces, or the oldest one if all have one. To replace several, request one link per file.

No file name or size is sent. Identity documents for a business's people are not uploaded through the API.

Response​

documentIduuid

Keep it. You send it in step 3.

uploadUrlstring

Presigned URL to PUT the file to.

expiresAtdate-time

When uploadUrl stops working (30 minutes).

fileKeystring

Storage key, for reference. You don't send it anywhere.

Beneficiary and payout documents​

The same route, with these differences:

BusinessDocumentbeneficiary / payout
customerIdA business you onboardedYour own partner id, or a business you onboarded
documentCategoryFrom Get document requirementsInvoice or Contract
contentTypeThe document's allowedFormatsPDF, PNG or JPEG
Max file sizeThe document's maxFileSizeMB, at most 10 MB (10,485,760 bytes)8 MB (8,388,608 bytes)
Once an analyst has the case or has decidedRefused (Customer.AlreadySubmitted)Allowed
replacesDocumentIdAllowedRefused
Removes pending uploads in the categoryYesNo

The document can only be attached to a beneficiary or payout of the customerId it was requested for, and only once its malware scan is clean.

Uploading the file​

PUT the raw file bytes to uploadUrl, with the Content-Type header set to exactly the contentType you requested. Send no Authorization header: the link carries it.

  • Size is checked after upload. Storage accepts a file over the limit, then deletes it, and the document becomes Quarantined. Check the size before you upload.
  • Every file is malware-scanned. Clean files move to Uploaded. Infected files are deleted and the document becomes Quarantined.
  • To retry after Quarantined, request a new link.

Storage returns its own errors, as XML:

Storage errorHTTPCauseFix
SignatureDoesNotMatch403Content-Type missing or different from contentType, or the URL was changed.Send the exact contentType; use uploadUrl unchanged.
AccessDenied (Request has expired)403The link is older than 30 minutes.Request a new link.

Errors​

CodeHTTPWhen
ValidationControl.Error400A body field is missing or invalid for the purpose.
Document.UnknownPurpose400purpose is missing or unknown.
Document.ContentTypeNotAllowed400The document doesn't accept this contentType.
ComplianceDocumentType.Unknown400documentCategory is neither on the business's requirements nor an active code in List document types.
ComplianceDocumentType.NotUploadable400Only compliance staff can attach this document.
Document.NotAnOpenRejection400replacesDocumentId isn't a rejected document in this category waiting for a replacement.
Document.ReplacementOnlyForBusinessDocuments400replacesDocumentId sent with beneficiary or payout.
Customer.NotFound404BusinessDocument: no customer with this id.
Customer.NotBusiness400BusinessDocument: the customer isn't a business.
Partner.NotAuthorized403You can't upload for this customerId.
Customer.AlreadySubmitted409BusinessDocument once an analyst has the case or has decided. Changes requested by compliance can still be answered.
OnboardingConfig.HighRiskCountryRequiresSetup409This country needs its own setup first. Contact support.
DocumentUpload.PresignedUrlFailed500Storage couldn't issue a link. Retry later. Returned as an RFC 7807 problem response.

See also common errors.