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.

INTERESTED ?

To start a chat, click the button below, and one of our available executives will assist you with questions about onboarding and commercials.

Chat With Attestr Support

API Details

Request

TypeURL
POSThttps://api.attestr.com/api/{version}/public/factx/async/address

Request Header Parameters

TypeNameValue / DescriptionOptionalMin VersionMax Version
StringContent-Typeapplication/jsonRequiredv1
StringAuthorizationBasic {authToken}Requiredv1

If you do not have the authentication token, please refer to Register App to generate one.

Request Body Parameters

TypeNameDescriptionOptional (default)Min VersionMax Version
StringtagUnique employee Id / reference id to be passed by the clientRequiredv1
StringaddressComplete address to be verified, including house number, locality, landmark, state, district and zip codeRequiredv1
BooleancurrentFlag indicating if the provided address is the current address of the candidateOptionalv1
BooleanpermanentFlag indicating if the provided address is the permanent address of the candidateOptionalv1
StringpocType

Type of point of contact. It can have the following two values.

  1. SELF : If the candidate herself is staying at the provided address and is supposed to be available at the time of verification
  2. OTHER : If someone in the family stays at the provided location
Requiredv1
NumberpocNameName of point of contact. Required only if pocType is OTHER.Conditionalv1
NumberpocContactContact number of the provided point of contact. Required only if pocType is OTHER.Conditionalv1
BooleanpocRelationRelation with the provided point of contact. Required only if pocType is OTHERConditionalv1
String[]documentsArray of supporting document Ids. To generate document Ids, first upload each document using Document UploadOptionalv1
BooleanwebhookBoolean flag to be used for triggering webhooks once record is updated. More details below.Optionalv1

Sample Request

JSON
Copy

Response Details

Http Status 200

KeyDescriptionTypeMin VersionMax Version
_idUnique request Id to be used later for querying the resultStringv1
numberUnique human readable number to be used for any reference laterStringv1
Sample Output
Copy

Querying Address Check Result

Get Address Async Request Outcome API

TypeURLMin VersionMax Version
GEThttps://api.attestr.com/api/{version}/public/async/<asyncId>v1

Request Header Parameters

TypeNameValue / DescriptionOptionalMin VersionMax Version
StringContent-Typeapplication/jsonRequiredv1
StringAuthorizationBasic {authToken}Requiredv1

Request URL Parameters

NameDescriptionMin VersionMax Version
asyncIdReplace <asyncId> in the URL with the _id received in the physical address verification API response as described above.v1

Response

Http Status 200

KeyDescriptionTypeMin VersionMax Version
_idRequest Id as queried in the URLStringv1
numberRequest numberStringv1
requestIdUnique ID used by Attestr for request tracing purposesStringv1
statusStatus of the request. Possible values are - COMPLETED, INITIATED, ERROREDStringv1
inputThe input details used for verificationStringv1
outputAddress check output object. Details described as below. Null if status is errored or initiated.AddressCheckOutputRecordv1
errorError object if the operation ran into errors, null otherwise. Null if status is completed or initiated.Stringv1
createdUnix timestamp when the request was placed.Numberv1
updatedUnix timestamp when the request was last updated. Null if status is initiated.Numberv1
signatureSignature generated using the output and client secret. Used for validating the accuracy of data. Null if status is errored or initiated.Stringv1

Address Check Output Record

KeyDescriptionTypeMin VersionMax Version
statusOne of Clear, Alert, False, MoreInfo, NoResultStringv1
modeMode of verification e.g Online, Offline, Physical, Email, Telephone etcStringv1
verifiedDate on which verified data was received from the institution. For online verification, it is the date on which verification was performed. DD-MM-YYYYDatev1
verifierName of the verifying body / individualStringv1
authorityName of the individual or department that verified the documentStringv1
descriptionDescription text provided by Attestr back office for each verification. This text is particularly useful for alert and false cases. HTML formatted string.Stringv1
documentsList of supporting verified letter, documents as received or preparedArray[String]v1
voiceRecordsIn 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

JSON
Copy

Error Response

ParameterTypeDescription
codeNumberUnique error codes for different errors. Always available.
messageStringError message describing the error. Always Available.
detailsStringDetail error message. Available only for certain types of errors.

Error Codes

HTTP StatusError CodeError Message
4004001Malformed data or missing required parameter values
4004005Operation could not be performed due to low credits balance
4014016Invalid client authorization
4034031Unauthorized access
4034035Requested service is not provisioned for your account
4034039Client's IP address is not whitelisted
4034035Requested service is not provisioned for your account
4294291Maximum account rate limit exceeded
4294292Maximum API rate limit exceeded
4294293Maximum account daily limit exceeded
4294294Maximum API daily limit exceeded
5005001Request could not be processed

Sample Error Response

JSON
Copy

Webhooks

This check supports the following two webhook events.

See Webhooks for more details on how to register webhooks.

  1. async.completed
  2. async.errored

To enable webhooks, the API input parameter webhook must be set as true while initiating the request.

Webhook Event Payload

KeyTypeDescriptionMin VersionMax Version
_idStringID of the async request. This is same as received in the output of Person / Business search API as described above.v1
requestIdStringUnique request ID for internal tracing purposes.v1
statusStringOne of INITIATED, COMPLETED OR ERROREDv1
outputObjectAddress Check output record same as output key described in Querying Result API above.
errorObjectError object if the check runs into errors. The structure of this is same as the Error Response object described above.v1
signatureStringgenerated 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.

Chat With Attestr Support
Type to search, ESC to discard
Type to search, ESC to discard
Type to search, ESC to discard