Document Inbox (SFTP and API)
The Document Inbox lets you send us the documents of your accounts (KYC/KYB) by SFTP or by API, and follow each file. A file under a document type can then be cited in the KYB instead of uploading it again.
How it works:
- Avenia enables the Document Inbox for your account.
- You send each file into a folder named after a document type or a tag. By API, you can also send a description without a file, such as the URL of your store. By SFTP, a
.txtunder a tag carries a description: its own, or that of the file with the same name. - We scan the file for malware and check it. You get a
DOCUMENT-RECEIVED,DOCUMENT-QUARANTINEDorDOCUMENT-UPLOAD-REJECTEDwebhook with the document ID. - You cite a
RECEIVEDfile of a document type in the KYB, by its ID or by its SFTP path. - When you submit the KYB, you get
DOCUMENT-SUBMITTEDfor each cited document, thenDOCUMENT-APPROVEDorDOCUMENT-REJECTEDonce it is reviewed.
The Document Inbox is enabled by Avenia, for your main account and all its sub-accounts: ask your Avenia contact. Until then, every endpoint on this page returns 403, no DOCUMENT webhook is sent, and the KYB does not accept Inbox citations:
{
"error": "Document Inbox is not enabled for this workspace"
}
Both channels feed the same folders, statuses, webhooks and read endpoints:
| SFTP | API | |
|---|---|---|
| Best for | Batches and automated uploads | One file at a time, from your backend |
| File formats | PDF, PNG, JPG, JPEG; under a tag, also GIF, WEBP, TIFF, BMP, TXT, CSV, XLS, XLSX, DOC, DOCX, ZIP | Same as SFTP |
| Maximum size | 1 GB per file | 10 MB (10485760 bytes) per file |
| Account | The first folder of the path | subAccountId query parameter |
| Folder | The second folder of the path | documentType or tag in the request |
| Description | A .txt under a tag, or afterwards with PATCH | On the request, or afterwards with PATCH |
| Description without a file | No | Under a tag |
Tag OTHER | Only with a description in a .txt; otherwise rejected (description-required) | Accepted only with a description |
| Cite in the KYB by | ID or sftp:/ path (document types only) | ID (document types only) |
File names may contain only ASCII letters, digits, ., _ and - (no spaces or accents), and must end with an extension.
Every endpoint on this page accepts an optional ?subAccountId= query parameter. Without it, the call applies to your main account. An ID that is not one of your sub-accounts returns 404 (NotFoundError: subAccountId not found).
Folders: document types and tags
Every document goes into exactly one folder, which says what the document is. The folder is either a document type or a tag, never both, and it never changes after the upload. Folder names are case-sensitive: write them exactly as listed.
Only files under a document type can be cited in the KYB. To use a document in the KYB, send it to the folder of its document type.
Document types
Folder (documentType) | Document |
|---|---|
ID | Identity card |
DRIVERS-LICENSE | Driver's license |
PASSPORT | Passport |
RESIDENCE-PERMIT | Residence permit |
SELFIE | Selfie |
SELFIE-FROM-LIVENESS | Selfie from a liveness session |
PROOF-OF-ADDRESS | Proof of address of a person |
PROOF-OF-FINANCIAL-CAPACITY | Proof of financial capacity |
PROOF-OF-REVENUE | Proof of revenue |
CERTIFICATE-OF-INCORPORATION | Certificate of incorporation |
ARTICLES-OF-INCORPORATION | Articles of incorporation |
COMPANY-TAX-IDENTIFICATION-DOCUMENT | Company tax identification document |
PROOF-OF-ADDRESS-COMPANY | Proof of address of a company |
OWNERSHIP-CHART | Ownership chart |
SHAREHOLDER-REGISTER | Shareholder register |
DIRECTORS-REGISTER | Directors register |
PROOF-OF-SIGNING-AUTHORITY | Proof of signing authority |
INVOICE | Invoice |
ADDITIONAL-ATTACHMENT | Additional attachment |
Tags
A tag groups the documents our compliance team asks you for beyond the document types, such as proof of how you sell. A tag never counts as a document type: a document under a tag has documentType "" and can't be cited in the KYB, neither by ID nor by sftp:/ path.
Tag names are stable: we may add tags, but we never rename or remove one.
| Tag | What goes in it |
|---|---|
COMPANY | Company documents: articles of association or constitutive act, business license, partners and directors, organization chart, powers of attorney, licenses. |
IDENTITY | Identity document of a UBO, a representative, a director or an individual merchant. |
ADDRESS | Proof of address, of the company or of a person. |
ACTIVITY-MARKETPLACE | Proof that you sell on a marketplace: your store page, a marketplace fee statement. |
ACTIVITY-OWN-CHANNEL | Proof that you sell through your own website or app: the website or app, its domain, a sales report. |
ACTIVITY-B2B | Proof that you sell to other companies (B2B): invoice, proforma invoice, contract, bill of lading or air waybill, export agreement. |
INVOICES | Brazilian invoices: NF-e and NFS-e, as PDF or as a ZIP of their XML files. |
FINANCIALS | Financial statements, bank statements, income tax returns. |
OTHER | Anything else. A description is required: send it by API in description, or by SFTP in a .txt sent before the file. A document sent by SFTP to OTHER without one is rejected with description-required. |
For an ACTIVITY-* tag, you can send the URL of your store or website as a description without a file by API, or as a .txt by SFTP.
Send files by SFTP
1. Get your credential
Send your Avenia contact:
- your SSH public key, in OpenSSH format: Ed25519, ECDSA, or RSA of at least 3072 bits. Never send the private key.
- optionally, the IPv4 addresses or ranges you connect from (up to 10, each
/24or narrower). When you send them, only those addresses can connect.
You receive the host, the port and your username. One credential covers your main account and all its sub-accounts. You log in with your SSH key only: passwords are not accepted. A credential can hold two keys at a time, so you can replace a key without downtime.
2. Folder layout
/<accountId>/<FOLDER>/<filename>
<accountId>is the account the document belongs to: the sub-account ID (subAccountId), or your main account ID (the top-levelidofGET /v2/account/account-infowithoutsubAccountId).<FOLDER>is a document type or a tag.<filename>uses onlyA-Z a-z 0-9 . _ -and ends in.pdf,.png,.jpgor.jpeg. Under a tag it may also end in.gif,.webp,.tiff,.bmp,.txt,.csv,.xls,.xlsx,.doc,.docxor.zip.
Connect:
sftp -P <port> -i ~/.ssh/avenia_ed25519 <username>@<host>
Send one file:
sftp> put /Users/me/docs/certificate.pdf /<accountId>/CERTIFICATE-OF-INCORPORATION/certificate.pdf
The first path is the file on your computer, the second is where it goes. Start both with /: a full path works from any folder. pwd shows where you are on the server.
The first time you use a folder, create it:
sftp> mkdir /<accountId>
sftp> mkdir /<accountId>/CERTIFICATE-OF-INCORPORATION
The server refuses the upload (most clients show Permission denied), and keeps nothing, when the first folder is not an account ID, when a file or folder name starts with ., when the file name has other characters, no extension or an extension that no folder accepts, or when the file is larger than 1 GB.
Other mistakes are accepted by the server and then rejected, with a DOCUMENT-UPLOAD-REJECTED webhook:
- an
<accountId>that is not one of your accounts:unknown-account. The webhook goes to your main account. - a
<FOLDER>that is not a document type or a tag, a file placed directly in/<accountId>/, or a file in a subfolder of<FOLDER>:invalid-folder. - a file that is not PDF, PNG, JPG or JPEG under a document type:
unsupported-format. - a document in the
OTHERfolder without a description in a.txt:description-required.
Describe a document with a .txt
Under a tag, a .txt carries a description in one of two ways.
It describes itself. To send the URL of your store, put it in /<accountId>/ACTIVITY-OWN-CHANNEL/store.txt:
https://shop.example.com
It describes the file with the same name. To describe letter.pdf, send letter.pdf.txt with the description first, then letter.pdf, in the same folder:
sftp> put /Users/me/docs/letter.pdf.txt /<accountId>/OTHER/letter.pdf.txt
sftp> put /Users/me/docs/letter.pdf /<accountId>/OTHER/letter.pdf
When letter.pdf is received, it takes the description of letter.pdf.txt. If the .txt is still being checked at that moment, the file waits for it. A file that arrives before its .txt has no description, and under OTHER it is rejected with description-required. The description is read once, when the file is received: to change it later, use PATCH. The .txt stays a document of its own, with the same description.
In both cases the whole text of the .txt becomes the description, as long as it is valid UTF-8 and up to 500 characters. Line breaks and repeated spaces become a single space, and a byte order mark at the start is ignored. A longer .txt, or one that is not plain text, is kept as a file without a description and describes no other file. Under OTHER, such a .txt is rejected with description-required. A .txt stays downloadable like any other file.
By API, a .txt sent without description also describes itself. Pairing a file with its <file>.txt works only by SFTP: by API, send description with the file.
Send several files
All files of a kind to one folder, ending the destination with /:
sftp> put /Users/me/docs/*.pdf /<accountId>/INVOICES/
Files to different folders: write the commands in a file and run it with -b.
put /Users/me/docs/statement.xlsx /<accountId>/FINANCIALS/statement.xlsx
put /Users/me/docs/store.txt /<accountId>/ACTIVITY-OWN-CHANNEL/store.txt
put /Users/me/docs/letter.pdf.txt /<accountId>/OTHER/letter.pdf.txt
put /Users/me/docs/letter.pdf /<accountId>/OTHER/letter.pdf
ssh-add ~/.ssh/avenia_ed25519
sftp -P <port> -i ~/.ssh/avenia_ed25519 -b batch.txt <username>@<host>
-b doesn't ask for your key's passphrase, hence ssh-add first. It stops at the first command that fails.
In OTHER, send the .txt files before the others. A wildcard sends files in alphabetical order, so put * sends letter.pdf before letter.pdf.txt, and letter.pdf is rejected with description-required:
sftp> put /Users/me/docs/*.txt /<accountId>/OTHER/
sftp> put /Users/me/docs/*.pdf /<accountId>/OTHER/
3. Versions
Uploading a file again to the same path doesn't overwrite it: it creates a new version, a new document with its own id and the next versionNumber. Earlier versions stay in the Inbox with their own status. The latest version is the one used when a KYB cites the file by its path; to use an earlier one, cite it by id.
You can't delete or rename files. To update a file, upload it again to the same path. To fix a wrong folder, upload the file to the right one.
Send files and descriptions by API
Each POST creates one document, which carries a file, a description, or both:
- A file, with or without a description, takes two steps: request an upload URL, then
PUTthe file to it. Uploading a file with the same name again creates another document, not a new version. - A description only, such as the URL of your store, takes one request under a tag. See Send a description only.
1. Request an upload URL
Endpoint
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
subAccountId (query) | string | No | The sub-account the document belongs to. Without it, your main account. |
documentType | string | One of documentType and tag | A document type: the folder of the file. |
tag | string | One of documentType and tag | A tag: the folder of the file. Send it instead of documentType. |
filename | string | Yes, for a file | The file name, without folders: only A-Z a-z 0-9 . _ -, ending in .pdf, .png, .jpg or .jpeg. Under a tag it may also end in .gif, .webp, .tiff, .bmp, .txt, .csv, .xls, .xlsx, .doc, .docx or .zip. |
sizeBytes | integer | Yes, for a file | The exact size of the file in bytes, from 1 to 10485760 (10 MB). |
description | string | Under OTHER, and for a description only | Free text about the document. Up to 500 characters on one line; leading and trailing spaces are removed. See Set a description. |
Request body
{
"documentType": "COMPANY-TAX-IDENTIFICATION-DOCUMENT",
"filename": "tax-id.pdf",
"sizeBytes": 482113,
"description": "Tax registration, updated September 2026"
}
Request example
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/document-inbox?subAccountId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
"documentType": "COMPANY-TAX-IDENTIFICATION-DOCUMENT",
"filename": "tax-id.pdf",
"sizeBytes": 482113,
"description": "Tax registration, updated September 2026"
}'
Response
201 Created:
{
"id": "0f8e7d3c-2b1a-4c5d-9e8f-7a6b5c4d3e2f",
"uploadUrl": "https://<pre-signed-upload-url>",
"expiresAtMs": 1790635442000
}
idis the ID the document will have once we receive the file. Store it: it isuploadIdin the webhooks and the value you cite in the KYB.uploadUrlis valid untilexpiresAtMs, 900 seconds (15 minutes) after it is issued.
Errors
| Status | error | Cause |
|---|---|---|
400 | InvalidFieldError: documentType is invalid | Both documentType and tag were sent, neither was, or documentType is not a document type. |
400 | InvalidFieldError: tag is invalid | tag is not one of the tags. |
400 | InvalidFieldError: description is invalid | Longer than 500 characters, or has a line break or another control character. Also when tag is OTHER and description is missing or blank, with or without a file. |
400 | InvalidFieldError: filename is invalid | The name has other characters, folders, or another extension. Also when filename is missing and the request is not a description only: with documentType, with sizeBytes, or without a description. |
400 | InvalidFieldError: sizeBytes is invalid | Below 1 or above 10485760, or missing while filename is sent. |
403 | Document Inbox is not enabled for this workspace | The Document Inbox is not enabled for your account. |
2. Upload the file
curl -X PUT "<uploadUrl>" --data-binary "@tax-id.pdf"
- Send exactly
sizeBytesbytes. The URL is signed for that size, and an upload of any other size is refused. - Use each URL once. A second upload to the same URL is stored as a separate document, with a new ID, and rejected with
upload-url-reused. - If the URL expires, request a new one. An
idwhose file never arrived returns404.
A successful PUT only means the file was stored. Its status comes with the webhook, where uploadId is the id from step 1. Files sent by API have no SFTP path: their uploadPath is "" and you cite them by ID.
Send a description only
To send information that is not a file, such as the URL of your store or website, send tag and description with no filename and no sizeBytes. A description only always goes under a tag: with documentType, the request returns 400 (InvalidFieldError: filename is invalid).
Request body
{
"tag": "ACTIVITY-OWN-CHANNEL",
"description": "https://shop.example.com"
}
Request example
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/document-inbox?subAccountId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
"tag": "ACTIVITY-OWN-CHANNEL",
"description": "https://shop.example.com"
}'
Response
201 Created, with no upload URL:
{
"id": "b3e1c2d4-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"uploadUrl": "",
"expiresAtMs": 0
}
- The document is created at once, with status
RECEIVED. There is nothing to upload. - No webhook is sent for it: this response is final.
- In the read endpoints it has
originalFilenameanduploadPath"",documentType"",versionNumber1, and itstaganddescription. A document withoriginalFilename""has no file. - You can replace its description with PATCH, but not clear it.
- It can't be cited in the KYB.
The errors are the same as in step 1.
Document status
Every file gets one status when it is checked. The status does not change afterwards; the result of the KYB review is reported separately, in analysis and in the review events.
status | Meaning | Can be cited in the KYB |
|---|---|---|
RECEIVED | The file passed the malware scan and the checks. A description only is always RECEIVED. | Yes, a file under a document type |
QUARANTINED | The malware scan found a threat. The file is never used. reason is malware. | No |
REJECTED | The file was not accepted. reason says why. | No |
Reasons
reason | status | Meaning |
|---|---|---|
malware | QUARANTINED | The malware scan found a threat. |
scan-failed | REJECTED | The malware scan could not be completed on the file. Send it again. |
unsupported-format | REJECTED | The format is not accepted in its folder: PDF, PNG, JPG or JPEG under a document type; under a tag, also GIF, WEBP, TIFF, BMP, TXT, CSV, XLS, XLSX, DOC, DOCX or ZIP. |
invalid-folder | REJECTED | The folder is not a document type or a tag, or the file is not directly inside it. documentType and tag are "". |
unknown-account | REJECTED | The SFTP account folder is not one of your accounts. Reported to your main account. |
upload-url-reused | REJECTED | A second upload to an API upload URL that had already been used. |
file-too-large | REJECTED | An API upload larger than 10 MB. |
description-required | REJECTED | A document sent by SFTP to the OTHER folder without a description: neither a .txt that holds one, nor a file whose <file>.txt arrived first. Send the .txt and then the file again, or send it by API with description. |
To correct a rejected file, send it again: the new upload is a new document. Setting a description on a rejected file with PATCH does not change its status.
Read your documents
Use these endpoints to show your documents or to reconcile after missing webhooks.
List documents
Endpoint
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
subAccountId | string | No | List the documents of this sub-account. Without it, your main account. |
status | string | No | RECEIVED, QUARANTINED or REJECTED. |
documentType | string | No | A document type. |
tag | string | No | A tag. |
createdAfter | integer | No | Unix milliseconds. Only documents created after it. |
cursor | string | No | The cursor of the previous page. |
An invalid value returns 400 naming the parameter, for example InvalidFieldError: status is invalid.
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/document-inbox?subAccountId=3fa85f64-5717-4562-b3fc-2c963f66afa6&status=RECEIVED" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Response
{
"documents": [
{
"id": "b3e1c2d4-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"documentType": "",
"tag": "ACTIVITY-OWN-CHANNEL",
"description": "https://shop.example.com",
"uploadPath": "",
"originalFilename": "",
"versionNumber": 1,
"status": "RECEIVED",
"reason": "",
"analysis": null,
"createdAtMs": 1790808242000
},
{
"id": "7c2d9e41-5a3b-4f6c-8d1e-2b9a0c4f6e83",
"documentType": "CERTIFICATE-OF-INCORPORATION",
"tag": "",
"description": "",
"uploadPath": "sftp:/3fa85f64-5717-4562-b3fc-2c963f66afa6/CERTIFICATE-OF-INCORPORATION/certificate.pdf",
"originalFilename": "certificate.pdf",
"versionNumber": 2,
"status": "RECEIVED",
"reason": "",
"analysis": null,
"createdAtMs": 1790721842000
},
{
"id": "0f8e7d3c-2b1a-4c5d-9e8f-7a6b5c4d3e2f",
"documentType": "COMPANY-TAX-IDENTIFICATION-DOCUMENT",
"tag": "",
"description": "Tax registration, updated September 2026",
"uploadPath": "",
"originalFilename": "tax-id.pdf",
"versionNumber": 1,
"status": "RECEIVED",
"reason": "",
"analysis": null,
"createdAtMs": 1790635442000
}
],
"cursor": ""
}
- Newest first, up to 100 documents per page. Every version is its own entry.
- When a page is full,
cursoris set: send it back with the same filters to get the next page. An emptycursormeans there are no more pages (the last page may come back empty). analysisis alwaysnullin the list. Read one document to see it.- A file rejected with
unknown-accountis not listed. Read it from your main account by its ID.
Get one document
Endpoint
Send the subAccountId of the account the document belongs to. A document of another account returns 404 (NotFoundError: document not found).
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/document-inbox/7c2d9e41-5a3b-4f6c-8d1e-2b9a0c4f6e83?subAccountId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Response
{
"document": {
"id": "7c2d9e41-5a3b-4f6c-8d1e-2b9a0c4f6e83",
"documentType": "CERTIFICATE-OF-INCORPORATION",
"tag": "",
"description": "",
"uploadPath": "sftp:/3fa85f64-5717-4562-b3fc-2c963f66afa6/CERTIFICATE-OF-INCORPORATION/certificate.pdf",
"originalFilename": "certificate.pdf",
"versionNumber": 2,
"status": "RECEIVED",
"reason": "",
"analysis": {
"status": "REJECTED",
"reason": "expired",
"reasonMessage": "Issued more than 90 days ago"
},
"createdAtMs": 1790721842000
}
}
Document fields
| Field | Type | Description |
|---|---|---|
id | string | Document ID. Each version has its own. The same value is uploadId in the webhooks. |
documentType | string | The document type of the folder. "" for a document under a tag, and for invalid-folder. |
tag | string | The tag folder of the document, or "". |
description | string | Your description, or "". |
uploadPath | string | For a file sent by SFTP, sftp:/<accountId>/<FOLDER>/<filename>: the path you can cite in the KYB when the folder is a document type. "" for a document sent by API. |
originalFilename | string | The file name as you sent it. "" for a description only, which has no file. |
versionNumber | integer | 1 for the first upload to an SFTP path, then one more for each new upload to it. Always 1 for a document sent by API. |
status | string | RECEIVED, QUARANTINED or REJECTED. See Document status. |
reason | string | Why the file was quarantined or rejected. "" otherwise. |
analysis | object or null | The latest KYB review of the document: status (SUBMITTED, APPROVED or REJECTED), reason and reasonMessage (see Review events). null until the document is cited in a KYB, and always null in the list and in the PATCH response. |
createdAtMs | integer | When we received the file, or created the description only, in Unix milliseconds. |
Ignore fields not listed here: we may add fields at any time.
Set a description
The description is free text you keep with a document, such as the URL of the store it refers to. Set it when you request the upload URL, or at any time with this endpoint. Apart from a .txt under a tag, it is the only way to describe a file sent by SFTP.
The description is optional, except under the tag OTHER and for a description only: there it is required, and can be replaced but not cleared.
Endpoint
Request body
{
"description": "Certified copy, September 2026"
}
descriptionis the only field you can change. The folder, the status and everything else never change.""clears it. Clearing the description of a description only, or of a document underOTHER, returns400(InvalidFieldError: description is invalid). A description of only spaces counts as"".- Up to 500 characters, after leading and trailing spaces are removed, on one line: no line breaks, tabs or other control characters. Otherwise, or when
descriptionis missing, the request returns400(InvalidFieldError: description is invalid). - Each version is its own document: after uploading a new version, describe it again.
- No webhook is sent. Webhooks already sent keep the description known at the time.
Request example
curl -X PATCH "https://api.sandbox.avenia.io:10952/v2/account/document-inbox/7c2d9e41-5a3b-4f6c-8d1e-2b9a0c4f6e83?subAccountId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
"description": "Certified copy, September 2026"
}'
Response
200 OK with the document, as in Get one document (analysis is null here):
{
"document": {
"id": "7c2d9e41-5a3b-4f6c-8d1e-2b9a0c4f6e83",
"documentType": "CERTIFICATE-OF-INCORPORATION",
"tag": "",
"description": "Certified copy, September 2026",
"uploadPath": "sftp:/3fa85f64-5717-4562-b3fc-2c963f66afa6/CERTIFICATE-OF-INCORPORATION/certificate.pdf",
"originalFilename": "certificate.pdf",
"versionNumber": 2,
"status": "RECEIVED",
"reason": "",
"analysis": null,
"createdAtMs": 1790721842000
}
}
A document of another account returns 404. A file rejected with unknown-account can't be edited.
Webhooks
Subscribe to DOCUMENT (see Webhook Management). How delivery works, duplicates included, is in Webhooks in Practice.
| Event | Sent when |
|---|---|
DOCUMENT-RECEIVED | A file was received with status RECEIVED. |
DOCUMENT-QUARANTINED | A file was quarantined (malware). |
DOCUMENT-UPLOAD-REJECTED | A file was rejected. reason says why. |
DOCUMENT-SUBMITTED | A KYB submission cited the document. |
DOCUMENT-APPROVED | The KYB review approved the document. |
DOCUMENT-REJECTED | The KYB review rejected the document. |
event.accountId is the account the document belongs to, except for unknown-account, which goes to your main account.
Receipt events
DOCUMENT-RECEIVED, DOCUMENT-QUARANTINED and DOCUMENT-UPLOAD-REJECTED are sent once per file. A description only has no file and gets no receipt event: the response to its POST is final.
{
"event": {
"id": "6df2ae75-670f-4619-a6b1-8a5018af56b0",
"accountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"subscription": "DOCUMENT",
"data": {
"type": "DOCUMENT-RECEIVED",
"document": {
"uploadId": "7c2d9e41-5a3b-4f6c-8d1e-2b9a0c4f6e83",
"uploadPath": "sftp:/3fa85f64-5717-4562-b3fc-2c963f66afa6/CERTIFICATE-OF-INCORPORATION/certificate.pdf",
"versionNumber": 2,
"documentType": "CERTIFICATE-OF-INCORPORATION",
"originalFilename": "certificate.pdf",
"status": "RECEIVED",
"createdAtMs": 1790721842000
}
},
"createdAt": "2026-09-29T22:44:02Z"
}
}
| Field | Description |
|---|---|
uploadId | The document ID: the id of the read endpoints and, for an API upload, the id returned when you requested the upload URL. |
uploadPath | sftp:/<accountId>/<FOLDER>/<filename> for a file sent by SFTP, "" for a file sent by API. |
versionNumber | See Document fields. |
documentType | See Document fields. |
originalFilename | The file name as you sent it. |
status | RECEIVED, QUARANTINED or REJECTED. |
reason | See Reasons. Omitted when empty. |
tag | The tag folder. Omitted when empty. |
description | The description known when the file was received, so only a file sent by API can have one here. Omitted when empty. |
createdAtMs | When we received the file, in Unix milliseconds. |
To match an event to your upload, use uploadId for a file sent by API, and uploadPath with versionNumber for a file sent by SFTP.
A file sent by API under a tag, with a description, and quarantined:
"data": {
"type": "DOCUMENT-QUARANTINED",
"document": {
"uploadId": "9d4c2b1a-6e5f-4a3b-8c7d-1e2f3a4b5c6d",
"uploadPath": "",
"versionNumber": 1,
"documentType": "",
"originalFilename": "bank-statement.pdf",
"status": "QUARANTINED",
"reason": "malware",
"tag": "FINANCIALS",
"description": "Bank statement, October 2026",
"createdAtMs": 1790894642000
}
}
A file sent by SFTP to the OTHER folder without its letter.pdf.txt. It has the tag and no document type, and is rejected because OTHER requires a description:
"data": {
"type": "DOCUMENT-UPLOAD-REJECTED",
"document": {
"uploadId": "2a4c6e8f-1b3d-4f5a-8c7e-9d0b1a2c3e4f",
"uploadPath": "sftp:/3fa85f64-5717-4562-b3fc-2c963f66afa6/OTHER/letter.pdf",
"versionNumber": 1,
"documentType": "",
"originalFilename": "letter.pdf",
"status": "REJECTED",
"reason": "description-required",
"tag": "OTHER",
"createdAtMs": 1790635442000
}
}
A file sent by SFTP to a folder that is not one of your accounts. The event goes to your main account (event.accountId), and uploadPath shows the folder you used:
"data": {
"type": "DOCUMENT-UPLOAD-REJECTED",
"document": {
"uploadId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
"uploadPath": "sftp:/3fa85f64-5717-4562-b3fc-2c963f66afa7/CERTIFICATE-OF-INCORPORATION/certificate.pdf",
"versionNumber": 1,
"documentType": "CERTIFICATE-OF-INCORPORATION",
"originalFilename": "certificate.pdf",
"status": "REJECTED",
"reason": "unknown-account",
"createdAtMs": 1790635442000
}
}
Review events
When you submit KYB Level 1 by API with the Document Inbox enabled, every document the submission cites (the company documents, and the identification and selfie of each UBO in uboIds) is followed on its own, whether it came from the Inbox or from POST /v2/documents:
DOCUMENT-SUBMITTEDis sent for each one when you submit.- When the KYB is approved, every cited document gets
DOCUMENT-APPROVED. - When the KYB is rejected, our team marks the documents it reviewed: each gets
DOCUMENT-APPROVEDorDOCUMENT-REJECTED. The others staySUBMITTEDand get no further event.
{
"event": {
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"accountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"subscription": "DOCUMENT",
"data": {
"type": "DOCUMENT-REJECTED",
"document": {
"uploadId": "7c2d9e41-5a3b-4f6c-8d1e-2b9a0c4f6e83",
"uploadPath": "sftp:/3fa85f64-5717-4562-b3fc-2c963f66afa6/CERTIFICATE-OF-INCORPORATION/certificate.pdf",
"documentType": "CERTIFICATE-OF-INCORPORATION",
"status": "REJECTED",
"reason": "expired",
"reasonMessage": "Issued more than 90 days ago",
"attemptId": "9c4a2f71-8d3e-4b6c-a157-2a0f9b5d3e84"
}
},
"createdAt": "2026-09-30T14:02:11Z"
}
}
| Field | Description |
|---|---|
uploadId | The cited document ID: an Inbox id, or the ID of a document uploaded with POST /v2/documents. |
uploadPath | The sftp:/ path of a file sent by SFTP; "" otherwise. |
documentType | The document type it was cited as. |
status | SUBMITTED, APPROVED or REJECTED. |
reason | Why it was rejected (see below). "" otherwise. |
reasonMessage | A detail from our team, always present when reason is other. "" otherwise. |
attemptId | The KYB attempt that cites the document. |
reason | Meaning |
|---|---|
illegible | The document can't be read (blurry, cropped, low resolution). |
expired | The document is expired or too old. |
wrong-document-type | The file is not the document type it was cited as. |
incomplete | Pages or sides are missing. |
data-mismatch | The data does not match the account (name, tax ID, address). |
not-accepted | The document was not accepted. No detail is given, and reasonMessage is "". |
other | Another reason, explained in reasonMessage. |
A document rejected in a KYB review can't be cited again in any KYB: send a corrected file, which gets a new ID.
The KYB attempt lists the same documents in documents (with the fields above, except attemptId), in GET /v2/kyc/attempts/{attemptId} and in the KYC-COMPLETED webhook. The latest review of each document is also its analysis.
Cite Inbox files in the KYB
A RECEIVED file can be cited in these fields, instead of a document uploaded with POST /v2/documents:
| Endpoint | Field | Folders accepted | File content |
|---|---|---|---|
POST /v2/kyc/new-level-1/api | certificateOfIncorporationDocumentId | CERTIFICATE-OF-INCORPORATION | |
POST /v2/kyc/new-level-1/api | taxIdentificationDocumentId | COMPANY-TAX-IDENTIFICATION-DOCUMENT | |
POST /v2/account/ubos, PATCH /v2/account/ubos/{uboId} | uploadedIdentificationId | ID, DRIVERS-LICENSE, PASSPORT, RESIDENCE-PERMIT | PNG or JPEG |
POST /v2/account/ubos, PATCH /v2/account/ubos/{uboId} | uploadedSelfieId | SELFIE, only when liveness is disabled for your account | PNG or JPEG |
Only files under these document types can be cited. A document under a tag, with or without a file, is refused with wrong document type, whether you cite it by ID or by path.
You can cite a file in two ways:
- By ID: the Inbox
id(uploadIdin the webhooks). It cites that exact version. Works for files sent by SFTP and by API. - By path:
sftp:/<accountId>/<FOLDER>/<filename>, theuploadPathof a file sent by SFTP. It cites the latest version at that path when you send the request; the request then stores that version's ID.
{
"certificateOfIncorporationDocumentId": "sftp:/3fa85f64-5717-4562-b3fc-2c963f66afa6/CERTIFICATE-OF-INCORPORATION/certificate.pdf",
"taxIdentificationDocumentId": "0f8e7d3c-2b1a-4c5d-9e8f-7a6b5c4d3e2f"
}
The file must:
- belong to the account of the request (the same
subAccountId); - have status
RECEIVED; - be in a folder the field accepts;
- have the content the field accepts. The content is checked, not only the extension: a file whose content does not match its extension is refused;
- not have been rejected in an earlier KYB review.
An Inbox file is a single image, so an identification document cited from the Inbox has one side only: put both sides in the same image. A SELFIE-FROM-LIVENESS file can't be cited: a liveness selfie comes only from a liveness session (see KYB Level 1 - API).
When a citation is refused, the request returns 400:
error | Cause |
|---|---|
document not found | No file at that sftp:/ path, or the Document Inbox is not enabled for your account. |
document still processing | The latest version at that sftp:/ path has not been checked yet. Wait for its webhook. |
document quarantined | The file is QUARANTINED. |
document rejected: <reason> | The file is REJECTED, for example document rejected: invalid-folder. |
wrong document type | The folder is not accepted by the field, or is a tag. With extraInfo unsupported format for this field, the content is not the one the field accepts. |
document belongs to another account | The file belongs to another of your accounts. Check subAccountId. |
document rejected in a previous review | The document was rejected in a KYB review. extraInfo names the field. |
InvalidFieldError: <field> is invalid | The sftp:/ path is malformed (extraInfo expected sftp:/<account>/<TYPE>/<file>), or a SELFIE was cited while liveness is enabled for your account (extraInfo Selfie must be uploaded using SELFIE-FROM-LIVENESS). |
Quick reference
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /v2/account/document-inbox | Request an upload URL for one file, or send a description only |
| PUT | uploadUrl | Upload the file, within 900 seconds |
| GET | /v2/account/document-inbox | List documents |
| GET | /v2/account/document-inbox/{documentId} | Read one document, with its latest review |
| PATCH | /v2/account/document-inbox/{documentId} | Set, replace or clear the description |