Documents
Upload Account Document
Attach an entity (business) document to the account as a base64 data URI
POST
Documents carry the entity (business) file evidence behind KYB — e.g. certificate of incorporation, proof of address, board resolution. They attach to an account. Files are submitted as base64 data URIs. The complete JSON request body is limited to 21 MiB, including base64 expansion and JSON/data-URI overhead; an oversized request returns
413. In practice, the largest raw file is approximately 15.75 MiB and may be slightly smaller depending on metadata.
Uploading a document accepts the file with status staged and recomputes the account’s onboarding requirements. Once all requirements are complete, Hop automatically submits the account — including its staged documents — for verification review, moving the account to under_review and each document to submitted. Uploads are blocked once the account’s kyc_status is terminal (approved / rejected).
While a submission is running or awaiting review, the document set is frozen: uploading during an active submission returns 422 (“KYB submission is in progress; retry the upload once it completes”), and once the account is submitted, uploads return 422 (“Account KYB has been submitted; documents can be added after a review reopens the application”) until a review outcome — such as a request for information — reopens the application.
For a requirement that accepts a single document (min_count 1), uploading again for the same requirement_key marks the previously staged file replaced — it stops counting toward the requirement and is not submitted. Requirements that accept multiple documents accumulate uploads instead.
If the verification provider cannot process a file during submission, that document becomes rejected (see rejection_reason) while the others proceed to submitted; the application automatically returns to not_ready and the affected requirement appears under requirements.issues with a rejected_documents list. Upload a corrected file with the same requirement_key — re-submission happens automatically, and already-submitted documents keep their status.
These endpoints cover entity documents only; an associated person’s identity documents are captured inside their Verification Session, not uploaded here.
This endpoint attaches an entity (business) document to the account and recomputes onboarding requirements. It applies to business accounts only: on an individual account every upload returns
422, because the account holder’s identity documents are captured inside their hosted verification session. Fails with 422 when kyc_status is terminal or while a submission is in flight or under review (see above).
Path Parameters
string
required
Id of the Platform customer (e.g.
cus_…).string
required
Id of the account (e.g.
acct_…).Request Body
string
required
Requirement key returned by GET Account (
requirements.missing[].key / requirements.issues[].key) that this document satisfies. Every upload must claim a key the account can satisfy — an unknown key, or a type the claimed requirement does not accept, is rejected with 422 listing the allowed values.enum
required
Account document type — see the enum table above.
string
required
Document file as a base64 data URI (e.g.
data:application/pdf;base64,...). The complete request body is limited to 21 MiB, including base64 and JSON overhead; the practical raw-file maximum is approximately 15.75 MiB.string | null
Original file name, for your own reference. Max 255 characters.
Response
Returns200 with the new resource’s id. Use Get Document to retrieve the full object.
string
Id of the newly created document (e.g.
doc_…).