Identity Verification - Detailed Documentation

The Identity Verification API is designed to verify identity information against stored data records from various databases. It provides a reliable way to ensure identity verification based on multiple data points, including personal information and address details.

API Playground:

/identity/verify

You can try the identity verify endpoint here.

Endpoints Overview

Verify Identity: Verify identity information by matching it against external and internal databases.

Authentication

To access the Address Verification API, authentication is required. A Bearer Token must be included in every request.

Tokens are valid for 60 minutes and must be refreshed after expiration.
Refer to the Authentication for detailed steps on obtaining a token.
Include the token in the Authorization header as follows:

Authorization: Bearer YOUR_ACCESS_TOKEN

API Base URL

Production:

https://api-umbrella.io/api/services

Sandbox:

https://sandbox-umbrella-api.azurewebsites.net/api/services

1. Verify Identity

Endpoint

POST /identity/verify

Description

This endpoint verifies identity information by matching it against external and internal databases.

Required Headers

Header	Value
Content-Type	`application/json`
Authorization	`Bearer yourAccessToken`

Request Body Parameters

Field	Type	Required	Description
`raw`	boolean	No	Flag to request raw data return. Defaults to `false`.
`identity`	object	Yes	Contains the personal identification details.
`identity.firstName`	string	Yes	First name of the individual.
`identity.lastName`	string	Yes	Last name of the individual.
`identity.nationalId`	string	No	National identification number.
`identity.birthDate`	string	Yes	Birthdate of the individual (format: `MM/DD/YYYY`).
`address`	object	Yes	Contains address details.
`address.street`	string	Yes	Street name of the address.
`address.houseNumber`	string	No	House or building number.
`address.building`	string	No	Building name or description.
`address.postalCode`	string	Yes	Postal or ZIP code of the address.
`address.city`	string	Yes	City of the address.
`address.district`	string	No	District or borough of the address.
`address.province`	string	No	Province or state of the address.
`address.countryCode`	string	Yes	ISO country code of the address.
`phone`	object	No	Contains phone contact details.
`phone.phoneNumber`	string	No	Phone number including international dialing code.

Response Structure

Field	Type	Description
`globalResult`	object	Contains the aggregate score from the verification process.
`globalResult.totalScore`	integer	Aggregate score from the verification process. Values include: `0` (Verification failed), `50` (No match found), `75` (Partial match, review needed), `100` (Verification successful).
`resultDetails`	array	Lists detailed match results from various data sources.
`resultDetails.datasource`	string	Identifier for the data source used in verification.
`resultDetails.country`	string	Country associated with the data source.
`resultDetails.matches`	array of `MatchRecord`	Detailed match results.
`resultDetails.matches.record`	string	Type of record matched.
`resultDetails.matches.match`	string	Result of the match against the record. Possible values: `full` (Full match), `partial` (Partial match), `not-present` (Record not present in the data source).

Response Codes

Code	Description
`200`	Successfully retrieved the verification results. Returns the verification data including total score and details of matches from various data sources.
`400`	Invalid request provided.
`401`	Authorization information is missing or invalid.

Global Result Table

Field	Type	Description
`totalScore`	integer	Aggregate score from the verification process. Values include:
`0`	integer	Verification failed.
`50`	integer	No match found.
`75`	integer	Partial match, review needed.
`100`	integer	Verification successful.

Example Request

{
"raw": false, // Optional: Flag to request raw data return. Defaults to false.
"identity": {
  "firstName": "John", // Required: First name of the individual.
  "lastName": "Doe",   // Required: Last name of the individual.
  "nationalId": "123456789", // Optional: National identification number.
  "birthDate": "05/15/1985"  // Required: Birthdate of the individual (format: yyyy/mm/dd).
},
"address": {
  "street": "Main Street", // Required: Street name of the address.
  "houseNumber": "123",    // Optional: House or building number.
  "building": "Apt 4B",   // Optional: Building name or description.
  "postalCode": "10001",  // Required: Postal or ZIP code of the address.
  "city": "New York",     // Required: City of the address.
  "district": "Manhattan", // Optional: District or borough of the address.
  "province": "NY",       // Optional: Province or state of the address.
  "countryCode": "US"     // Required: ISO country code of the address.
},
"phone": {
  "phoneNumber": "+1234567890" // Optional: Phone number including international dialing code.
}
}

