Identity Verification (defined data sources) is an identity verification service designed to verify individuals' identities. This service is seamlessly integrated into the ZignSec API, enabling easy and secure identity checks. By submitting personal information, and providing consent if needed, the API verifies a user's identity using one or more defined data sources specified by the user. It then generates a detailed report, which includes a reporting reference, a unique identifier for the report, and a match status indicating the degree of correspondence between the user's provided information and the database. Offering a reliable and convenient solution, this service is highly effective for businesses and organizations requiring identity verification.
----
## API Overview
---
## Core Functionalities
### Environments
We provide the following environments for your use:
· **Test (TEST) Environment:** `https://test-gateway.zignsec.com/core/api/`
· **Production (PROD) Environment:** `https://gateway.zignsec.com/core/api/`
### Authentication
Each request to our API should be authenticated by sending your subscription key in the “Authorization” header. Our support creates subscription keys for you (a pair for each environment), and it’s highly recommended to regularly rotate the keys (currently it’s done by sending a support request, but please let us know if you’d like to automate it).
If you need different configurations it’s possible to register multiple tenants and configure them differently.
### REST API
#### Headers
| Header | Description | Required |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| Authorization | This header parameter is the subscription key you received from ZignSec during the registration process. Example: Authorization: 123456add0cff22873c428e987654321 | Yes |
| Content-Type | Specifies the media type of the request body data. Set to application/json if JSON object. | Yes |
#### OpenAPI documentation
##### Live documentation
- [Swagger UI (zignsec.com)](https://test-gateway.zignsec.com/#/Register%20Checks/postIdentityCheckIdp)
---
#### API Endpoints
##### Identity Verification check
**Endpoint**: POST /sessions/identity_check/idp
**Description:** Initiates an identity verification process through a specified identity provider.
##### Get session details
**Endpoint**: GET /sessions/{id}
**Description:** This API endpoint retrieves the status and details of an Identity Verification, enabling you to review the results of a previously initiated verification request.
##### Webhooks
Every time session state changed, we send a webhook (see our common Webhook documentation), with the structure described in the live documentation.
### Request and Response examples with parameter lists
#### Request sample for Peru National ID
```bash
curl --location 'https://test-gateway.zignsec.com/core/api/sessions/identity_check/idp' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Your-Subscription-key' \
--data '{
"metadata": {
"address_element1": "",
"address_element2": "",
"address_element3": "",
"address_element4": "",
"address_element5": "",
"client_reference": "",
"consent_obtained": {
"Peru_National_ID": true
},
"country_code": "PE",
"date_of_birth": "1993-11-23",
"first_name": "ANDY",
"identity_variables": {
"nationalIdNo": "72953609"
},
"last_name": "ZAPATA DELGADO",
"middle_name": "WILBER",
"service": [
"Peru National ID"
]
},
"relay_state": "TestMessage",
"webhook": "https://webhook.site/"
}'
```
#### Request parameters:
**Note**! Request parameters can change from country to another and from a document to another one.
| **Parameter** | **Type** | **Description** | **Required** |
| ---------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| metadata | Object | | yes |
| address_element1, 2, 3 | String | Address of subject, optional depending on service called | Yes / No |
| client_reference | String | | No |
| consent_obtained | Boolean | Asking the end-user for consent is required depending on country and type of document | Yes / No |
| country_code | string | ISO code, example: AU | No |
| date_of_birth | string | Date Of Birth using the international format (YYYY-MM-DD) | Yes |
| first_name | string | First name | Yes |
| identity_variables | object | Identity Variables such as:<br><br>nationalIDNo, birth_certificate_number, birth_registration_date, birth_registration_no, birth_registration_state<br><br>Input depending on service called | yes |
| last_name | string | Last Name | Yes |
| middle_name | string | Middle Name | No |
| service | Table of string | Datasource(s) you are connecting too | Yes |
| tenant | string | Tenant if needed to override a default one (it should be configured by support before usage) | No |
| relay_state | string | Optional Custom Parameter to be included in webhook calls | No |
| webhook | string | Webhook URL where your backend will receive session events. | No |
#### Response Result
#### Sample GET Request
```bash
curl -X 'GET' \
'https://test-gateway.zignsec.com/core/api/sessions/f0254a90-da3f-440e-81fd-3c95d3577afc' \
-H 'accept: application/json' \
-H 'authorization: Your-Access-key'
```
Used to retrieve status and result response of the analysis. Simply pass the sessionID with the authorization token. (In example above sessionID is: f0254a90-da3f-440e-81fd-3c95d3577afc)
#### Response sample for Peru National ID:
```json
{
"data": {
"errors": [],
"id": "c882d945-6327-495e-94a5-1cf785b945a2",
"result": {
"clientReference": "c882d945-6327-495e-94a5-1cf785b945a2",
"countryCode": "Peru",
"matchStatus": "Full Match 1+1 Verification",
"remarks": [],
"reportingReference": "DZ-50c513db-dd82-4fe0-aef1-c53411f7fd66",
"safeHarbour": "false",
"searchErrorMessage": "",
"searchStatus": "Successful",
"serviceResponses": {
"peru National ID": {
"addressMatchScore": "N/A",
"errorMessage": "",
"identityVerified": true,
"nameMatchScore": "1.000",
"returnedData": {},
"safeHarbourScore": "M2",
"sourceStatus": "Successful",
"status": 0,
"verifications": {
"dateOfBirth": true,
"firstName": true,
"lastName": true,
"middleName": true,
"nationalIDNo": true
}
}
}
},
"status": "Finished"
}
}
```
#### Response parameters:
|**Parameter**|**Description**|
|---|---|
|data|Data from Datasource|
|---|---|
|errors|Error code, description and details|
|id|A unique session identifier generated for each workflow instance|
|result|Result of the input’s check including clientReference, countryCode, matchStatus, remarks, reportingReference, safeHarbour, searchErrorMessage, searchStatus, serviceResponses …etc<br><br>See separate table bellow|
|status|Shows present state of session.<br><br>Enum: [ Created, Finished, Failed ]|
#### Result node
|**Parameter**|**Values returned**|**Description**|
|---|---|---|
|“countryCode”|Country code, example:<br><br>“Australia”|Directs the request to search data sources of the input country code. This is provided by the client in the API request.|
|“clientReference”|Example: “ c882d945-6327-495e-94a5-1cf785b945a2”|Reference number same as session identifier|
|“reportingReference”|Example: DZ-745a7f0b-c47f-47f1-8115-99e39cff2c27|Reference ID generated per API request made. Number is unique per API request, is used for support enquiries.|
|“matchStatus”|“Full Match 1+1 Verification”|Full Match 1+1 determined when identity verified = true in 1 source/service|
|“Full Match 2+2 Verification”|Full Match 2+2 determined when identity verified = true in =>2 sources/services|
|“No Match”|No Match when neither of the above two rules are determined.|
|”remarks”|list|Remarks about the session|
|“searchErrorMessage”|"searchErrorMessage": "The following data source requests failed validation: Australia Residential"|Used to flag if a service has failed a pre-validation check|
|“safeHarbour”|True|The **Safe Harbour Matching Score** (i.e.. "safeHarbourScore") is determined by the following logic:<br><br>- M1 = Match on full name, address and DOB<br>- M2 = Match on full name and DOB<br>- N1 = Match on full name and address<br>- None = No match|
|False|Safe Harbour Flag is set to False (i.e.. "safeHarbour" = False) if a True Match is not returned|
|“searchStatus”|Successful|“Successful” - the request is submitted to at least one data source<br><br>“Not Successful” - a pre-validation error has ocurred (ie incorrect syntax used)<br><br>or source not operational at this time and has not submitted the request for verification on behalf of the client.|
|“serviceResponses”|For example: “Australian Residential”|The service name of the data sources used for verification. The child parameters of this attribute will contain the safe harbour score and element matching.|
#### Service Responses
|**Parameter**|**Values returned**|**Description**|
|---|---|---|
|“status”|0,1,2,3|0 when All input elements matched and identityVerified = ‘true’<br><br>1 when Some input elements matched and identityVerified = ‘true’<br><br>2 when identityVerified = ‘false’<br><br>3 when an error has occurred and the identity can neither be verified or not verified|
|“sourceStatus”|“successful”<br><br>“unsuccessful”|Indicates if the API query successfully reached the data source|
|“errorMessage”|too many to list|Returns an error message indicating what the error was - usually in conjunction with “status”: 3, however can sometimes occur with “status”: 2 as per DVS enhanced messaging:<br><br>"errorMessage": "Some or all of the supplied details do not match the Issuer record. GivenName: Given name does not match. "|
|“identityVerified”|true|Flag will confirm identity verification, refer to additional field responses, i.e. “nameMatchScore”|
||false|Refer above|
|“safeHarbourScore”|Refer to safe harbour table|Score represents which combination of elements have been verified. Name and address match score threshold must be met for a safe harbour score to be returned.|
|“nameMatchScore”|A score between 0-1|Indicates the exactness of the match against the data source with score of 1 representing exact match. Acceptable match thresholds can be set in for client account preferences to accept fuzzy matching for example setting an acceptable threshold of 0.8 or greater.|
|“addressMatchScore”|A score between 0-1|Indicates the exactness of the match against the data source with score of 1 representing exact match. Acceptable match thresholds can be set in for client account preferences to accept fuzzy matching for example setting an acceptable threshold of 0.8 or greater|
|“verifications”|For example: "dateOfBirth": true, "firstName": true, "lastName": true, "middleName": true, "nationalIDNo": true|Contains element level verification on details supplied for the source. Only elements provided in the request from the client will be present in the response. For example if no DOB provided in the request then there will be no DOB attribute in the response.|
### Scoring
Electronic Verification Safe Harbour Obligations
To come within Safe Harbour, reporting entities must:
- Verify the person’s name from at least two reliable and independent electronic sources; and
- Verify the person’s date of birth from at least one reliable and independent electronic source and verify the person’s address from at least one reliable and independent electronic source or verify the person’s address from at least two reliable and independent electronic sources or verify the person’s date of birth from at least two reliable and independent electronic sources;
The Safe Harbour Matching Score (ie. “safeHarbourScore”) is determined by the following logic:
- M1 = Match on full name, address and DOB
- M2 = Match on full name and DOB
- N1 = Match on full name and address
- None = No match
When combining the selected data source(s) in a composite query, the Safe Harbour Flag is set to True (ie. “safeHarbour” = True) if any of the following conditions are satisfied:
- 2 or more data sources return a Safe Harbour Matching Score of M1 or
- 1 data source returns a Safe Harbour Matching Score of M1 AND 1 data source returns a Safe Harbour Matching Score of M2 or
- 1 data source returns a Safe Harbour Matching Score of M1 AND 1 data source returns a Safe Harbour Matching Score of N1 or
- 1 data source returns a Safe Harbour Matching Score of M2 AND 1 data source returns a Safe Harbour Matching Score of N1
In addition for Australian data sources only:
- 2 or more data sources return a Safe Harbour Matching Score of M2
Otherwise, the Safe Harbour Flag is set to False (ie. “safeHarbour” = False)
The Enhanced Safe Harbour is an alternate scoring logic that can be applied to ID Verifications that use an ID Number as one of their inputs.
The Enhanced Safe Harbour Matching Score is determined by the following logic:
- L1= Match on full name, address, DOB, ID number
- L2 =Match on full name, DOB, ID number
- L3= Match on full name, ID number
- L4= Match on full name, address, ID number
- L5= Match on ID number
This score is only returned in the response field if the “Enhanced Safe Harbour” preference set to True (i.e. “Enhanced SafeHarbour”: “true”)
Name Match Scoring
The Australian Residential service provides a score based on the Name Matching of the verification:
A = Full match [Full Name Match]
A1 = Full match [First Name and Surname Matched, Middle Name Mismatched]
A2 = Full match [Using Nicknames]
B = Good match [First Name, Initial and Surname Matched]
C = Soft match [Surname Match]
X = Wrong [No Match / Other Surname in Directory]
Address Match Scoring
The Australian Residential service provides a score based on the Address Matching of the verification:
0 = Full match [Full Address Match]
1 = Soft Locality match [Full Address Match with Error in Suburb/Postcode]
2 = Soft Number match [Full Address Match with Error in Unit Number]
2A = Soft Number match [Full Address Match with Error in House Suffix/Prefix]
3 = Street Number [Full Address Match with Error in Street Number]
Z = Address mismatch [No Matches]
### Coverage
Explore coverage list below:
|**Country**|**Country**|
|---|---|
|Argentina|Kenya|
|Australia|Malaysia|
|Austria|Mexico|
|Bangladesh|Morocco|
|Belgium|Netherlands|
|Brazil|New Zealand|
|Cambodia|Nigeria|
|Canada|Norway|
|Chile|Peru|
|China|Philippines|
|Colombia|Poland|
|Czech Republic|Singapore|
|Denmark|Slovakia|
|Finland|South Africa|
|France|South Korea|
|Germany|Spain|
|Greece|Sweden|
|Hong Kong|Switzerland|
|India|Thailand|
|Indonesia|United Kingdom|
|Ireland|United States of America|
|Italy||
## How to test
Please check the available test Data on [this link](https://25357801.fs1.hubspotusercontent-eu1.net/hubfs/25357801/Marketing%20and%20IR/Other/Test%20Data-%20Registercheck_IDV.xlsx). If you do not find the requested country please reach out to support team and they will help you out. You find test Data below for Kenya and Nigeria.
Test Data for Nigerian National ID
```json
"metadata": {
"address_element1": "",
"address_element2": "",
"address_element3": "",
"address_element4": "",
"address_element5": "",
"client_reference": "Test_0001",
"consent_obtained": {
"Nigeria National ID": true
},
"country_code": "NG",
"date_of_birth": "1960-10-01",
"first_name": "Bunch",
"identity_variables": {
"nationalIDNo": "JZ426633988976CH"
},
"last_name": "Dillon",
"middle_name": "",
"service": [
"Nigeria National ID"
]
},
```
Test Data for Nigerian Bank verification
```json
"metadata": {
"address_element1": "",
"address_element2": "",
"address_element3": "",
"address_element4": "",
"address_element5": "",
"client_reference": "testabc123",
"consent_obtained": {
"Nigeria Bank Verification": true
},
"country_code": "NG",
"date_of_birth": "1995-07-07",
"first_name": "Bunch",
"identity_variables": {
"bankVerificationNo": "95888168924"
},
"last_name": "Dillon",
"middle_name": "",
"service": [
"Nigeria Bank Verification"
]
},
```
Test Data for Kenya National ID
```json
"metadata": {
"address_element1": "",
"address_element2": "",
"address_element3": "",
"address_element4": "",
"address_element5": "",
"client_reference": "KenyaTest123",
"consent_obtained": {
"Kenya National ID": true
},
"country_code": "KE",
"date_of_birth": "1993-12-04",
"first_name": "Harmon",
"identity_variables": {
"nationalIdNo": "30053078"
},
"last_name": "Okinyo",
"middle_name": "Odhiambo",
"service": [
"Kenya National ID"
]
},
```