Address Verification

Verify proof of address through utility bills, bank statements, and government correspondence. AI-powered extraction validates name, address, issue date, and document authenticity. Supports documents in English and French.

Accepted Documents

Utility bills (electricity, water, internet), bank statements, tax documents, and government-issued correspondence dated within the last 3 months.

POST/verifications/address

Submit a proof-of-address document for verification. Uses multipart/form-data for file upload.

Request Body (multipart/form-data)

Parameter	Type	Description
`userId`required	string	Your internal user identifier
`documentType`required	enum	UTILITY_BILL, BANK_STATEMENT, TAX_DOCUMENT, or GOVERNMENT_LETTER
`document`required	file	Document image or PDF (max 10MB)
`country`required	string	ISO 3166-1 alpha-2 country code
`expectedAddress`	string	Expected address to match against (improves accuracy)

Code Examples

curl -X POST https://api.verifyhq.com/v1/verifications/address \
  -H "X-API-Key: your_api_key" \
  -F "userId=user_123" \
  -F "documentType=UTILITY_BILL" \
  -F "document=@electricity_bill.pdf" \
  -F "country=CI"

Response

201 Createdjson

{
  "id": "addr_abc123",
  "userId": "user_123",
  "documentType": "UTILITY_BILL",
  "status": "PROCESSING",
  "createdAt": "2026-02-18T13:00:00Z"
}

GET/verifications/address/:id

Retrieve the status and extracted data of an address verification.

curl https://api.verifyhq.com/v1/verifications/address/addr_abc123 \
  -H "X-API-Key: your_api_key"

Response

200 OKjson

{
  "id": "addr_abc123",
  "userId": "user_123",
  "documentType": "UTILITY_BILL",
  "status": "VERIFIED",
  "extractedData": {
    "fullName": "Adebayo Ogunlesi",
    "address": "12 Rue du Commerce, Abidjan, Côte d'Ivoire",
    "issueDate": "2026-01-05",
    "issuer": "CIE Electricity"
  },
  "addressMatch": true,
  "documentAge": "44 days",
  "completedAt": "2026-02-18T13:00:35Z",
  "createdAt": "2026-02-18T13:00:00Z"
}

GET/verifications/address/user/:userId

List all address verifications for a specific user.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 100)

curl "https://api.verifyhq.com/v1/verifications/address/user/user_123?page=1&limit=10" \
  -H "X-API-Key: your_api_key"

POST/verifications/address/:id/review

Submit a manual review decision for an address verification in MANUAL_REVIEW status.

Request Body

Parameter	Type	Description
`decision`required	enum	VERIFIED or REJECTED
`reviewedBy`required	string	Identifier of the reviewer
`reviewNotes`required	string	Notes explaining the review decision

curl -X POST https://api.verifyhq.com/v1/verifications/address/addr_abc123/review \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "VERIFIED",
    "reviewedBy": "admin_john",
    "reviewNotes": "Address matches utility bill. Document is recent."
  }'

Verification Statuses

Parameter	Type	Description
`PROCESSING`	status	Document uploaded, AI extraction in progress
`MANUAL_REVIEW`	status	Flagged for human review (low confidence or mismatches)
`VERIFIED`	status	Address confirmed from document
`REJECTED`	status	Document invalid, expired, or address mismatch

Webhook Events

Parameter	Type	Description
`address.verified`	event	Address successfully verified from document
`address.rejected`	event	Address verification rejected
`address.manual_review`	event	Address verification flagged for manual review