Example Response

{
    "requestTrackingId": "ffefb592-aad5-43e5-b1bf-a66d1cfff1b8",
    "globalResult": {
        "totalScore": "100: VERIFICATION SUCCESSFUL"
    },
    "resultDetails": [
        {
            "datasource": "1: CREDIT",
            "country": "US",
            "matches": [
                {
                    "record": "CRD2-COMPLETENAME",
                    "match": "Full match made on Complete Name"
                },
                {
                    "record": "CRD2-FIRSTNAME",
                    "match": "Full match made on First Name/Given Name"
                },
                {
                    "record": "CRD2-LASTNAME",
                    "match": "Full match made on Last Name/Surname"
                },
                {
                    "record": "CRD2-DATEOFBIRTH",
                    "match": "Full match made on Date of Birth"
                },
                {
                    "record": "CRD2-DAYOFBIRTH",
                    "match": "Full match made on Day of Birth"
                },
                {
                    "record": "CRD2-MONTHOFBIRTH",
                    "match": "Full match made on Month of Birth"
                },
                {
                    "record": "CRD2-YEAROFBIRTH",
                    "match": "Full match made on Year of Birth"
                }
            ]
        },
        {
            "datasource": "2: CREDIT",
            "country": "US",
            "matches": [
                {
                    "record": "CRD4-COMPLETENAME",
                    "match": "Full match made on Complete Name"
                },
                {
                    "record": "CRD4-FIRSTINITIAL",
                    "match": "Full match made on First Initial"
                },
                {
                    "record": "CRD4-FIRSTNAME",
                    "match": "Full match made on First Name/Given Name"
                },
                {
                    "record": "CRD4-LASTNAME",
                    "match": "Full match made on Last Name/Surname"
                },
                {
                    "record": "CRD4-ADDRESS",
                    "match": "Full match made on Address Elements provided in Address Lines"
                },
                {
                    "record": "CRD4-HOUSENUMBER",
                    "match": "Full match made on House Number/Street Number"
                },
                {
                    "record": "CRD4-THOROUGHFARE",
                    "match": "Full match made on Street/Thoroughfare"
                },
                {
                    "record": "CRD4-LOCALITY",
                    "match": "Full match made on City/Locality"
                },
                {
                    "record": "CRD4-POSTALCODE",
                    "match": "Full match made on Postal Code/Zip Code"
                },
                {
                    "record": "CRD4-DATEOFBIRTH",
                    "match": "Full match made on Date of Birth"
                },
                {
                    "record": "CRD4-DAYOFBIRTH",
                    "match": "Full match made on Day of Birth"
                },
                {
                    "record": "CRD4-MONTHOFBIRTH",
                    "match": "Full match made on Month of Birth"
                },
                {
                    "record": "CRD4-YEAROFBIRTH",
                    "match": "Full match made on Year of Birth"
                }
            ]
        }
    ]
}

Getting Started

Essentials

Identity Verification

Identity Verification - Detailed Documentation

API Playground:

Endpoints Overview

Authentication

API Base URL

Production:

Sandbox:

1. Verify Identity

Endpoint

Description

Required Headers

Request Body Parameters

Response Structure

Response Codes

Global Result Table

Example Request

Example Response

​Identity Verification - Detailed Documentation

​API Playground:

​Endpoints Overview

​Authentication

​API Base URL

​Production:

​Sandbox:

​1. Verify Identity

​Endpoint

​Description

​Required Headers

​Request Body Parameters

​Response Structure

​Response Codes

​Global Result Table

​Example Request

​Example Response

Identity Verification - Detailed Documentation

API Playground:

Endpoints Overview

Authentication

API Base URL

Production:

Sandbox:

1. Verify Identity

Endpoint

Description

Required Headers

Request Body Parameters

Response Structure

Response Codes

Global Result Table

Example Request

Example Response