First Steps
WorldID is a service for checking human identity and liveness over the Internet. The manual assumes the integrating company (later "the company") has a web server (later "the company server") running at example.com and has a company_key. The company_key is a password for communicating from the company server to the WorldID server. As an option for additional security, companies can use HMAC Authorization. The secret_key is the encryption key used with HMAC (which is optional).
Process
The procedure is simple and consists of the following steps:
- Acquiring a
session_token, - Redirecting the user's browser to begin verification, and
- Checking for a result.
Session Creation
To acquire a session_token the company server has to call the verifications/ page and pass the following arguments: company_keyand flags.
The page like other pages can be called using HTTP POST method.
You can either pass Flags parameters or a Configuration ID.
Flags
The flags parameter is an object containing the details about the identification process. The parameters can be passed either in a query string as a URL-encoded form data or as a request body containing a JSON document.
Currently, it may have the following format:
{
// Where to return after the identification.
// Omitting this means you are embedding in an iframe.
"return_url": <String>,
// Whether or not to check liveness of the user. Default: false
"liveness": <Boolean>,
// User interface language. Possible values: "en", "es", "ka", "ru", "uk". Default: "en"
"language": <String>,
// A list of allowed documents.
// Possible item values: "id", "passport", "driver_license",
// "residence_license". Default: everything
"document_types": <Array>,
// Limit document scanning by country codes.
// Possible item values: "USA", "DEU", "ITA", etc.
"document_countries": <Array>,
// A list of allowed general documents.
// Works only if allow_general_document_capture or allow_general_document_upload is set.
// Possible item values: "bank_statement", "utility_bill",
"general_document_types": <Array>,
// Allow capture of general document.
// Default: false,
"allow_general_document_capture": <Boolean>,
// Allow upload of general document.
// Default: false,
"allow_general_document_upload": <Boolean>,
// Skip agreement step completely
// Default: false
"skip_agreement": <Boolean>,
// Skip document scanning step completely
// Default: false
"skip_document": <Boolean>,
// Skip face scanning step completely
// Default: false
"skip_face": <Boolean>,
// Allow upload of an image as a document
// Default: false
"allow_document_upload": <Boolean>,
// Allow person to upload a selfie
// Default: false
"allow_face_upload": <Boolean>,
// Allow a person to upload an image of them holding a document in hand
// Default: false
"allow_face_doc_upload": <Boolean>,
// Require a person to hold a document in a hand
// Default: false
"require_face_document": <Boolean>,
// Disable document capture with camera
// Default: false
"disable_document_capture": <Boolean>,
// Skip personal computer, mac browser session and display QR code to continue on mobile device
// Default: false
"skip_desktop": <Boolean>,
// Instead of capturing passport's single page, capture double
// Default: false
"capture_double_page_passport": <Boolean>
// Enable email verification step
// Default: false
"require_email_check": <Boolean>
// Enable email collection step
// Default: false
"require_email": <Boolean>
// Enable phone number verification step
// Default: false
"require_phone_number_check": <Boolean>
// Enable phone number collection step
// Default: false
"require_phone_number": <Boolean>
// Provide custom url in qr code when camera is not present or access is restricted
"switch_device_url": <String>
// Restrict sharing of the session URL to continue from another browser.
// Note: If this flag is true, when camera permission is denied or camera is inaccessible
// the QR code will not appear unless switch_device_url flag is present.
// Default: false
"restrict_url_sharing": <Boolean>
}Configuration ID
Following the company_key you may pass a config_id instead of flags.
This simplifies the API setup since all configuration steps and thresholds are created in the back office of the Identity Verification Solution. Once the configuration is created an id will be provided and can be passed in the API requests.
Example (including your company key):
{
"company_key": Your company key here
"config_id": Your configuration ID here
}
Following thecompany_keyonlyflagsorconfig_idcan be passed, but never both.
Questionnaire
Steps object describes the flow of the identification process. The questionnaire is provided as the step in the flow. The steps array is passed along with the company_key and flags or config_id.
Example of the questionnaire steps below:
{
"steps": [{
// The type of the step may be either operator-questionnaire or client-questionnaire
"type": <Enum>,
"title": <String, Object>,
"key": <String>,
// Step description supports Markdown formatting
"description" : <String, Object>,
"questions": [
{
// The type of the question may be one of the following: boolean, string, options or multiple-choice
"type": <Enum>,
"title": <String, Object>,
"key": <String>,
"mandatory": <Boolean>,
// In case of options or multiple-choice, the following properties are required
"options": [{
"title": <String, Object>,
"key": <String>
}]
}]
}]
}The company server now has to check for a result.
Result Parsing
This is done by calling the result/ page and passing the company_key and the session_token parameters. It returns a JSON document containing all the information about the user.
The document has the following format:
{
// The result of the identification process.
// Possible values:
// * "APPROVED" - The person was acceptable.
// * "REJECTED" - The person was unacceptable.
// * "MANUAL_CHECK" - A person was suspiciously acceptable. Human review required.
// * "DISAGREED_WITH_TERMS" - The person disagreed with terms.
// * "IN_PROGRESS" - The person is undergoing check or has quit the process before completion.
"result": <String>,
// Whether or not the person was considered as live
"live": <Boolean>,
// A number between 0 to 1 of how much
// the person photo matched the one in the document.
// The more the value the more the match.
"similarity": <Number>,
// The document with which the process was fulfilled.
"document_type": <String>,
// List of general documents with which the process was fulfilled.
// Extracted data from proof of address documents will appear here.
"generalDocuments": [{
"documentType": <String>,
"pages": <Array>
}],
// The number of face images.
"num_faces": <Number>,
// An object describing why the session was rejected.
// Can be null.
"reject_reason": {
// The rejection reason code.
"value": <String>,
// A human-readable explanation.
"description": <String>
},
// The structured data extracted from a person document.
// Every member is optional.
"person": {
"local_first_name": <String>,
"local_last_name": <String>,
"first_name": <String>,
"last_name": <String>,
"birthday": <String>,
"birthday_time": <String>,
"age": <Number>,
"birth_place": <String>,
"registration_place": <String>,
"citizenship": <String>,
"nationality": <String>,
"document_number": <String>,
"document_issued": <String>,
"document_expires": <String>,
"document_expires_time": <String>,
"personal_number": <String>,
"authority": <String>,
"issuing_state": <String>,
"sex": <String>,
"mrz_type": <String>,
"status": <String>
},
// Trusted database record.
"trusted_database_record": <Object>,
// If Operator Rejects/Approves the session manually and adds a comment, that comment will be provided here
"result_comment": <String>,
// In case of the session having the questionnaire this object will return array containing answers
"questionnaires": [{
"key": <String>,
"questions": [{
"key": <String>,
"answer": <String, Boolean, Array[String]>
}]
}],
// In case of the session having screening matches this object will return array containing those matches
// You can fetch person details by calling get-screening-person-details with personId that you get in screeningMatches elements
"screeningMatches": [{
"score": <Number>,
"name": <String>,
"personId": <String>,
"reviewStatus": <String>
}],
// The structured data of technical details.
"technicalDetails": {
"remoteAddress": <String>,
"userAgent": <String>,
"countryCode": <String>
}
}Session records can be deleted by calling delete/ page and passing the company_key and the session_token parameters. It returns a JSON document containing all the information about the deleted session. In case of non existing session, it returns SESSION_NOT_FOUND or in case of an invalid session, it returns SESSION_INVALID.
Session Deletion
HMAC Authorization (Optional)
For data integrity and identity, API supports the request check by message authentication code - MAC. It uses the standard HMAC_SHA_256 algorithm to generate code. The symmetric key for hashing is obtained during the generation of the appropriate type of the company_key.
In the case of non-standard request types, the procedure for generating an authorization code is different. In standard cases, the authorization code is the base64 value of the HMAC of the request object - base64(hmac_sha_256(secret_key, request_body)). A multipart request is a non-standard request, the code of which is generated iteratively. The hashing key of each iteration is the binary value of the authorization code obtained during the previous interaction. base64(hmac_sha_256(hmac_sha_256(secret_key, part_1), part_2))). In the multipart request, it’s important to sort parts of it by type, firstly there should be placed text data, and then file type data.
The generated authorization code should be added in the request header as follows:
Authorization: signature="{code}"Like a request, the response contains an authorization header as well - Authorization: signature="base64(hmac_sha_256(secret_key, response_body)), the authenticity of which should be checked by the caller. An unsuccessful request does not include an authorization header.