Table of Contents

1 Introduction
2 Authentication
3 Environments
4 Endpoints
- 4.1 Headers
- 4.2 Request body
- 4.3 Response
5 Code Examples
- 5.1 Example request
- 5.2 Example response
6 Error Handling
7 Billing

Introduction

This API is a natural person validation service that enables businesses to validate the personal information of individuals using their personal identification data. This documentation explains the features, benefits, and available endpoints of this API.

Authentication

To access the API, an access token must be included in the request. You can obtain an access token by following the instructions provided here.

The API has one scope: registries_naturalentityvalidation_api, which provides access to the natural person validation endpoint.

Environments

The API has two environments: Sandbox and Prod. The base URLs and the available scopes for each environment are provided in the table below. Additionally, the Swagger URL for the API is also provided.

Environment	Swagger URL	Base URL	Scopes

Environment

Swagger URL

Base URL

Scopes

Sandbox

https://sandbox-registries.ondato.com/swagger/index.html

https://sandbox-registries.ondato.com

registries_naturalentityvalidation_api

Prod

https://registries.ondato.com/swagger/index.html

https://registries.ondato.com

registries_naturalentityvalidation_api

Endpoints

The API has one endpoint: post /v1/natural/natural-entity-validations.

This endpoint returns a match status of the requested person's information based on the parameters provided in the request. The request body includes various fields for validating the personal information of the individual, including name, address, gender, and document information.

Headers

Parameter	Type	Required	Description

Parameter	Type	Required	Description
Correlation-Id	string	no	A unique identifier assigned to the request.
Application-Id	string	yes	Your application Id. Please contact support@ondato.com you don’t have one.
Access token	string	yes	Described in the Authentication part

Request body

Possible request fields differ from country to country.

To find out for possible request fields, please visit this page:

Request parameters for natural entity validation

Field	Type	Description

Field	Type	Description
`source`	string	Source defining in which country and register to perform validation. Possible values are described on the page .
`firstName`	string	The first name of the person whose details need to be validated.
`middleName`	string	The middle name of the person whose details need to be validated.
`lastName`	string	The last name of the person whose details need to be validated.
`dateOfBirth`	string	The date of birth of the person whose details need to be validated. Date format: YYYY-MM-DD format.
`gender`	string	The gender of the person whose details need to be validated. Possible values: `f` `m` Description: f - female m - male
`address`	string	The address of the person whose details need to be validated.
`address1`	string	The address of the person whose details need to be validated.
`address2`	string	The address of the person whose details need to be validated.
`city`	string	The city of the person whose details need to be validated.
`state`	string	The country of the person whose details need to be validated.
`zip`	string	The zip code of the person whose details need to be validated.
`idNum`	string	The document number of the person whose details need to be validated. The document type is described below.
`idType`	string	The type of document of the person whose details need to be validated. Possible enum values: `1` - Passport `2` - National ID `3` - eID `4` - Driver's License `5` - Residence Permit `6` - Aadhaar Number (INDIA only) `7` - TAX Number `8` - SSN
`phone`	string	The phone number of the person whose details need to be validated.
`email`	string	The email of the person whose details need to be validated.
`maritalStatus`	string	The marital status of the person whose details need to be validated. Possible values: `M` - married

Response

The response from this API is an object containing the matched fields from the request.

The matched fields can have various results such as "Match," "Partial Match," "No Match," "No Data," and "No Input."

Field	Type	Description

Field	Type	Description
`data`	object	An object containing the fields that were matched in the request.
data.`firstName`	object	An object containing the result of the matching process for the first name.
data.firstName.`result`	string	The result of the matching process for the first name. Possible values: Match Partial Match No Match
data.`middleName`	object	An object containing the result of the matching process for the middle name.
data.middleName.`result`	string	The result of the matching process for the middle name. Possible values: Match Partial Match No Match No Data No Input
data.`lastName`	object	An object containing the result of the matching process for the last name.
data.lastName.`result`	string	The result of the matching process for the last name. Possible values: Match Partial Match No Match
data.`dateOfBirth`	object	An object containing the result of the matching process for the date of birth.
data.dateOfBirth.`result`	string	The result of the matching process for the date of birth. Possible values: Match Partial Match No Match No Data No Input
data.`gender`	object	An object containing the result of the matching process for the gender.
data.gender.`result`	string	The result of the matching process for the gender. Possible values: Match Partial Match No Match No Data No Input
data.`address`	object	An object containing the result of the matching process for the address.
data.address.`result`	string	The result of the matching process for the address. Possible values: Match Partial Match No Match No Data No Input
data.`address1`	object	An object containing the result of the matching process for the first line of the address.
data.address1.`result`	string	The result of the matching process for the first line of the address. Possible values: Match Partial Match No Match No Data No Input
data.`address2`	object	An object containing the result of the matching process for the second line of the address.
data.address2.`result`	string	The result of the matching process for the second line of the address. Possible values: Match Partial Match No Match No Data No Input
data.`city`	object	An object containing the result of the matching process for the city.
data.city.`result`	string	The result of the matching process for the city. Possible values: Match Partial Match No Match No Data No Input
data.`state`	object	An object containing the result of the matching process for the state.
data.state.`result`	string	The result of the matching process for the state. Possible values: Match Partial Match No Match No Data No Input
data.`zip`	object	An object containing the result of the matching process for the zip code.
data.zip.`result`	string	The result of the matching process for the zip code. Possible values: Match Partial Match No Match No Data No Input
data.`idNum`	object	An object containing the result of the matching process for the ID number.
data.idNum.`result`	string	The result of the matching process for the ID number. Possible values: Match Partial Match No Match No Data No Input
data.`phone`	object	An object containing the result of the matching process for the phone number.
data.phone.`result`	string	The result of the matching process for the phone number. Possible values: Match Partial Match No Match No Data No Input
data.`email`	object	An object containing the result of the matching process for the email address.
data.email.`result`	string	The result of the matching process for the email address. Possible values: Match Partial Match No Match No Data No Input
data.`maritalStatus`	object	An object containing the result of the matching process for the marital status.
data.maritalStatus.`result`	string	The result of the matching process for the marital status. Possible values: Match Partial Match No Match

Code Examples

Example request

{
  "source": "ID5",
  "firstName": "CLFNAME",
  "middleName": "CLLNAME",
  "lastName": "CLMNAME",
  "dateOfBirth": "1995-08-01",
  "address": "CLADDRESS",
  "idNum": "8888888888888888",
  "idType": "2"
}

Example response

{
  "data": {
    "firstName": {
      "result": "Match"
    },
    "middleName": {
      "result": "Match"
    },
    "lastName": {
      "result": "Match"
    },
    "dateOfBirth": {
      "result": "Match"
    },
    "address": {
      "result": "Partial Match"
    },
    "idNum": {
      "result": "Match"
    }
  }
}

Error Handling

The API returns error responses in the following formats:

400 Bad Request

{
  "reason": "ValidationFailed",
  "message": "The request is invalid.",
  "params": {
    "additionalProp1": [
      {
        "reason": "Required",
        "message": "Property should not be empty."
      }
    ],
    "additionalProp2": [
      {
        "reason": "Required",
        "message": "Property should not be empty."
      }
    ],
    "additionalProp3": [
      {
        "reason": "Required",
        "message": "Property should not be empty."
      }
    ]
  }
}

Ondato

Natural entity data validation