INTERESTED ?
Physical Address Verification API
API FOR IN PERSON PHYSICAL ADDRESS BACKGROUND VERIFICATION
Introduction
Physical address verification API is one among the suite of background check APIs offered by the Attestr Platform. This asynchronous API accepts input for the address and point of contact information. When requested, the on-field executive visits the requested location personally to verify the information and records it. These details are then made accessible via web hooks and APIs, providing end-to-end automation.
To start a chat, click the button below, and one of our available executives will assist you with questions about onboarding and commercials.

API Details
Request
Type | URL |
---|---|
POST | https://api.attestr.com/api/{version} /public/factx/async/address |
Request Header Parameters
Type | Name | Value / Description | Optional | Min Version | Max Version |
---|---|---|---|---|---|
String | Content-Type | application/json | Required | v1 | |
String | Authorization | Basic {authToken} | Required | v1 |
If you do not have the authentication token, please refer to Register App to generate one.
Request Body Parameters
Type | Name | Description | Optional (default) | Min Version | Max Version |
---|---|---|---|---|---|
String | tag | Unique employee Id / reference id to be passed by the client | Required | v1 | |
String | address | Complete address to be verified, including house number, locality, landmark, state, district and zip code | Required | v1 | |
Boolean | current | Flag indicating if the provided address is the current address of the candidate | Optional | v1 | |
Boolean | permanent | Flag indicating if the provided address is the permanent address of the candidate | Optional | v1 | |
String | pocType | Type of point of contact. It can have the following two values.
| Required | v1 | |
Number | pocName | Name of point of contact. Required only if pocType is OTHER. | Conditional | v1 | |
Number | pocContact | Contact number of the provided point of contact. Required only if pocType is OTHER. | Conditional | v1 | |
Boolean | pocRelation | Relation with the provided point of contact. Required only if pocType is OTHER | Conditional | v1 | |
String[] | documents | Array of supporting document Ids. To generate document Ids, first upload each document using Document Upload | Optional | v1 | |
Boolean | webhook | Boolean flag to be used for triggering webhooks once record is updated. More details below. | Optional | v1 |
Sample Request
{
"tag": "ABCD1234",
"address": "8-2-293/K/57/101 Kamlapuri Colony Phase 3 Hyderabad Telangana 500073",
"permanent": false,
"current": false,
"pocType": "OTHER",
"pocName":"Gitanjali Raheja",
"pocContact":"+91889876472384",
"pocRelation": "SPOUSE",
"documents": ["MX17Cd6KEBSsbKSaou"],
"webhook": false
}
Response Details
Http Status 200
Key | Description | Type | Min Version | Max Version |
---|---|---|---|---|
_id | Unique request Id to be used later for querying the result | String | v1 | |
number | Unique human readable number to be used for any reference later | String | v1 |
{
"_id": "AR02zfeuv2iz5ksij09nf",
"number": "3801-575765-9695"
}
Querying Address Check Result
Get Address Async Request Outcome API
Type | URL | Min Version | Max Version |
---|---|---|---|
GET | https://api.attestr.com/api/{version}/public/async/<asyncId> | v1 |
Request Header Parameters
Type | Name | Value / Description | Optional | Min Version | Max Version |
---|---|---|---|---|---|
String | Content-Type | application/json | Required | v1 | |
String | Authorization | Basic {authToken} | Required | v1 |
Request URL Parameters
Name | Description | Min Version | Max Version |
---|---|---|---|
asyncId | Replace <asyncId> in the URL with the _id received in the physical address verification API response as described above. | v1 |
Response
Http Status 200
Key | Description | Type | Min Version | Max Version |
---|---|---|---|---|
_id | Request Id as queried in the URL | String | v1 | |
number | Request number | String | v1 | |
requestId | Unique ID used by Attestr for request tracing purposes | String | v1 | |
status | Status of the request. Possible values are - COMPLETED, INITIATED, ERRORED | String | v1 | |
input | The input details used for verification | String | v1 | |
output | Address check output object. Details described as below. Null if status is errored or initiated. | AddressCheckOutputRecord | v1 | |
error | Error object if the operation ran into errors, null otherwise. Null if status is completed or initiated. | String | v1 | |
created | Unix timestamp when the request was placed. | Number | v1 | |
updated | Unix timestamp when the request was last updated. Null if status is initiated. | Number | v1 | |
signature | Signature generated using the output and client secret. Used for validating the accuracy of data. Null if status is errored or initiated. | String | v1 |
Address Check Output Record
Key | Description | Type | Min Version | Max Version |
---|---|---|---|---|
status | One of Clear, Alert, False, MoreInfo, NoResult | String | v1 | |
mode | Mode of verification e.g Online, Offline, Physical, Email, Telephone etc | String | v1 | |
verified | Date on which verified data was received from the institution. For online verification, it is the date on which verification was performed. DD-MM-YYYY | Date | v1 | |
verifier | Name of the verifying body / individual | String | v1 | |
authority | Name of the individual or department that verified the document | String | v1 | |
description | Description text provided by Attestr back office for each verification. This text is particularly useful for alert and false cases. HTML formatted string. | String | v1 | |
documents | List of supporting verified letter, documents as received or prepared | Array[String] | v1 | |
voiceRecords | In case the verification has been performed over the phone, it contains an array of voice recording media Ids. In most cases, this will be null. | Array[String] | v1 |
Sample Output
{
"status": "Clear",
"documents": [
"MX1xRollD8Szmm4iI7","MX1xX1geabcdeem4iI7"
],
"voiceRecords": null,
"description": "On July 29, 2022, around 11 AM, the field executive paid a visit to the indicated address. The address is situated in a far-flung village, about 20 kilometres from the Nashik district. Mr. Naresh, the father of the candidate, was discovered to be residing there together with three other family members. When asked for proof, he produced his identification card and the electricity bill. Copies of both documents are included in this letter. The absence of the home number plate was notice however due to the isolated location. However, the neighbours verified the plot number and discovered that it matched the details given. A snapshot of the home's main entryway is also offered as evidence. The completed form attesting to the information above is also provided.",
"verifier": "Mr. Naresh",
"authority": "Individual",
"verified": "09-02-2022",
"mode": "Physical"
}
Error Response
Parameter | Type | Description |
---|---|---|
code | Number | Unique error codes for different errors. Always available. |
message | String | Error message describing the error. Always Available. |
details | String | Detail error message. Available only for certain types of errors. |
Error Codes
HTTP Status | Error Code | Error Message |
---|---|---|
400 | 4001 | Malformed data or missing required parameter values |
400 | 4005 | Operation could not be performed due to low credits balance |
401 | 4016 | Invalid client authorization |
403 | 4031 | Unauthorized access |
403 | 4035 | Requested service is not provisioned for your account |
403 | 4039 | Client's IP address is not whitelisted |
403 | 4035 | Requested service is not provisioned for your account |
429 | 4291 | Maximum account rate limit exceeded |
429 | 4292 | Maximum API rate limit exceeded |
429 | 4293 | Maximum account daily limit exceeded |
429 | 4294 | Maximum API daily limit exceeded |
500 | 5001 | Request could not be processed |
Sample Error Response
{
"code": 4001,
"message": "Malformed data or missing required parameter values"
}
Webhooks
This check supports the following two webhook events.
See Webhooks for more details on how to register webhooks.
- async.completed
- async.errored
To enable webhooks, the API input parameter webhook must be set as true while initiating the request.
Webhook Event Payload
Key | Type | Description | Min Version | Max Version |
---|---|---|---|---|
_id | String | ID of the async request. This is same as received in the output of Person / Business search API as described above. | v1 | |
requestId | String | Unique request ID for internal tracing purposes. | v1 | |
status | String | One of INITIATED, COMPLETED OR ERRORED | v1 | |
output | Object | Address Check output record same as output key described in Querying Result API above. | ||
error | Object | Error object if the check runs into errors. The structure of this is same as the Error Response object described above. | v1 | |
signature | String | generated using hmacHexDigest of output object and client secret. Null if archived. |
INTERESTED ?
To start a chat, click the button below, and one of our available executives will assist you with questions about onboarding and commercials.
