Identity Data Verification (IDV)
IDV module enables convenient ID validation, safeguarding your customer data.
Before you start issuing IDV requests, you can choose between the following two options based on your preference:
- IDV with UI elements: Build will handle the arrangement of elements for you. You only need to design the UI elements based on the JSON data returned by Build.
- IDV without UI elements.
IDV with UI elements
Form and Related Concepts:
To facilitate UI design and meet various form and validation requirements, we organize a form using hierarchical elements. A Form typically includes one or more Pages, a Page includes one or more Sections, and a Section includes multiple Questions.
Concept of Question:
A Question represents an item that needs to be answered. It has properties such as encryption and whether it allows multiple selections. It can be of types like integer, float, or string, but only the string value needs to be submitted.
Translation:
Translations are used to identify and explain the related elements.
Business Guidance:
- Start by creating a FormInstance instance.
- Retrieve the details of the FormInstance using /v1/idv/form-inst-detail to get the list of questions to be answered.
- You can fill out the form by using the AnswerId.
- Alternatively, you can fill out the form using QuestionField, which is the unique identifier for a Question. During the form filling process, you can check the form completion status using /v1/idv/form-inst-detail. Once the form is filled, submit it using /v1/idv/submit-form and check the final status using /v1/idv/form-inst-status.
IDV without UI elements
If your application doesnot envolve complicated UI, then you can follow these steps to do IDV requests.
- Create form instance from the default form,which has the id "ETLPzgJtStg-mf" in the ENV of testing.
curl -X POST {baseUrl}/v1/idv/create-form-instance\
-H 'Content-Type: application/json' \
-d '{
"form_id": "ETLPzgJtStg-mf",
"uid": "1698974509547507713"
}'
Response:
{
"code": 0,
"msg": "Success",
"data": {
"instance_id": "ETLPzgJtSt7rSUk.mg"
},
"properties": {}
}
- Get information about question fields of the default form and get acknowledge of the questions need to be answered.
curl {baseUrl}/v1/idv/form-fields?form_id=ETLPzgJtStg-mf
Response:
{
"id": "ETLPzgJtStg-mf",
"fields": [
{
"field_name": "city",
"is_optional": 0
},
{
"field_name": "state",
"is_optional": 0
},
{
"field_name": "postcode",
"is_optional": 0
},
{
"field_name": "address2",
"is_optional": 1
},
{
"field_name": "address1",
"is_optional": 0
},
{
"field_name": "id_card_no",
"is_optional": 0
},
{
"field_name": "day_of_birth",
"is_optional": 0
},
{
"field_name": "mobile",
"is_optional": 0
},
{
"field_name": "gender",
"is_optional": 0
},
{
"field_name": "country_code",
"is_optional": 0
},
{
"field_name": "last_name",
"is_optional": 0
},
{
"field_name": "mid_name",
"is_optional": 1
},
{
"field_name": "first_name",
"is_optional": 0
},
{
"field_name": "email",
"is_optional": 0
}
]
}
- Fill the questions of a form instance
curl -X POST {baseUrl}/v1/idv/fill-questions-by-field
-d'{
"form_inst_id": "ETLPzgJtSt7rSUk.mg",
"answer_list": [
{
"field_name": "email",
"txt": "james.wang@bano.rocks"
},
{
"field_name": "mid_name",
"txt": ""
},
{
"field_name": "country_code",
"txt": "CN"
},
{
"field_name": "address1",
"txt": "Building 123,Chaoyang North Rd"
},
{
"field_name": "address2",
"txt": "Room 701"
},
{
"field_name": "state",
"txt": "Beijing"
},
{
"field_name": "city",
"txt": "Beijing"
},
{
"field_name": "first_name",
"txt": "旭"
},
{
"field_name": "last_name",
"txt": "王"
},
{
"field_name": "postcode",
"txt": "100123"
},
{
"field_name": "id_card_no",
"txt": "420582198310257933"
},
{
"field_name": "day_of_birth",
"txt": "1983-10-25"
},
{
"field_name": "mobile",
"txt": "+86-13301268283"
},
{
"field_name": "gender",
"txt": "Male"
}
]
}'
- Submit form instance for review
curl {baseUrl}/v1/idv/submit-form?formInstId=ETLPzgJtSt7rSUk.mg
- Query form instance status
curl {baseUrl}/v1/idv/form-inst-status?form_inst_id=ETLPzgJtSt7rSUk.mg
Response:
{
"code": 0,
"msg": "Success",
"data": {
"form_inst_id": "ETLPzgJtSt7rSUk.mg",
"status": "VALID",
"message": "Success",
"filled_answers": [
{
"id": "ETLPzgEsTDwQigr5",
"question_field": "email",
"status": "FILLED"
},
{
"id": "ETLPzgEsTDwQigr4",
"question_field": "first_name",
"status": "FILLED"
},
{
"id": "ETLPzgEsTDwQigrc",
"question_field": "mid_name",
"status": "FILLED"
},
{
"id": "ETLPzgEsTDwQigq_",
"question_field": "last_name",
"status": "FILLED"
},
{
"id": "ETLPzgEsTDwQigq-",
"question_field": "country_code",
"status": "FILLED"
},
{
"id": "ETLPzgEsTDwQigq.",
"question_field": "gender",
"status": "FILLED"
},
{
"id": "ETLPzgEsTDwQigq9",
"question_field": "mobile",
"status": "FILLED"
},
{
"id": "ETLPzgEsTDwQigqo",
"question_field": "day_of_birth",
"status": "FILLED"
},
{
"id": "ETLPzgEsTDwQigqn",
"question_field": "id_card_no",
"status": "FILLED"
},
{
"id": "ETLPzgEsTDwQigqm",
"question_field": "address1",
"status": "FILLED"
},
{
"id": "ETLPzgEsTDwQigq5",
"question_field": "address2",
"status": "FILLED"
},
{
"id": "ETLPzgEsTDwQigq4",
"question_field": "postcode",
"status": "FILLED"
},
{
"id": "ETLPzgEsTDwQigqc",
"question_field": "state",
"status": "FILLED"
},
{
"id": "ETLPzgEsTDwQigp_",
"question_field": "city",
"status": "FILLED"
}
],
"empty_answers": [],
"success_answers": [],
"failed_answers": []
},
"properties": {}
}
List available forms
To list all the available forms, call /v1/idv/form-list.
Check the webhook for form validations
After validation of form instances, customers will receive notifications of type "idv_validation_status" in webhook
Appendix
Form instance status
PENDING_INITIALIZATION - The IDV process is in the initialization stage.
AWAITING_SUBMISSION - IDV details are ready to be submitted.
SUBMITTED_FOR_REVIEW - IDV details have been submitted and are awaiting review.
UNDER_REVIEW - IDV details are currently under review.
VERIFIED - IDV details have been verified.
REJECTED - IDV details have been rejected.