Skip to main content

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:

  1. Avenia enables the Document Inbox for your account.
  2. 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 .txt under a tag carries a description: its own, or that of the file with the same name.
  3. We scan the file for malware and check it. You get a DOCUMENT-RECEIVED, DOCUMENT-QUARANTINED or DOCUMENT-UPLOAD-REJECTED webhook with the document ID.
  4. You cite a RECEIVED file of a document type in the KYB, by its ID or by its SFTP path.
  5. When you submit the KYB, you get DOCUMENT-SUBMITTED for each cited document, then DOCUMENT-APPROVED or DOCUMENT-REJECTED once it is reviewed.
Enabling the Document Inbox

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:

JSON
{
"error": "Document Inbox is not enabled for this workspace"
}

Both channels feed the same folders, statuses, webhooks and read endpoints:

SFTPAPI
Best forBatches and automated uploadsOne file at a time, from your backend
File formatsPDF, PNG, JPG, JPEG; under a tag, also GIF, WEBP, TIFF, BMP, TXT, CSV, XLS, XLSX, DOC, DOCX, ZIPSame as SFTP
Maximum size1 GB per file10 MB (10485760 bytes) per file
AccountThe first folder of the pathsubAccountId query parameter
FolderThe second folder of the pathdocumentType or tag in the request
DescriptionA .txt under a tag, or afterwards with PATCHOn the request, or afterwards with PATCH
Description without a fileNoUnder a tag
Tag OTHEROnly with a description in a .txt; otherwise rejected (description-required)Accepted only with a description
Cite in the KYB byID 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.

info

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
IDIdentity card
DRIVERS-LICENSEDriver's license
PASSPORTPassport
RESIDENCE-PERMITResidence permit
SELFIESelfie
SELFIE-FROM-LIVENESSSelfie from a liveness session
PROOF-OF-ADDRESSProof of address of a person
PROOF-OF-FINANCIAL-CAPACITYProof of financial capacity
PROOF-OF-REVENUEProof of revenue
CERTIFICATE-OF-INCORPORATIONCertificate of incorporation
ARTICLES-OF-INCORPORATIONArticles of incorporation
COMPANY-TAX-IDENTIFICATION-DOCUMENTCompany tax identification document
PROOF-OF-ADDRESS-COMPANYProof of address of a company
OWNERSHIP-CHARTOwnership chart
SHAREHOLDER-REGISTERShareholder register
DIRECTORS-REGISTERDirectors register
PROOF-OF-SIGNING-AUTHORITYProof of signing authority
INVOICEInvoice
ADDITIONAL-ATTACHMENTAdditional 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.

TagWhat goes in it
COMPANYCompany documents: articles of association or constitutive act, business license, partners and directors, organization chart, powers of attorney, licenses.
IDENTITYIdentity document of a UBO, a representative, a director or an individual merchant.
ADDRESSProof of address, of the company or of a person.
ACTIVITY-MARKETPLACEProof that you sell on a marketplace: your store page, a marketplace fee statement.
ACTIVITY-OWN-CHANNELProof that you sell through your own website or app: the website or app, its domain, a sales report.
ACTIVITY-B2BProof that you sell to other companies (B2B): invoice, proforma invoice, contract, bill of lading or air waybill, export agreement.
INVOICESBrazilian invoices: NF-e and NFS-e, as PDF or as a ZIP of their XML files.
FINANCIALSFinancial statements, bank statements, income tax returns.
OTHERAnything 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 /24 or 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-level id of GET /v2/account/account-info without subAccountId).
  • <FOLDER> is a document type or a tag.
  • <filename> uses only A-Z a-z 0-9 . _ - and ends 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.

Connect:

Shell
sftp -P <port> -i ~/.ssh/avenia_ed25519 <username>@<host>

Send one file:

Shell
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:

Shell
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 OTHER folder 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:

Shell
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 /:

