Address & Proof of Address

The Address API exposes the residential address linked to an account, plus the Proof of Address (PoA) verification flow used to validate it.

info

To perform any of these operations on behalf of a Subaccount, pass the subAccountId field as a query parameter.

---

Get Address

Returns the current address on file for the account (or subaccount). The address may have been collected during KYC or extracted from an approved Proof of Address document.

HTTP GET Request

https://api.sandbox.avenia.io:10952/v2/account/address

Query Parameters

Parameter	Type	Required	Description
subAccountId	string	No	The ID of the subaccount to fetch the address of.

JSON Response

{
  "address": {
    "streetLine1": "AV PAULISTA 1000 APT 204",
    "streetLine2": "",
    "streetLine3": "",
    "city": "SAO PAULO",
    "countrySubdivision": "SP",
    "zipCode": "01310-100",
    "country": "BRA",
    "source": "USER"
  }
}

Response Fields

Field	Type	Description
streetLine1	string	Street address, first line.
streetLine2	string	Street address, second line (optional, may be empty).
streetLine3	string	Street address, third line (optional, may be empty).
city	string	City of residence.
countrySubdivision	string	State or province (ISO 3166-2 subdivision code, e.g. SP, BR-SP, NY).
zipCode	string	Postal code.
country	string	Country of residence (ISO 3166-1 alpha-3, e.g. BRA, USA).
source	string	Source of the address. Possible values: USER (provided at KYC/manually) or PROOF-OF-ADDRESS (extracted from an approved PoA attempt).

info

If the account has no address on file, the address object will be empty.

cURL Example

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/address" \
     -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

---

Update Address

Overwrites the account's address with the values provided. All fields are replaced.

HTTP PUT Request

https://api.sandbox.avenia.io:10952/v2/account/address

Fields

Field	Type	Required	Description
streetLine1	string	Yes	Street address, first line.
streetLine2	string	No	Street address, second line.
streetLine3	string	No	Street address, third line.
city	string	Yes	City of residence.
countrySubdivision	string	Yes	State or province (ISO 3166-2 subdivision code).
zipCode	string	Yes	Postal code.
country	string	Yes	Country of residence (ISO 3166-1 alpha-3, e.g. BRA).

Sample JSON Body

{
  "streetLine1": "AV PAULISTA 1000 APT 204",
  "streetLine2": "",
  "streetLine3": "",
  "city": "SAO PAULO",
  "countrySubdivision": "SP",
  "zipCode": "01310-100",
  "country": "BRA"
}

JSON Response

200 OK with empty body on success.

cURL Example

curl -X PUT "https://api.sandbox.avenia.io:10952/v2/account/address" \
     -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
     -H "Content-Type: application/json" \
     -d '{
       "streetLine1": "AV PAULISTA 1000 APT 204",
       "city": "SAO PAULO",
       "countrySubdivision": "SP",
       "zipCode": "01310-100",
       "country": "BRA"
     }'

---

Proof of Address - API Flow

Proof of Address is verified in three phases:

1. Upload a PROOF-OF-ADDRESS document and wait until it is ready (see KYC Level 1 - Step 1 and Step 2).
2. Submit the uploaded document ID to the PoA endpoint to start a verification attempt.
3. Poll the attempt until it reaches a final result, or listen for the corresponding webhook.

Step 1 - Submit a Proof of Address Attempt

Creates a new PoA verification attempt using a document previously uploaded with documentType: PROOF-OF-ADDRESS.

HTTP POST Request

https://api.sandbox.avenia.io:10952/v2/account/address/proof-of-address/api

Fields

Field	Type	Required	Description
uploadedPoAId	string	Yes	The id returned when the PROOF-OF-ADDRESS document was created. The document must be in ready: true state.
sandboxReject	boolean	No	Set to true to simulate a rejected PoA attempt in the sandbox environment. Defaults to false.

Sample JSON Body

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

JSON Response

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

Save the returned id - it is the PoA attempt ID used for polling.

cURL Example

curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/address/proof-of-address/api" \
     -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
     -H "Content-Type: application/json" \
     -d '{
       "uploadedPoAId": "c4e9b27f-1a3d-4e8c-b561-7d2f0a9e4b38"
     }'

---

Step 2 - List Proof of Address Attempts

Returns a paginated list of PoA attempts for the account (or subaccount).

HTTP GET Request

https://api.sandbox.avenia.io:10952/v2/account/address/proof-of-address/attempts

Query Parameters

Parameter	Type	Required	Description
createdAfter	number	No	Unix timestamp; returns only attempts created after this value.
createdBefore	number	No	Unix timestamp; returns only attempts created before this value.
cursor	string	No	Pagination cursor from the previous response.
subAccountId	string	No	The ID of the subaccount to query.

Sample JSON Response

{
  "attempts": [
    {
      "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"
    }
  ],
  "cursor": "MTEwLTE3NDMwMjkzNTUyODE="
}

---

Step 3 - Get Proof of Address Attempt by ID

Retrieves a single PoA attempt by its ID. Use this to poll for the final result.

HTTP GET Request

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

Path Parameters

Parameter	Type	Description
attemptId	string	The ID returned by the POST endpoint in Step 1.

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"
  }
}

Response Fields

Field	Description
id	Unique ID of the PoA attempt.
uploadedPoAId	ID of the PROOF-OF-ADDRESS document that was submitted.
status	Processing status. Possible values: PENDING, PROCESSING, COMPLETED, EXPIRED.
result	Final outcome. Possible values: APPROVED, REJECTED. Empty until status is COMPLETED.
resultMessage	Human-readable explanation when result is REJECTED.
createdAt	Creation timestamp (ISO 8601).
updatedAt	Last update timestamp (ISO 8601).

info

If webhooks are configured, you will receive a PROOF-OF-ADDRESS event whenever an attempt reaches a final state. Polling is not required in that case.

---

Quick Reference

Action	Method	Endpoint
Get address	GET	/v2/account/address
Update address	PUT	/v2/account/address
Submit PoA attempt	POST	/v2/account/address/proof-of-address/api
List PoA attempts	GET	/v2/account/address/proof-of-address/attempts
Get PoA attempt by ID	GET	/v2/account/address/proof-of-address/attempts/{id}