API Reference

WorldID

Introduction

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.

Procedure

The procedure is simple and consists of the following steps:

Acquiring a session_token,
Redirecting the user's browser to WorldID, and
Checking for a result.

To acquire a session_token the company server has to call the begin/ page and pass the following arguments: company_key and flags. The page like other pages can be called using HTTP GET or POST method. The parameters can be passed in a query string or as a URL-encoded form data or as a request body containing a JSON document. The flags parameter is an object containing the details about the identification process. 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>

}

Steps object provides the description of the flow of the identification process. Questionnaire is provided as the step in the flow. Steps array is passed along with the company_key and flags.

{

    "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. 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 record 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 invalid session it returns SESSION_INVALID.

WorldID also provides other API methods under a base URL . See below.

Accessing Data

The following methods are available for accessing images and videos related to a session:

result/card-front/ - Retrieves the image of the front side of a card
result/card-back/ - Retrieves the image of the back side of a card
result/passport/ - Retrieves the passport photo page image
result/face/ - Retrieves the face image
result/face-video/ - Retrieves the face motion video
result/face-document/ - Retrieves the image of a face with a document
result/General-document/ - Retrieves the general document photo page image
list-session-activities - Provides a list of the session's activities
get-session-statistical-summary - Retrieves the statistical summary of a session
get-session-main-document-face-photo - Obtains the face photo from the main document
search-screening-person - Searches for a person in the screening databases
get-screening-person-details - Retrieves details about a person from the screening databases
get-video-call-shots - Obtains the video call shots

Processing an Image

The methods below are for manually processing an image:

card/front/ - ID card front side
card/back/ - ID card back side
license/front/ - Driver license front side
license/back/ - Driver license back side
residence/front/ - Residence permit back side
residence/back/ - Residence permit front side
passport/ - Passport photo page

Each of these methods return either a string containing an error code, or an object containing the information read. The number of object fields may change depending on whatever can be read from the image.

Extra Processing

Listed below are various methods of image processing:

compare-faces/ - Get similarity score for two faces

Each of these methods return either a string containing an error code, or an object containing the information read. The number of object fields may change depending on whatever can be read from the image.

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.