Shell
sftp> put /Users/me/docs/*.pdf /<accountId>/INVOICES/

Files to different folders: write the commands in a file and run it with -b.

batch.txt
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
Shell
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:

Shell
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 PUT the 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​

POSThttps://api.sandbox.avenia.io:10952/v2/account/document-inbox

Parameters​

FieldTypeRequiredDescription
subAccountId (query)stringNoThe sub-account the document belongs to. Without it, your main account.
documentTypestringOne of documentType and tagA document type: the folder of the file.
tagstringOne of documentType and tagA tag: the folder of the file. Send it instead of documentType.
filenamestringYes, for a fileThe 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.
sizeBytesintegerYes, for a fileThe exact size of the file in bytes, from 1 to 10485760 (10 MB).
descriptionstringUnder OTHER, and for a description onlyFree text about the document. Up to 500 characters on one line; leading and trailing spaces are removed. See Set a description.

Request body​

JSON
{
"documentType": "COMPANY-TAX-IDENTIFICATION-DOCUMENT",
"filename": "tax-id.pdf",
"sizeBytes": 482113,
"description": "Tax registration, updated September 2026"
}

Request example​

cURL
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:

JSON
{
"id": "0f8e7d3c-2b1a-4c5d-9e8f-7a6b5c4d3e2f",
"uploadUrl": "https://<pre-signed-upload-url>",
"expiresAtMs": 1790635442000
}
  • id is the ID the document will have once we receive the file. Store it: it is uploadId in the webhooks and the value you cite in the KYB.
  • uploadUrl is valid until expiresAtMs, 900 seconds (15 minutes) after it is issued.

Errors​

StatuserrorCause
400InvalidFieldError: documentType is invalidBoth documentType and tag were sent, neither was, or documentType is not a document type.
400InvalidFieldError: tag is invalidtag is not one of the tags.
400InvalidFieldError: description is invalidLonger 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.
400InvalidFieldError: filename is invalidThe 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.
400InvalidFieldError: sizeBytes is invalidBelow 1 or above 10485760, or missing while filename is sent.
403Document Inbox is not enabled for this workspaceThe Document Inbox is not enabled for your account.

2. Upload the file​

cURL
curl -X PUT "<uploadUrl>" --data-binary "@tax-id.pdf"
  • Send exactly sizeBytes bytes. 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 id whose file never arrived returns 404.

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​

JSON
{
"tag": "ACTIVITY-OWN-CHANNEL",
"description": "https://shop.example.com"
}

Request example​

cURL
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:

JSON
{
"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 originalFilename and uploadPath "", documentType "", versionNumber 1, and its tag and description. A document with originalFilename "" 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.

statusMeaningCan be cited in the KYB
RECEIVEDThe file passed the malware scan and the checks. A description only is always RECEIVED.Yes, a file under a document type
QUARANTINEDThe malware scan found a threat. The file is never used. reason is malware.No
REJECTEDThe file was not accepted. reason says why.No

Reasons​

reasonstatusMeaning
malwareQUARANTINEDThe malware scan found a threat.
scan-failedREJECTEDThe malware scan could not be completed on the file. Send it again.
unsupported-formatREJECTEDThe 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-folderREJECTEDThe folder is not a document type or a tag, or the file is not directly inside it. documentType and tag are "".
unknown-accountREJECTEDThe SFTP account folder is not one of your accounts. Reported to your main account.
upload-url-reusedREJECTEDA second upload to an API upload URL that had already been used.
file-too-largeREJECTEDAn API upload larger than 10 MB.
description-requiredREJECTEDA 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​

GEThttps://api.sandbox.avenia.io:10952/v2/account/document-inbox

Parameters​

FieldTypeRequiredDescription
subAccountIdstringNoList the documents of this sub-account. Without it, your main account.
statusstringNoRECEIVED, QUARANTINED or REJECTED.
documentTypestringNoA document type.
tagstringNoA tag.
createdAfterintegerNoUnix milliseconds. Only documents created after it.
cursorstringNoThe cursor of the previous page.

An invalid value returns 400 naming the parameter, for example InvalidFieldError: status is invalid.

Request example​

cURL
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​

JSON
{
"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, cursor is set: send it back with the same filters to get the next page. An empty cursor means there are no more pages (the last page may come back empty).
  • analysis is always null in the list. Read one document to see it.
  • A file rejected with unknown-account is not listed. Read it from your main account by its ID.

Get one document​

Endpoint​

GEThttps://api.sandbox.avenia.io:10952/v2/account/document-inbox/{documentId}

Send the subAccountId of the account the document belongs to. A document of another account returns 404 (NotFoundError: document not found).

Request example​

cURL
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​

JSON
{
"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​

FieldTypeDescription
idstringDocument ID. Each version has its own. The same value is uploadId in the webhooks.
documentTypestringThe document type of the folder. "" for a document under a tag, and for invalid-folder.
tagstringThe tag folder of the document, or "".
descriptionstringYour description, or "".
uploadPathstringFor 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.
originalFilenamestringThe file name as you sent it. "" for a description only, which has no file.
versionNumberinteger1 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.
statusstringRECEIVED, QUARANTINED or REJECTED. See Document status.
reasonstringWhy the file was quarantined or rejected. "" otherwise.
analysisobject or nullThe 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.
createdAtMsintegerWhen 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​

PATCHhttps://api.sandbox.avenia.io:10952/v2/account/document-inbox/{documentId}

Request body​

JSON
{
"description": "Certified copy, September 2026"
}
  • description is 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 under OTHER, returns 400 (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 description is missing, the request returns 400 (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
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):

JSON
{
"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.

EventSent when
DOCUMENT-RECEIVEDA file was received with status RECEIVED.
DOCUMENT-QUARANTINEDA file was quarantined (malware).
DOCUMENT-UPLOAD-REJECTEDA file was rejected. reason says why.
DOCUMENT-SUBMITTEDA KYB submission cited the document.
DOCUMENT-APPROVEDThe KYB review approved the document.
DOCUMENT-REJECTEDThe 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.

JSON
{
"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"
}
}
FieldDescription
uploadIdThe document ID: the id of the read endpoints and, for an API upload, the id returned when you requested the upload URL.
uploadPathsftp:/<accountId>/<FOLDER>/<filename> for a file sent by SFTP, "" for a file sent by API.
versionNumberSee Document fields.
documentTypeSee Document fields.
originalFilenameThe file name as you sent it.
statusRECEIVED, QUARANTINED or REJECTED.
reasonSee Reasons. Omitted when empty.
tagThe tag folder. Omitted when empty.
descriptionThe description known when the file was received, so only a file sent by API can have one here. Omitted when empty.
createdAtMsWhen 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:

JSON
"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:

JSON
"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:

JSON
"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-SUBMITTED is 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-APPROVED or DOCUMENT-REJECTED. The others stay SUBMITTED and get no further event.
JSON
{
"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"
}
}
FieldDescription
uploadIdThe cited document ID: an Inbox id, or the ID of a document uploaded with POST /v2/documents.
uploadPathThe sftp:/ path of a file sent by SFTP; "" otherwise.
documentTypeThe document type it was cited as.
statusSUBMITTED, APPROVED or REJECTED.
reasonWhy it was rejected (see below). "" otherwise.
reasonMessageA detail from our team, always present when reason is other. "" otherwise.
attemptIdThe KYB attempt that cites the document.
reasonMeaning
illegibleThe document can't be read (blurry, cropped, low resolution).
expiredThe document is expired or too old.
wrong-document-typeThe file is not the document type it was cited as.
incompletePages or sides are missing.
data-mismatchThe data does not match the account (name, tax ID, address).
not-acceptedThe document was not accepted. No detail is given, and reasonMessage is "".
otherAnother 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:

EndpointFieldFolders acceptedFile content
POST /v2/kyc/new-level-1/apicertificateOfIncorporationDocumentIdCERTIFICATE-OF-INCORPORATIONPDF
POST /v2/kyc/new-level-1/apitaxIdentificationDocumentIdCOMPANY-TAX-IDENTIFICATION-DOCUMENTPDF
POST /v2/account/ubos, PATCH /v2/account/ubos/{uboId}uploadedIdentificationIdID, DRIVERS-LICENSE, PASSPORT, RESIDENCE-PERMITPNG or JPEG
POST /v2/account/ubos, PATCH /v2/account/ubos/{uboId}uploadedSelfieIdSELFIE, only when liveness is disabled for your accountPNG 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 (uploadId in the webhooks). It cites that exact version. Works for files sent by SFTP and by API.
  • By path: sftp:/<accountId>/<FOLDER>/<filename>, the uploadPath of 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.
JSON
{
"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:

errorCause
document not foundNo file at that sftp:/ path, or the Document Inbox is not enabled for your account.
document still processingThe latest version at that sftp:/ path has not been checked yet. Wait for its webhook.
document quarantinedThe file is QUARANTINED.
document rejected: <reason>The file is REJECTED, for example document rejected: invalid-folder.
wrong document typeThe 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 accountThe file belongs to another of your accounts. Check subAccountId.
document rejected in a previous reviewThe document was rejected in a KYB review. extraInfo names the field.
InvalidFieldError: <field> is invalidThe 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​

MethodEndpointPurpose
POST/v2/account/document-inboxRequest an upload URL for one file, or send a description only
PUTuploadUrlUpload the file, within 900 seconds
GET/v2/account/document-inboxList 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