Skip to main content

KYB - Proof of Address

Submit a Proof of Address to raise the limits on a company subaccount. This step is independent of KYB Level 1: Level 1 verifies the company's identity, while Proof of Address (and, for fiat rails, Proof of Financial Capacity) unlocks higher operating limits.

info

Proof of Address is always submitted against a COMPANY subaccount. Pass its ID as ?subAccountId= on every call below.

info

KYB Level 1 must be approved before submitting Proof of Address. See KYB Level 1 (Web SDK) or KYB Level 1 (API).

The flow is the same two-phase pattern used everywhere else: upload the document, wait until it is ready, then submit the document ID for verification.

Step 1 - Upload the Proof of Address Document​

Upload via POST /v2/documents?subAccountId={subAccountId} (same two-phase upload described in KYB Level 1 (API) - Step 2). Use the documentType that matches what the document proves:

DocumentdocumentTypeProves
Company proof of addressPROOF-OF-ADDRESS-COMPANYThe company's registered business address
UBO proof of residencePROOF-OF-ADDRESSAn Ultimate Beneficial Owner's residence

Both are single-sided PDF documents. Poll GET /v2/documents/{documentId}?subAccountId={subAccountId} (or listen for the document webhook) until ready: true before continuing.

tip

A proof of address is typically valid for the last 3 months. If you are relying on documents collected during your own onboarding, they may be accepted up to 12 months old — confirm the accepted age with your account manager.

Step 2 - Submit the Proof of Address​

Once the document is ready, submit its ID for verification.

HTTP POST Request​

https://api.sandbox.avenia.io:10952/v2/account/address/proof-of-address/api?subAccountId={subAccountId}

Fields​

FieldTypeRequiredDescription
uploadedPoAIdstringYesID of the PROOF-OF-ADDRESS or PROOF-OF-ADDRESS-COMPANY document (must have ready: true).
sandboxRejectbooleanNoSet to true to simulate a rejected Proof of Address in the sandbox environment.

Sample JSON Body​

{
  "uploadedPoAId": "c4e9b27f-1a3d-4e8c-b561-7d2f0a9e4b38"
}

JSON Response​

{
  "id": "1e6b8c43-5f2a-4d9e-b782-4c1f0a7e3b65"
}

The returned id is the Proof of Address attempt ID.

Step 3 - Poll the Proof of Address Attempt​

Polling is optional when webhooks are configured.

HTTP GET Request​

https://api.sandbox.avenia.io:10952/v2/account/address/proof-of-address/attempts/{attemptId}?subAccountId={subAccountId}

Sample JSON Response​

{
  "attempt": {
    "id": "1e6b8c43-5f2a-4d9e-b782-4c1f0a7e3b65",
    "uploadedPoAId": "c4e9b27f-1a3d-4e8c-b561-7d2f0a9e4b38",
    "status": "COMPLETED",
    "result": "APPROVED",
    "resultMessage": "",
    "createdAt": "2026-03-19T22:09:56.631111Z",
    "updatedAt": "2026-03-19T22:09:56.865286Z"
  }
}

Wait until result is APPROVED. You can list all attempts with GET /v2/account/address/proof-of-address/attempts?subAccountId={subAccountId}.

Quick Reference​

StepMethodEndpointOutput
1POST + PUT/v2/documents?subAccountId={id} + S3 URLDocument ID
2POST/v2/account/address/proof-of-address/api?subAccountId={id}PoA attempt ID
3GET/v2/account/address/proof-of-address/attempts/{attemptId}?subAccountId={id}Poll until APPROVED