API Reference

The API Reference documentation provides detailed information on the available endpoints, request parameters, response formats, and authentication methods for integrating with Identomat.

Session management

begin/ - Session creation

URL:

https://widget.identomat.com/external-api/begin/

Description:

Initiates a new verification session. Sessions can be started using either a predefined configuration (config_id) or by explicitly specifying the steps and flags for a custom flow.

This endpoint now also supports overriding individual steps within a configuration. This allows you to inject dynamic data (e.g., prefill user details like first name and last name) while still using your saved configuration, making the transition to configuration-based setups more flexible.

Parameters:

• company_key (string, required)- The company's secret key.

• parent_session_id (string, optional) – Specifies the parent session ID when creating a child session for multi-participant verification.

with:

• flags (object, optional) – A JSON object containing session customization options.

• steps (array, optional) – Defines the sequence of steps in the identification process.

or:

• config_id (string, optional) - The unique identifier for the session configuration.

Note: If both config_id and steps are provided, the session will use the specified configuration and override only the steps that are explicitly redefined. This is useful for injecting dynamic values like user input into specific steps without rewriting the entire flow.

cURL example:

curl https://widget.identomat.com/external-api/begin/ \
    -F 'company_key=abcd' \
    -F 'flags={some_flags}'

Check all steps examples in Developer guide.

Request parameter examples:

Start default session:

{
  "company_key": "abcd"
}

Start session with flags and steps:

{
  "company_key": "abcd",
  "flags": {},
  "steps": [],
  "parent_session_id": "98aryxvvzwpi4zuasth332ozfucli3l0qx13hisc"
}

Start session with configuration:

{
  "company_key": "abcd",
  "config_id": "62412c096c4b39ba845d4bf2"
}

Start a session using a configuration and override specific steps:

{
    "company_key": "abcd",
    "config_id": "62412c096c4b39ba845d4bf2",
    "steps": [
        {
            "type": "user-questionnaire",
            "key": "agreement",
            "title": {
                "en": "Personal information"
            },
            "questions": [
                {
                    "mandatory": true,
                    "type": "string",
                    "key": "agreement-1",
                    "title": {
                        "en": "Your full name"
                    },
                    "answer": "John Doe"
                }
            ],
            "successButtonTitle": {
                "en": "Continue"
            }
        }
    ]
}

Result examples:

default:

"47fjzxvvzapi4ztasth3c2ozfucli3l0qx13hisc"

result/ - Session results

URL:

https://widget.identomat.com/external-api/result/

Description:

This endpoint allows you to retrieve the result of a verification session. Based on the session ID, the response will return the final decision (approved/rejected), document data, extracted information, and metadata.

Parameters:

• companyKey (string, required) - The company's secret key.

• sessionId (string, required) - The unique identifier of the session.

cURL example:

 curl https://widget.identomat.com/external-api/result/ \
    -F 'company_key={some_company_key}' \
    -F 'session_token={some_session_token}'

Request parameter examples:

{
  "company_key": "abcd",
  "session_token": "defg"
}

Result examples:

sessionApproved:

{
    "result": "approved",
    "similarity": 0.9027283530404249,
    "live": false,
    "document_type": "id",
    "generalDocuments": [
        {
            "pages": [
                {
                    "typeId": "utility-bill",
                    "final": {
                        "street": "Main Street",
                        "state": "California",
                        "city": "Los Angeles",
                        "country": "United States",
                        "postalCode": "90001",
                        "streetNumber": "123",
                        "county": "Los Angeles County",
                        "countryCode": "USA",
                        "documentIssued": "1/15/2025",
                        "documentIssuedTime": "2025-01-15T00:00:00",
                        "authority": "Bank of America, NA",
                        "address": "123 Main St, Los Angeles, CA 90001",
                        "formattedAddress": "123 Main St, Los Angeles, CA 90001, USA",
                        "latitude": 34.052235,
                        "longitude": -118.243683,
                        "fullName": "John Doe",
                        "firstName": "John",
                        "lastName": "Doe",
                        "permanent": null
                    },
                    "documentPages": [
                        {
                            "pageNumber": 1
                        }
                    ],
                    "pageNumber": 1,
                    "statuses": []
                }
            ],
            "documentType": "UTILITY_BILL",
            "permanent": null,
            "typeId": "utility_bill"
        }
    ],
    "reject_reason": {
        "value": "",
        "description": ""
    },
    "result_comment": "",
    "name": "John Doe",
    "face_images": 1,
    "id_card_front": {
        "Given_Names_en_US": "John",
        "Surname_en_US": "Doe",
        "citizenship": "USA",
        "Sex_en_US": "M",
        "Personal_Number_en_US": "123456789",
        "Date_of_Birth_en_US": "1/8/1980",
        "Date_of_Expiry_en_US": "8/9/2025",
        "Document_Number_en_US": "AB1234567",
        "Issuing_State_Code_en_US": "USA",
        "Date_of_Birth_ISO": "1980-01-08T00:00:00.000Z",
        "Date_of_Expiry_ISO": "2025-08-09T00:00:00.000Z"
    },
    "id_card_back": {
        "Date_of_Issue_en_US": "6/28/2021",
        "Issuing_State_Code_en_US": "USA",
        "Place_of_Birth_en_US": "USA",
        "Date_of_Issued_ISO": "2021-06-28T00:00:00.000Z",
        "Given_Names_en_US": "John",
        "Surname_en_US": "Doe",
        "Nationality_Code_en_US": "USA",
        "Sex_en_US": "M",
        "Personal_Number_en_US": "123456789",
        "Date_of_Birth_en_US": "1/8/1980",
        "Date_of_Expiry_en_US": "6/28/2028",
        "Document_Number_en_US": "AB0002261",
        "Nationality_en_US": "USA",
        "Date_of_Birth_ISO": "1980-01-08T00:00:00.000Z",
        "Date_of_Expiry_ISO": "2028-06-28T00:00:00.000Z",
        "mrz": "IDUSAAB0002261938001085718<<<<\n8001081M2806288USA<<<<<<<<<<<1\nDOE<<JOHN<<<<<<<<<<<<<<<<<<<"
    },
    "suggested": {},
    "person": {
        "email": "[e-mail]",
        "phoneNumber": "[phone]",
        "first_name": "John",
        "last_name": "Doe",
        "birthday": "1/8/1980",
        "birthday_time": "1980-01-08T00:00:00.000Z",
        "age": 45,
        "citizenship": "USA",
        "document_number": "AB0002261",
        "document_expires": "6/28/2028",
        "document_expires_time": "2028-06-28T00:00:00.000Z",
        "personal_number": "123456789",
        "issuing_state": "USA",
        "sex": "M",
        "birth_place": "USA",
        "nationality": "USA",
        "document_issued": "6/28/2021",
        "document_issued_time": "2021-06-28T00:00:00.000Z",
        "status": "FIELDS_MATCH",
        "mrz": "IDUSAAB0002261938001085718<<<<\n8001081M2806288USA<<<<<<<<<<<1\nDOE<<JOHN<<<<<<<<<<<<<<<<<<<",
        "address": "2804 Fairway Dr, Cedar Hill, TX 75104, USA"
    },
    "questionnaires": [
        {
            "key": "agreement",
            "questions": [
                {
                    "key": "question1",
                    "answer": "John Doe"
                },
                {
                    "key": "question2",
                    "answer": "option4"
                },
                {
                    "key": "question3",
                    "answer": [
                        "option1",
                        "option2"
                    ]
                },
                {
                    "key": "question5",
                    "answer": 1
                },
                {
                    "key": "question6",
                    "answer": "readOnly answer"
                }
            ]
        }
    ],
    "geolocation": [
        {
            "key": "require_geolocation",
            "latitude": 34.05221168293059,
            "longitude": -118.24393094417908,
            "address": "123 Main St, Los Angeles, CA 90001, USA"
        }
    ],
    "technicalDetails": {
        "remoteAddress": "192.168.1.1",
        "userAgent": "PostmanRuntime/7.37.3",
        "countryCode": "US"
    }
}

sessionRejected:

{
    "result": "rejected",
    "similarity": 0.59931052549619,
    "live": true,
    "document_type": "id",
    "generalDocuments": [
        {
            "pages": [
                {
                    "typeId": "utility-bill",
                    "final": {
                        "street": "Main Street",
                        "state": "California",
                        "city": "Los Angeles",
                        "country": "United States",
                        "postalCode": "90001",
                        "streetNumber": "123",
                        "county": "Los Angeles County",
                        "countryCode": "USA",
                        "documentIssued": "1/15/2025",
                        "documentIssuedTime": "2025-01-15T00:00:00",
                        "authority": "Bank of America, NA",
                        "address": "123 Main St, Los Angeles, CA 90001",
                        "formattedAddress": "123 Main St, Los Angeles, CA 90001, USA",
                        "latitude": 34.052235,
                        "longitude": -118.243683,
                        "fullName": "John Doe",
                        "firstName": "John",
                        "lastName": "Doe",
                        "permanent": null
                    },
                    "documentPages": [
                        {
                            "pageNumber": 1
                        }
                    ],
                    "pageNumber": 1,
                    "statuses": []
                }
            ],
            "documentType": "UTILITY_BILL",
            "permanent": null,
            "typeId": "utility_bill"
        }
    ],
    "reject_reason": {
        "value": "low_similarity",
        "description": "Low similarity"
    },
    "result_comment": "",
    "name": "John Doe",
    "errors": [
        "LOW_SIMILARITY"
    ],
    "face_images": 1,
    "id_card_front": {
        "Given_Names_en_US": "James",
        "Surname_en_US": "Smith",
        "Nationality_Code_en_US": "USA",
        "Sex_en_US": "M",
        "Date_of_Birth_en_US": "1/1/1980",
        "Date_of_Issue_en_US": "5/30/2015",
        "Document_Number_en_US": "A12345678",
        "Nationality_en_US": "USA",
        "Issuing_State_Code_en_US": "USA",
        "Date_of_Birth_ISO": "1980-01-01T00:00:00.000Z",
        "Date_of_Issued_ISO": "2015-05-30T00:00:00.000Z"
    },
    "id_card_back": {
        "Issuing_State_Code_en_US": "USA",
        "Authority_en_US": "Department of State",
        "Given_Names_en_US": "James",
        "Surname_en_US": "Smith",
        "Nationality_Code_en_US": "USA",
        "Sex_en_US": "M",
        "Date_of_Birth_en_US": "1/1/1980",
        "Date_of_Expiry_en_US": "5/30/2025",
        "Document_Number_en_US": "A12345678",
        "Nationality_en_US": "USA",
        "Date_of_Birth_ISO": "1980-01-01T00:00:00.000Z",
        "Date_of_Expiry_ISO": "2025-05-30T00:00:00.000Z",
        "mrz": "I<USA12345678<<<<<<<<<<<<<<<\n8001013M2505309USA<<<<<<<<<<<2\nSMITH<<JAMES<<<<<<<<<<<<<<<<<"
    },
    "suggested": {},
    "person": {
        "email": "[e-mail]",
        "phoneNumber": "[phone]",
        "first_name": "James",
        "last_name": "Smith",
        "birthday": "1/1/1980",
        "birthday_time": "1980-01-01T00:00:00.000Z",
        "age": 45,
        "nationality": "USA",
        "document_number": "A12345678",
        "document_issued": "5/30/2015",
        "document_issued_time": "2015-05-30T00:00:00.000Z",
        "issuing_state": "USA",
        "sex": "M",
        "document_expires": "5/30/2025",
        "document_expires_time": "2025-05-30T00:00:00.000Z",
        "authority": "Department of State",
        "status": "FIELDS_MATCH",
        "mrz": "I<USA12345678<<<<<<<<<<<<<<<\n8001013M2505309USA<<<<<<<<<<<2\nSMITH<<JAMES<<<<<<<<<<<<<<<<<",
        "address": "123 Main St, Los Angeles, CA 90001, USA"
    },
    "questionnaires": [
        {
            "key": "agreement",
            "questions": [
                {
                    "key": "question1",
                    "answer": "John Doe"
                },
                {
                    "key": "question2",
                    "answer": "option4"
                },
                {
                    "key": "question3",
                    "answer": [
                        "option1",
                        "option2"
                    ]
                },
                {
                    "key": "question5",
                    "answer": 1
                },
                {
                    "key": "question6",
                    "answer": "readOnly answer"
                }
            ]
        }
    ],
    "geolocation": [
        {
            "key": "require_geolocation",
            "latitude": 34.05221168293059,
            "longitude": -118.24393094417908,
            "address": "123 Main St, Los Angeles, CA 90001, USA"
        }
    ],
    "technicalDetails": {
        "remoteAddress": "192.168.1.1",
        "userAgent": "PostmanRuntime/7.37.3",
        "countryCode": "US"
    }
}

sessionNotFound:

{
  "argumentError": "session-not-found"
}

delete/ - Session data deletion

URL:

https://widget.identomat.com/external-api/delete/

Description:

This endpoint allows you to permanently delete data related to a specific verification session. This operation is irreversible and should be used with caution. It is typically used to comply with data retention policies or user data deletion requests.

Parameters:

• companyKey (string, required) - The company's secret key.

• sessionId (string, required) - The unique identifier of the session.

cURL example:

curl https://widget.identomat.com/external-api/delete/ \
    -F 'company_key={some_company_key}' \
    -F 'session_token={some_session_token}'

Request parameter examples:

{
  "company_key": "abcd",
  "session_token": "defg"
}

Result examples:

default:

true

sessionNotFound:

{
  "argumentError": "session-not-found"
}

export-session-as-pdf - Export session

URL:

https://external-api.identomat.com/export-session-as-pdf

Description:

This endpoint allows you to export data related to a specific session as a downloadable PDF document. You can choose to include the full session details, screening results, and/or proof of address documents. At least one export option must be set to true.

Parameters:

• companyKey (string, required) - The company's secret key.

• sessionId (string, required) - The unique identifier of the session.

One of the following parameters must be set to true for the operation to proceed:

• exportSession (boolean, optional) – Indicates whether to export the full session data.

• exportScreening (boolean, optional) – Specifies whether to include screening results in the export.

• exportProofOfAddress (boolean, optional) - Determines whether to include proof of address documents in the export.

cURL example:

curl https://external-api.identomat.com/export-session-as-pdf \
    -d '{"companyKey":"abcd","sessionId":"defg"}'

Request parameter examples:

{
  "companyKey": "abcd",
  "sessionId": "defg",
  "exportSession": true,
  "exportScreening": false,
  "exportProofOfAddress": false
}

Result examples:

default:

PDF document of session

wrongParameters:

{
  "argumentError": "wrong-parameters"
}

invalidAccess:

{
  "argumentError": "invalid-access"
}

sessionNotFound:

{
  "argumentError": "session-not-found"
}

Accessing Data and More

The methods below are used to access images and videos associated with a session:

result/card-front/ - Card front side image

URL:

https://widget.identomat.com/external-api/result/card-front/

Description:

This endpoint returns the front image of the identification document submitted during the session.

Parameters:

• company_key (string, required) - The company's secret key.

• session_token (string, required) - The unique identifier of the session.

cURL example:

curl https://widget.identomat.com/external-api/result/card-front/ \
    -F 'company_key={some_company_key}' \
    -F 'session_token={some_session_token}'

Result examples:

default:

Card front side image

sessionNotFound:

{
  "argumentError": "session-not-found"
}

result/card-back/ - Card back side image

URL:

https://widget.identomat.com/external-api/result/card-back/

Description:

This endpoint returns the back image of the identification document submitted during the session.

Parameters:

• company_key (string, required) - The company's secret key.

• session_token (string, required) - The unique identifier of the session.

cURL example:

curl https://widget.identomat.com/external-api/result/card-back/ \
    -F 'company_key={some_company_key}' \
    -F 'session_token={some_session_token}'

Result examples:

default:

Card back side image

sessionNotFound:

{
  "argumentError": "session-not-found"
}

result/passport/ - Passport photo page image

URL:

https://widget.identomat.com/external-api/result/passport/

Description:

This endpoint returns the image of the passport submitted during the session.

Parameters:

• company_key (string, required) - The company's secret key.

• session_token (string, required) - The unique identifier of the session.

cURL example:

curl https://widget.identomat.com/external-api/result/passport/ \
    -F 'company_key={some_company_key}' \
    -F 'session_token={some_session_token}'

Result examples:

default:

Passport image

sessionNotFound:

{
  "argumentError": "session-not-found"
}

result/face/ - Face image

URL:

https://widget.identomat.com/external-api/result/face/

Description:

This endpoint returns the image of the user’s face captured during the verification session.

Parameters:

• company_key (string, required) - The company's secret key.

• session_token (string, required) - The unique identifier of the session.

cURL example:

curl https://widget.identomat.com/external-api/result/face/ \
    -F 'company_key={some_company_key}' \
    -F 'session_token={some_session_token}'

Result examples:

default:

Face image

sessionNotFound:

{
  "argumentError": "session-not-found"
}

result/face-video/ - Face motion video

URL:

https://widget.identomat.com/external-api/result/face-video/

Description:

This endpoint returns the video used during the liveness of the identity verification process.

Parameters:

• company_key (string, required) - The company's secret key.

• session_token (string, required) - The unique identifier of the session.

cURL example:

curl https://widget.identomat.com/external-api/result/face-video/ \
    -F 'company_key={some_company_key}' \
    -F 'session_token={some_session_token}'

Result examples:

default:

Face video

sessionNotFound:

{
  "argumentError": "session-not-found"
}

result/face-document/ - Selfie with ID

URL:

https://widget.identomat.com/external-api/result/face-document/

Description:

This endpoint provides the image where the user holds their ID document next to their face.

Parameters:

• company_key (string, required) - The company's secret key.

• session_token (string, required) - The unique identifier of the session.

cURL example:

curl https://widget.identomat.com/external-api/result/face-document/ \
    -F 'company_key={some_company_key}' \
    -F 'session_token={some_session_token}'

Result examples:

default:

Selfie with ID (image)

sessionNotFound:

{
  "argumentError": "session-not-found"
}

result/general-document/ - Proof of Address image or PDF

URL:

https://widget.identomat.com/external-api/result/general-document/

Description:

This endpoint returns a proof of address document or other general documents submitted during the session, such as a bank statement, utility bill, or driver's license.

Parameters:

• company_key (string, required) - The company's secret key.

• session_token (string, required) - The unique identifier of the session.

• typeId (string, required) – The document type identifier. Valid values include:

  • bank-statement

  • utility-bill

  • vehicle-registration-certificate-front

  • vehicle-registration-certificate-back

  • drivers-license

cURL example:

curl https://widget.identomat.com/external-api/result/general-document/ \
    -F 'company_key={some_company_key}' \
    -F 'session_token={some_session_token}' \
    -F 'typeId={some_typeId}'

Request parameter examples:

{
  "company_key": "abcd",
  "session_token": "defg",
  "typeId": "bank-statement"
}

Result examples:

default:

Image or PDF of document

sessionNotFound:

{
  "argumentError": "session-not-found"
}

get-session-main-document-face-photo - Get face photo from main document

URL:

https://external-api.identomat.com/get-session-main-document-face-photo

Description:

This endpoint allows you to retrieve the face photo from the main document associated with a specific session.

Parameters:

• companyKey (string, required) - The company's secret key.

• sessionId (string, required) - The unique identifier of the session.

cURL example:

curl https://external-api.identomat.com/get-session-main-document-face-photo \
    -d '{"companyKey":"abcd","sessionId":"defg"}'

Request parameter examples:

{
  "companyKey": "abcd",
  "sessionId": "defg"
}

Result examples:

default:

{
  "result": "data:text/plain;base64String"
}

invalidAccess:

{
  "argumentError": "invalid-access"
}

notFound:

{  "argumentError": "face-photo-not-found"}

sessionNotFound:

{
  "argumentError": "session-not-found"
}

list-session-activities - List of session activities

URL:

https://external-api.identomat.com/list-session-activities

Description:

This endpoint retrieves a list of activities related to a specific session.

Parameters:

• companyKey (string, required) - The company's secret key.

• sessionId (string, required) - The unique identifier of the session.

cURL example:

curl https://external-api.identomat.com/list-session-activities \
    -d '{"companyKey":"abcd","sessionId":"defg"}'

Request parameter examples:

{
  "companyKey": "abcd",
  "sessionId": "defg"
}

Result examples:

default:

{
  "result": [
    {
      "id": "6162636465666768696a6b6c",
      "type": "PAGE_LOADED",
      "time": "2021-12-29T11:30:39.086Z",
      "data": []
    },
    {
      "id": "5ff45878f44e95bbf987a801",
      "type": "PAGE_LOADED",
      "time": "2011-12-29T11:30:39.086Z",
      "data": []
    }
  ]
}

invalidAccess:

{
  "argumentError": "invalid-access"
}

sessionNotFound:

{
  "argumentError": "session-not-found"
}

get-session-statistical-summary - Session statistical summary

URL:

https://external-api.identomat.com/get-session-statistical-summary

Description:

This endpoint retrieves a statistical summary of a session, providing key metrics and insights.

Parameters:

• companyKey (string, required) - The company's secret key.

• sessionId (string, required) - The unique identifier of the session.

cURL example:

curl https://external-api.identomat.com/get-session-statistical-summary \
    -d '{"companyKey":"abcd","sessionId":"defg"}'

Request parameter examples:

{
  "companyKey": "abcd",
  "sessionId": "defg"
}

Result examples:

default:

{
  "result": [
    {
      "sessionStartDate": "2021-12-29T11:30:40.000Z",
      "sessionTimeSpan": 8000,
      "scanDocumentStartTime": "2021-12-29T11:30:41.000Z",
      "scanDocumentEndTime": "2021-12-29T11:30:43.000Z",
      "scanDocumentAttempts": 1,
      "scanDocumentFailReason": null,
      "livenessStartTime": "2021-12-29T11:30:45.000Z",
      "livenessEndTime": "2021-12-29T11:30:48.000Z",
      "livenessFailReasons": null,
      "sessionTerminationStep": null,
      "sessionTerminationReasons": null
    }
  ]
}

invalidAccess:

{
  "argumentError": "invalid-access"
}

sessionNotFound:

{
  "argumentError": "session-not-found"
}

get-visual-markers - Get document visual markers

URL:

https://external-api.identomat.com/get-visual-markers

Description:

This endpoint retrieves the visual markers from a document.

Parameters:

• companyKey (string, required) - The company's secret key.

• sessionId (string, required) - The unique identifier of the session.

cURL example:

curl -L 'https://external-api.identomat.com/get-visual-markers' \
-H 'Content-Type: application/json' \
-d '{
    "companyKey": "abcd",
    "sessionId": "defg"
}'

Request parameter examples:

{
  "companyKey": "abcd",
  "sessionId": "defg"
}

Result examples:

default:

{
  "result": [
    [
      "data:application/x-tar;base64,base64String"
    ]
  ]
}

wrongParameters:

{
  "argumentError": "wrong-parameters"
}

invalidAccess:

{
  "argumentError": "invalid-access"
}

sessionNotFound:

{
  "argumentError": "session-not-found"
}

get-question-file - Get file from the question

URL:

https://external-api.identomat.com/get-question-file

Description:

This endpoint allows you to retrieve a file attached to a specific question in a questionnaire.

Parameters:

• companyKey (string, required) - The company's secret key.

• sessionId (string, required) - The unique identifier of the session.

• stepKey (string, required) – The unique key of the questionnaire step.

• questionKey(string, required) – The unique key of the question within the questionnaire.

• fileIndex (integer, optional) – The index of the file when multiple files are uploaded to a question. This is used to reference a specific file within the question’s attachments.

cURL example:

curl -L 'https://external-api.identomat.com/get-question-file' \
-H 'Content-Type: application/json' \
-d '{
    "companyKey": "abcd",
    "sessionId": "defg",
    "stepKey": "user-questionnaire-1",
    "questionKey": "question-1",
    "fileIndex": 0
}'

Request parameter examples:

{
  "companyKey": "abcd",
  "sessionId": "defg",
  "stepKey": "user-questionnaire-1",
  "questionKey": "question-1",
  "fileIndex": 0
}

Result examples:

default:

{
  "result": [
    [
      "data:application/x-tar;base64,base64String"
    ]
  ]
}

wrongParameters:

{
  "argumentError": "wrong-parameters"
}

invalidAccess:

{
  "argumentError": "invalid-access"
}

sessionNotFound:

{
  "argumentError": "session-not-found"
}

AML Screening

The methods below are used to perform and retrieve results for Anti-Money Laundering (AML) screening associated with a session:

search-screening-person - Search for a person in screening databases

URL:

https://external-api.identomat.com/search-screening-person

Description:

Use this endpoint to search for individuals in global screening databases including sanctions, PEPs (Politically Exposed Persons), regulatory actions, and more.

Parameters:

• companyKey (string, required) - The company's secret key.

• query (object, required) – The parameters for querying the database.

  • fullName (string, required) – Full name of the individual.

  • birthdayTimeFrom (string, optional) – The start date and time of the birthday range in ISO 8601 format.

  • scoreThreshold (integer, required) – The minimum score required for the query results.

• offset (integer, optional) – The number of items to skip from the beginning of the results.

• limit (integer, optional) – The maximum number of items to return in the query results.

Entities glossary:

• Sanctioned Entity: Companies, individuals, or other entities that have been designated by a government to prohibit specific interactions with them.

• Sanction-linked Entity: Entities, including companies and individuals, that have a direct relationship with a sanctioned entity. This also includes companies that are indirect subsidiaries of sanctioned entities, regardless of the percentage ownership held by the sanctioned entity.

• Counter-sanctioned Entity: Entities listed on sanctions lists from non-democratic countries, often targeting pro-democracy activists, journalists, and human rights advocates.

• Debarred Entity: Companies or individuals that have been excluded from public procurement, typically due to committing fraud in the execution of a government contract.

• Politician (Politically Exposed Persons): Individuals who currently or previously held a position of political influence.

• Close Associate: Family members and key business associates of politically exposed persons (PEPs). These individuals are often used as nominees or front-people to hide illicit financial gains.

• Person of Interest: Individuals under scrutiny due to public interest, who do not meet the common definitions of politically-exposed persons and are not sanctioned.

• Regulator Action: Companies that have been subject to enforcement action by an industry regulatory body.

• Regulator Warning: Companies that have been placed on a warning or alert list by an industry regulatory body.

cURL example:

curl https://external-api.identomat.com/search-screening-person \
    -d '{"companyKey":"abcd","query":{"birthdayTimeFrom":"1980-11-07T13:07:59.790Z","fullName":"John Smith","scoreThreshold":80},"offset":0,"limit":100}'

Request parameter examples:

{
  "companyKey": "abcd",
  "query": {
    "birthdayTimeFrom": "1980-11-07T13:07:59.790Z",
    "fullName": "John Smith",
    "scoreThreshold": 80
  },
  "offset": 0,
  "limit": 100
}

Result examples:

default - no results for person:

{
    "result": []
}

default - person found:

{
    "result": [
        {
            "score": 100,
            "name": "Vladimir Vladimirovich PUTIN",
            "personId": "67137933a2176f0797f1e657",
            "entityType": "person",
            "topics": [
                "Sanctioned entity",
                "Wanted person",
                "Person of interest",
                "Politician"
            ]
        }
    ]
}

companyMissing:

{
  "argumentError": "company-missing"
}

accessDenied:

{
  "argumentError": "access-denied"
}

get-screening-person-details - Get person details from screening databases

URL:

https://external-api.identomat.com/get-screening-person-details

Description:

Retrieve extended profile data, positions, aliases, sanctions, and other metadata for a specific individual listed in screening databases.

Parameters:

• companyKey (string, required) - The company's secret key.

• personId (string, required) – The unique identifier for the person.

cURL example:

curl https://external-api.identomat.com/get-screening-person-details \
  -d '{"companyKey":"abcd","personId":"defg"}'

Request parameter examples:

{
  "companyKey": "abcd",
  "personId": "defg"
}

Result examples:

default:

{
    "result": {
        "entityType": "person",
        "firstName": "John",
        "middleName": "Doe",
        "lastName": "Smith",
        "gender": "male",
        "birthdayTime": "1952-10-07",
        "nationality": "US",
        "extraDetails": [
            {
                "groupName": "Profile",
                "details": [
                    {
                        "detailName": "John Doe Smith",
                        "properties": [
                            {
                                "propertyName": "Position",
                                "value": [
                                    "President of US (2012-)",
                                    "chairperson",
                                    "party leader"
                                ],
                                "type": "list"
                            },
                            {
                                "propertyName": "Name",
                                "value": [
                                    "John Doe Smith",
                                    "约翰·多·史密斯",
                                    "Джон Доу Сміт",
                                   
                            {
                                "propertyName": "Alias",
                                "value": [
                                    "John Smith"
                                ],
                                "type": "list"
                            },
            {
                "groupName": "Position occupied",
                "details": [
                    {
                        "detailName": "President",
                        "properties": [
                            {
                                "propertyName": "Name",
                                "value": [
                                    "President of US",
                                    "President"
                                ],
                                "type": "string"
                            },
                            {
                                "propertyName": "Start Date",
                                "value": [
                                    "1999-08-16"
                                ],
                                "type": "date"
                            },
                            {
                                "propertyName": "End Date",
                                "value": [
                                    "2000-05-07"
                                ],
                                "type": "date"
                            },
                            {
                                "propertyName": "Status",
                                "value": [
                                    "active"
                                ],
                                "type": "string"
                            }
                        ]
                    },
            {
                "groupName": "Sanctions",
                "details": [
                    {
                        "detailName": "Department of Foreign Affairs and Trade",
                        "properties": [
                            {
                                "propertyName": "Start Date",
                                "value": [
                                    "2022-02-28"
                                ],
                                "type": "date"
                            },
                            {
                                "propertyName": "Authority",
                                "value": [
                                    "Department of Foreign Affairs and Trade"
                                ],
                                "type": "string"
                            },
                            {
                                "propertyName": "Program",
                                "value": [
                                    ""
                                ],
                                "type": "string"
                            },
                            {
                                "propertyName": "Entity",
                                "value": [
                                    "Q772247"
                                ],
                                "type": "string"
                            },
                            {
                                "propertyName": "Summary",
                                "value": [
                                    "Instrument of first designation and declaration: Autonomous Sanctions ....."
                                ],
                                "type": "string"
                            },
                            {
                                "propertyName": "Source Url",
                                "value": [
                                    "https://www.dfat.gov.au/international-relations/security/sanctions/Pages3/"
                                ],
                                "type": "url"
                            }
                        ]
                    }
                }
            }
         }
      }
   }
}

companyMissing:

{
  "argumentError": "company-missing"
}

accessDenied:

{
  "argumentError": "access-denied"
}

monitor-screening-query - Set person on monitoring

URL:

https://external-api.identomat.com/monitor-screening-query

Description:

Enable ongoing monitoring of a specific individual in screening databases. If the person is already on monitoring, an appropriate error will be returned.

Parameters:

• companyKey (string, required) - The company's secret key.

• query (object, required) – The parameters for querying the database.

  • fullName (string, required) – The last name of the individual.

  • birthdayTimeFrom (string, optional) – The start date and time of the birthday range in ISO 8601 format.

cURL example:

curl https://external-api.identomat.com/monitor-screening-query \
  -d '{ "companyKey":"abcd", "query": {"fullName": "John",  "birthdayTimeFrom": "1982-12-12"}}'

Request parameter examples:

{
  "companyKey": "abcd",
  "query": {
    "fullName": "John Smith",
    "birthdayTimeFrom": "1982-12-12"
  }
}

Result examples:

default:

{
  "result": "64ad3b14090678e34512eab8"
}

Already on monitoring:

{
    "argumentError": "already-exists"
}

remove-screening-query-from-monitoring - Remove person from monitoring

URL:

https://external-api.identomat.com/remove-screening-query-from-monitoring

Description:

Removes an individual from ongoing screening monitoring, unsubscribing from further updates or alerts related to that person.

Parameters:

• companyKey (string, required) - The company's secret key.

• id (string, required) - The ID of monitoring query.

cURL example:

curl https://external-api.identomat.com/remove-screening-query-from-monitoring \
  -d '{ "companyKey": "abcd", "id": "64ad3b14090678e34512eab8"}'

Request parameter examples:

{
  "companyKey": "abcd",
  "id": "64ad3b14090678e34512eab8"
}

Result examples:

default:

{ }

list-screening-monitoring-records - List screening records that are monitored

URL:

https://external-api.identomat.com/list-screening-monitoring-records

Description:

Retrieves a list of individuals currently being monitored for screening. This includes basic metadata like name, ID, and optionally the last updated date.

Parameters:

• companyKey (string, required) - The company's secret key.

• start (integer, optional) – The number of items to skip from the beginning of the results.

• limit (integer, optional) – The maximum number of records to return.

• date (string, optional, ISO 8601 format) – Filters records after a specific date. If no date is provided, the entire list will be returned.

cURL example:

curl https://external-api.identomat.com/list-screening-monitoring-records \
  -d '{"companyKey":"abcd", "start":0, "limit": 50}'

Request parameter examples:

{
  "companyKey": "abcd",
  "start": 0,
  "limit": 50,
  "date":"2023-07-10T12:26:00.576Z
}

Result examples:

default:

{
  "result": {
    "start": 0,
    "limit": 50,
    "total": 4,
    "data": [
      {"fullName":"John Smith1","id":"64ad3b14090678e34512eab8"},
      {"fullName":"John Smith2","id":"64ad3ef45fcf054afc73ebb4", "lastUpdatedDate": "2023-07-01T10:50:42.389Z"},
      {"fullName":"John Smith3","id":"64ad3f3a8b3f54aca29fc0a2", "lastUpdatedDate": "2023-07-20T10:50:42.389Z"},
      {"fullName":"John Smith4","id":"64ad3f3a8b3f54aca29fc0a3"}
    ]
  }
}

Blacklist management

APIs for managing individuals flagged for fraud or other risks. Use these endpoints to add a person to the blacklist, remove them, or retrieve the current list of blacklisted records.

add-blacklist-record - Add person to the blacklist

URL:

https://external-api.identomat.com/add-blacklist-record

Description:

Adds a person to the blacklist based on identifying attributes such as name, document number, or personal number.

Parameters:

• companyKey (string, required) - The company's secret key.

• query (object of strings, required) - Object containing query details. Must include reason and at least one of the following: firstName, lastName, personalNumber, documentNumber, birthday.

  • firstName (string, optional) - First name of the individual.

  • lastName (string, optional) - Last name of the individual.

  • personalNumber (string, optional) - Personal identification number.

  • documentNumber (string, optional) - Document number (e.g., from an ID or passport).

  • birthday (string, optional) - Birthday in ISO 8601 format (e.g., 1990-05-14).

  • reason (string, required) - The reason for blacklisting the individual.

cURL example:

curl -L 'https://external-api.identomat.com/add-blacklist-record' \
-H 'Content-Type: application/json' \
--data-raw '{
    "companyKey": "abcd",
    "query": {
        "firstName": "John",
        "lastName": "Doe",
        "personalNumber": "12345678901",
        "documentNumber": "123ABC123",
        "birthday": "1980-01-01T00:00:00.000Z",
        "reason": "Reason for adding to blacklist"
    }
}'

Request parameter examples:

{
    "companyKey": "abcd",
    "query": {
        "firstName": "John",
        "lastName": "Doe",
        "personalNumber": "12345678901",
        "documentNumber": "123ABC123",
        "birthday": "1980-01-01T00:00:00.000Z",
        "reason": "Reason for adding to blacklist"
    }
}

Result examples:

default:

{
    "result": "682b09e4400b3a00067ebcf7"
}

wrongParameters:

{
  "argumentError": "wrong-parameters"
}

invalidCompanyKey:

{
  "argumentError": "invalid-company-key"
}

alreadyExists

{  
  "argumentError": "already-exists"
}

remove-blacklist-record - Remove record from the blacklist

URL:

https://external-api.identomat.com/remove-blacklist-record

Description:

Removes previously added record from the blacklist.

Parameters:

• companyKey (string, required) - The company's secret key.

• id (string, required) - Blacklist record ID.

cURL example:

curl -L 'https://external-api.identomat.com/remove-blacklist-record' \
-H 'Content-Type: application/json' \
--data-raw '{
    "companyKey": "abcd",
    "id": "682b09e4400b3a00067ebcf7"
}'

Request parameter examples:

{
    "companyKey": "abcd",
    "id": "682b09e4400b3a00067ebcf7"
}

Result examples:

default:

{
    "result": true
}

wrongParameters:

{
  "argumentError": "wrong-parameters"
}

invalidCompanyKey:

{
"argumentError": "invalid-company-key"
}

idNotFound:

{  
  "argumentError": "not-found"
}

list-blacklist-records - List all blacklist records associated with the company

URL:

https://external-api.identomat.com/list-blacklist-records

Description:

Retrieves all blacklist records associated with the company. You can optionally filter records by a query, set pagination with offset and limit, or retrieve the full list.

Parameters:

• companyKey (string, required) - The company's secret key.

• query (object of strings, optional) - Optional filter fields:

  • offset (number, optional) - Number of records to skip from the beginning.

  • limit (number, optional) - Maximum number of records to return.

cURL example:

curl -L 'https://external-api.identomat.com/list-blacklist-records' \
-H 'Content-Type: application/json' \
--data-raw '{
    "companyKey": "abcd"
}'

Request parameter examples:

{
    "companyKey": "abcd"
}

Result examples:

default:

{
    "result": {
        "offset": 0,
        "limit": 100,
        "total": 1,
        "data": [
            {
                "firstName": "John",
                "lastName": "Doe",
                "documentNumber": "123ABC123",
                "personalNumber": "012345678901",
                "birthday": "1980-01-01T00:00:00.000Z",
                "notes": null,
                "reason": "Reason for adding to blacklist",
                "id": "682b09e4400b3a00067ebcf7"
            }
        ]
    }
}

wrongParameters:

{
  "argumentError": "wrong-parameters"
}

invalidCompanyKey:

{
"argumentError": "invalid-company-key"
}

noRecord:

{
    "result": {
        "offset": 0,
        "limit": 100,
        "total": 0,
        "data": []
    }
}

Video call

The methods below are used to retrieve results from video call sessions:

get-video-call-shots - Video call shots

URL:

https://external-api.identomat.com/get-video-call-shots

Description:

Retrieves all screenshots (shots) taken by the operator during a video call session. These images serve as part of the evidence captured during the KYC verification.

Parameters:

• companyKey (string, required) - The company's secret key.

• sessionId (string, required) - The unique identifier of the session.

cURL example:

curl https://external-api.identomat.com/get-video-call-shots \
    -d '{"companyKey":"abcd","sessionId":"defg"}'

Request parameter examples:

{
  "companyKey": "abcd",
  "sessionId": "defg"
}

Result examples:

default:

{
  "result": [
    [
      "data:application/x-tar;base64,base64String"
    ]
  ]
}

invalidAccess:

{
  "argumentError": "invalid-access"
}

sessionNotFound:

{
  "argumentError": "session-not-found"
}

get-video-call-videos - Video call videos

URL:

https://external-api.identomat.com/get-video-call-videos

Description:

Retrieves all video recordings from the video call session. These are typically used for compliance, auditing, or further verification purposes.

Parameters:

• companyKey (string, required) - The company's secret key.

• sessionId (string, required) - The unique identifier of the session.

cURL example:

curl https://external-api.identomat.com/get-video-call-videos \
    -d '{"companyKey":"abcd","sessionId":"defg"}'

Request parameter examples:

{
  "companyKey": "abcd",
  "sessionId": "defg"
}

Result examples:

default:

Videos in tar archive format.

invalidAccess:

{
  "argumentError": "invalid-access"
}

notFound:

{  "argumentError": "not-found"}

sessionNotFound:

{
  "argumentError": "session-not-found"
}

end-video-call - End video call for the connected user

URL:

https://external-api.identomat.com/end-video-call

Description:

Manually ends an active video call session for the connected user. This endpoint is typically used by system to forcefully close a session that is still ongoing.

Parameters:

• companyKey (string, required) - The company's secret key.

• sessionId (string, required) - The unique identifier of the session.

cURL example:

curl https://external-api.identomat.com/get-video-call-videos \
    -d '{"companyKey":"abcd","sessionId":"defg"}'

Request parameter examples:

{
  "companyKey": "abcd",
  "sessionId": "defg"
}

Result examples:

default:

{ }

invalidAccess:

{
  "argumentError": "invalid-access"
}

Other methods

list-groups - List groups

URL:

https://external-api.identomat.com/list-groups

Description:

Retrieves a list of groups associated with the specified company. Each group includes its ID, name, and a list of its members.

Parameters:

• companyKey (string, required) - The company's secret key.

cURL example:

curl https://external-api.identomat.com/list-groups \
    -d '{"companyKey":"abcd"}'

Request parameter examples:

{
  "companyKey": "abcd"
}

Result examples:

default:

{
  "result": [
        {
            "id": "650976e8dc32104b8bb1757e",
            "name": "group_name",
            "members": [ 
                {"username": "[e-mail]"},
                {"username": "[e-mail]"}
            ]
        }
]
}

noGroups:

{
  "result": []
}

notFound:

{  "argumentError": "not-found"}

make-group - Create a new group

URL:

https://external-api.identomat.com/make-group

Description:

Creates a new user group under the specified company. A group can be used to manage permissions, assign sessions, or organize users.

Parameters:

• companyKey (string, required) - The company's secret key.

• name (string, required) – The name of the new group.

• memberIds (array of strings, optional) – A list of user IDs to be added to the group.

cURL example:

curl -L 'https://external-api.identomat.com/make-group' \
-d '{
    "companyKey": "abcd",
    "name": "Group 1",
    "memberIds": [ "user1_id", "user2_id"
    ]
}'

Request parameter examples:

{
    "companyKey": "abcd",
    "name": "Group 1",
    "memberIds": [ "user1_id", "user2_id"
    ]
}

Result examples:

default:

{
    "result": {
        "id": "6784c6d768cb9e8a891087e1"
    }
}

wrongParameter:

{"argumentError":"wrong-parameters",
"errorSourceGroup":"service-module-server-external"}

change-group - Update existing group

URL:

https://external-api.identomat.com/make-group

Description:

Allows you to modify an existing group by updating its name or changing the members in the group. To keep existing members in the group, you must include their IDs in the list.

Parameters:

• companyKey (string, required) - The company's secret key.

• groupId (string, required) – The unique identifier of the group.

• name (string, optional) – The name of the new group.

• memberIds (array of strings, optional) – A list of user IDs to be added or removed from the group. To keep existing members in the group, you must include their IDs in the list.

cURL example:

curl -L 'https://external-api.identomat.com/change-group' \
-d '{
    "companyKey": "abcd",
    "groupId": "679c951cfc9fb5ff47e2833c",
    "name": "Group 1",
    "memberIds": [ "user1_id", "user2_id"
    ]
}'

Request parameter examples:

{
    "companyKey": "abcd",
    "groupId": "679c951cfc9fb5ff47e2833c",
    "name": "Group 1",
    "memberIds": [ "user1_id", "user2_id"
    ]
}

Result examples:

default:

{}

wrongParameter:

{"argumentError":"wrong-parameters",
"errorSourceGroup":"service-module-server-external"}

delete-group - Delete a group

URL:

https://external-api.identomat.com/delete-group

Description:

Allows you to delete a group permanently from the system.

Parameters:

• companyKey (string, required) - The company's secret key.

• groupId (string, required) – The unique identifier of the group.

cURL example:

curl -L 'https://external-api.identomat.com/delete-group' \
-d '{
    "companyKey": "abcd",
    "groupId": "679c951cfc9fb5ff47e2833c"
    ]
}'

Request parameter examples:

{
    "companyKey": "abcd",
    "groupId": "679c951cfc9fb5ff47e2833c"
    ]
}

Result examples:

default:

{}

wrongParameter:

{"argumentError":"wrong-parameters",
de"errorSourceGroup":"service-module-server-external"}

list-users - List users

URL:

https://external-api.identomat.com/list-users

Description:

This endpoint retrieves a list of users associated with the company.

Parameters:

• companyKey (string, required) - The company's secret key.

cURL example:

curl https://external-api.identomat.com/list-users \
    -d '{"companyKey":"abcd"}'

Request parameter examples:

{
  "companyKey": "abcd"
}

Result examples:

default:

{
    "result": [
        {
            "id": "user_id",
            "username": "[e-mail]",
            "roles": [
                "identomat_admin",
                "administrator",
                "operator",
                "call_center_operator"
            ]
        }
    ]
}

wrongParameters:

{
  "argumentError": "wrong-parameters"
}

invalidAccess:

{
  "argumentError": "invalid-access"
}

create-user - Create a user

URL:

https://external-api.identomat.com/create-user

Description:

Creates a new user for the Identomat platform (Manage).

Parameters:

• companyKey (string, required) - The company's secret key.

• email (string, required) - The email address of the new user.

• emailVerified (boolean, optional) - Whether the email should be marked as verified. Defaults to false.

• password (string, required) - The user’s password (minimum 8 characters).

• firstName (string, optional) - First name of the user.

• lastName (string, optional) - Last name of the user.

• rights (array of strings, optional) - List of roles to assign to the user. If omitted, defaults to call_center_operator. Valid values are:

  • call_center_operator

  • operator

  • administrator

cURL example:

curl -L 'https://external-api.identomat.com/create-user' \
-H 'Content-Type: application/json' \
--data-raw '{
    "companyKey": "abcd",
    "email": "[e-mail]",
    "emailVerified": true,
    "password": "12345678",
    "firstName": "John",
    "lastName": "Doe",
    "rights": [
        "call_center_operator",
        "administrator",
        "operator"
    ]
}'

Request parameter examples:

{
  "companyKey": "abcd"
  "email": "[e-mail]",
  "emailVerified": true,
  "password": "12345678",
  "firstName": "John",
  "lastName": "Doe",
  "rights": [
        "call_center_operator",
        "administrator",
        "operator"
    ]
}

Result examples:

default:

{
    "result": "68243e94540d1e5fe6c04a0f"
}

wrongParameters:

{
  "argumentError": "wrong-parameters"
}

invalidCompanyKey:

{
  "argumentError": "invalid-company-key"
}

invalidEmailFormat:

{
  "argumentError": "invalid-email-format"
}

passwordTooShort

{
  "argumentError": "password-too-short"
}

passwordIsNotString

{
  "internalError": Illegal arguments: number, string"
}

invalidRights

{
  "argumentError": "invalid-rights"
}

userAlreadyExists:

{
  "argumentError": "user-already-exists"
}

get-session-config - Get session configuration

URL:

https://external-api.identomat.com/get-session-config

Description:

This endpoint retrieves the configuration details for a specific session configuration based on the given session config ID.

Parameters:

• companyKey (string, required) - The company's secret key.

• sessionConfigId (string, required) – The unique identifier for the session configuration.

cURL example:

curl https://external-api.identomat.com/get-session-config \
    -d '{"companyKey":"abcd","sessionConfigId":"defg"}'

Request parameter examples:

{
  "companyKey": "abcd",
  "sessionConfigId": "defg"
}

Result examples:

default:

{
  "result": {
    "id": "679c74e4d9725987e3879265",
    "name": "Configuration Template",
    "general": {
        "language": "en",
        "sessionLifetime": 15
        }
    "steps": [
      {
        "title": {
          "en": "ID Verification"
        },
        "type": "identity-document",
        "key": "select_document_id",
        "flags": {
          "documentTypes": [
            "id",
            "passport",
            "driver_license",
            "residence_permit"
          ]
        }
      },
      {
        "title": {
          "en": "Liveness Check"
        },
        "type": "liveness",
        "key": "liveness",
        "flags": {
          "liveness": true,
          "maxLivenessAttempts": 3
        }
      }
    ]
  }
}

wrongParameters:

{
  "argumentError": "wrong-parameters"
}

Processing an image

The methods below are used for manually processing an image. Each method returns either a string with an error code or an object containing the extracted information. The number of fields in the object may vary depending on the data successfully extracted from the image.

card/front/ - ID card front side

URL:

https://widget.identomat.com/external-api/card/front/

Parameters:

• company_key (string, required) - The company's secret key.

• image (file, required) – A JPEG image file to be uploaded.

cURL example:

curl https://widget.identomat.com/external-api/card/front/ \
    -F 'company_key={some_company_key}' \
    -F 'image=@{some_image.jpg}'

Result examples:

default:

{
    "Given_Names_en_US": "JOHN",
    "Surname_en_US": "DOE",
    "citizenship": "USA",
    "Sex_en_US": "M",
    "Personal_Number_en_US": "1234567890",
    "Date_of_Birth_en_US": "1/1/1990",
    "Date_of_Expiry_en_US": "1/1/2030",
    "Document_Number_en_US": "USA1234567",
    "Issuing_State_Code_en_US": "USA",
    "Date_of_Birth_ISO": "1990-01-01T00:00:00.000Z",
    "Date_of_Expiry_ISO": "2030-01-01T00:00:00.000Z",
    "requestId": "abcdef1234567890abcdef1234567890",
    "person": {
        "first_name": "JOHN",
        "last_name": "DOE",
        "birthday": "1/1/1990",
        "birthday_time": "1990-01-01T00:00:00.000Z",
        "age": 34,
        "citizenship": "USA",
        "document_number": "USA1234567",
        "document_expires": "1/1/2030",
        "document_expires_time": "2030-01-01T00:00:00.000Z",
        "personal_number": "1234567890",
        "issuing_state": "USA",
        "sex": "M"
    }
}

card/back/ - ID card back side

URL:

https://widget.identomat.com/external-api/card/back/

Parameters:

• company_key (string, required) - The company's secret key.

• image (file, required) – A JPEG image file to be uploaded.

cURL example:

curl https://widget.identomat.com/external-api/card/back/ \
    -F 'company_key={some_company_key}' \
    -F 'image=@{some_image.jpg}'

Result examples:

default:

{
    "Date_of_Issue_en_US": "6/28/2021",
    "Issuing_State_Code_en_US": "USA",
    "Place_of_Birth_en_US": "USA",
    "Date_of_Issued_ISO": "2021-06-28T00:00:00.000Z",
    "Given_Names_en_US": "JOHN DOE",
    "Surname_en_US": "DOE",
    "Nationality_Code_en_US": "USA",
    "Sex_en_US": "M",
    "Personal_Number_en_US": "1234567890",
    "Date_of_Birth_en_US": "1/1/1990",
    "Date_of_Expiry_en_US": "6/28/2031",
    "Document_Number_en_US": "USA1234567",
    "Nationality_en_US": "USA",
    "Date_of_Birth_ISO": "1990-01-01T00:00:00.000Z",
    "Date_of_Expiry_ISO": "2031-06-28T00:00:00.000Z",
    "mrz": "IDUSA1234567938001085718<<<<\n8001081M2606288USA<<<<<<<<<<<1\nDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<",
    "requestId": "abcdef1234567890abcdef1234567890",
    "person": {
        "first_name": "JOHN DOE",
        "last_name": "DOE",
        "birthday": "1/1/1990",
        "birthday_time": "1990-01-01T00:00:00.000Z",
        "age": 34,
        "birth_place": "USA",
        "nationality": "USA",
        "document_number": "USA1234567",
        "document_issued": "6/28/2021",
        "document_expires": "6/28/2031",
        "document_expires_time": "2031-06-28T00:00:00.000Z",
        "document_issued_time": "2021-06-28T00:00:00.000Z",
        "personal_number": "1234567890",
        "issuing_state": "USA",
        "sex": "M",
        "mrz": "IDUSA1234567938001085718<<<<\n8001081M2606288USA<<<<<<<<<<<1\nDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<"
    }
}

license/front/ - Driver license front side

URL:

https://widget.identomat.com/external-api/license/front/

Parameters:

• company_key (string, required) - The company's secret key.

• image (file, required) – A JPEG image file to be uploaded.

cURL example:

curl https://widget.identomat.com/external-api/license/front/ \
    -F 'company_key={some_company_key}' \
    -F 'image=@{some_image.jpg}'

Result examples:

default:

{
    "Given_Names_en_US": "John",
    "Surname_en_US": "Doe",
    "Given_Names_ka_GE": "ჯონ",
    "Surname_ka_GE": "დო",
    "Personal_Number_en_US": "1234567890",
    "Date_of_Birth_en_US": "1/1/1985",
    "Date_of_Issue_en_US": "5/15/2015",
    "Document_Number_en_US": "ID1234567",
    "Issuing_State_Code_en_US": "USA",
    "Place_of_Birth_en_US": "Los Angeles",
    "Authority_en_US": "Department of Motor Vehicles",
    "Date_of_Birth_ISO": "1985-01-01T00:00:00.000Z",
    "Date_of_Issued_ISO": "2015-05-15T00:00:00.000Z",
    "Address_en_US": "456 Main St, Los Angeles, CA 90001",
    "Local_Address_en_US": "456 Main St, Los Angeles, CA 90001",
    "localAuthority": "Department of Motor Vehicles",
    "Drivers_License_Class_en_US": "C",
    "requestId": "a1b2c3d4e5f67890",
    "person": {
        "local_first_name": "ჯონ",
        "local_last_name": "დო",
        "first_name": "John",
        "last_name": "Doe",
        "birthday": "1/1/1985",
        "birthday_time": "1985-01-01T00:00:00.000Z",
        "age": 40,
        "birth_place": "Los Angeles",
        "document_number": "ID1234567",
        "document_issued": "5/15/2015",
        "document_issued_time": "2015-05-15T00:00:00.000Z",
        "personal_number": "1234567890",
        "authority": "Department of Motor Vehicles",
        "local_authority": "Department of Motor Vehicles",
        "issuing_state": "USA",
        "address": "456 Main St, Los Angeles, CA 90001",
        "local_address": "456 ქუჩა, ლოს ანჯელესი, CA 90001"
    }
}

license/back/ - Driver license back side

URL:

https://widget.identomat.com/external-api/license/back/

Parameters:

• company_key (string, required) - The company's secret key.

• image (file, required) – A JPEG image file to be uploaded.

cURL example:

curl https://widget.identomat.com/external-api/license/back/ \
    -F 'company_key={some_company_key}' \
    -F 'image=@{some_image.jpg}'

Result examples:

default:

{
    "Issuing_State_Code_en_US": "USA",
    "requestId": "262f6ee39992e0a61769c5cc13b2f092",
    "person": {
        "issuing_state": "USA"
    }
}

residence/front/ - Residence permit front side

URL:

https://widget.identomat.com/external-api/residence/front/

Parameters:

• company_key (string, required) - The company's secret key.

• image (file, required) – A JPEG image file to be uploaded.

cURL example:

curl https://widget.identomat.com/external-api/residence/front/ \
    -F 'company_key={some_company_key}' \
    -F 'image=@{some_image.jpg}'

Result examples:

default:

{
    "Given_Names_en_US": "John",
    "Surname_en_US": "Doe",
    "Nationality_Code_en_US": "USA",
    "Sex_en_US": "M",
    "Date_of_Birth_en_US": "5/15/1985",
    "Date_of_Expiry_en_US": "12/31/2030",
    "Document_Number_en_US": "D12345678",
    "Nationality_en_US": "USA",
    "Issuing_State_Code_en_US": "USA",
    "Date_of_Birth_ISO": "1985-05-15T00:00:00.000Z",
    "Date_of_Expiry_ISO": "2030-12-31T00:00:00.000Z",
    "requestId": "1234567890abcdef1234567890abcdef",
    "person": {
        "first_name": "John",
        "last_name": "Doe",
        "birthday": "5/15/1985",
        "birthday_time": "1985-05-15T00:00:00.000Z",
        "age": 40,
        "nationality": "USA",
        "document_number": "D12345678",
        "document_expires": "12/31/2030",
        "document_expires_time": "2030-12-31T00:00:00.000Z",
        "issuing_state": "USA",
        "sex": "M"
    }
}

residence/back/ - Residence permit back side

URL:

https://widget.identomat.com/external-api/residence/back/

Parameters:

• company_key (string, required) - The company's secret key.

• image (file, required) – A JPEG image file to be uploaded.

cURL example:

curl https://widget.identomat.com/external-api/residence/back/ \
    -F 'company_key={some_company_key}' \
    -F 'image=@{some_image.jpg}'

Result examples:

default:

{
    "Date_of_Issue_en_US": "7/1/2020",
    "Issuing_State_Code_en_US": "ITA",
    "Place_of_Birth_en_US": "CITTA",
    "Date_of_Issued_ISO": "2020-07-01T00:00:00.000Z",
    "Given_Names_en_US": "John",
    "Surname_en_US": "Doe",
    "Nationality_Code_en_US": "USA",
    "Sex_en_US": "M",
    "Date_of_Birth_en_US": "5/15/1985",
    "Date_of_Expiry_en_US": "12/31/2030",
    "Document_Number_en_US": "D12345678",
    "Nationality_en_US": "USA",
    "Date_of_Birth_ISO": "1985-05-15T00:00:00.000Z",
    "Date_of_Expiry_ISO": "2030-12-31T00:00:00.000Z",
    "mrz": "P<USADOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<\nD12345678USA850515M3031232<<<<<<<<<<<<<<06",
    "requestId": "5924aa4e44eb394f7cd2377568c21859",
    "person": {
        "first_name": "John",
        "last_name": "Doe",
        "birthday": "5/15/1985",
        "birthday_time": "1985-05-15T00:00:00.000Z",
        "age": 40,
        "birth_place": "CITTA",
        "nationality": "USA",
        "document_number": "D12345678",
        "document_issued": "7/1/2020",
        "document_expires": "12/31/2030",
        "document_expires_time": "2030-12-31T00:00:00.000Z",
        "document_issued_time": "2020-07-01T00:00:00.000Z",
        "issuing_state": "ITA",
        "sex": "M",
        "mrz": "P<USADOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<\nD12345678USA850515M3031232<<<<<<<<<<<<<<06"
    }
}

passport/ - Passport photo page

URL:

https://widget.identomat.com/external-api/passport/

Parameters:

• company_key (string, required) - The company's secret key.

• image (file, required) – A JPEG image file to be uploaded.

cURL example:

curl https://widget.identomat.com/external-api/passport/ \
    -F 'company_key={some_company_key}' \
    -F 'image=@{some_image.jpg}'

Result example:

default:

{
    "mrzData": {
        "Given_Names_en_US": "JOHN",
        "Surname_en_US": "DOE",
        "Nationality_Code_en_US": "USA",
        "Sex_en_US": "M",
        "Date_of_Birth_en_US": "1/1/1990",
        "Date_of_Expiry_en_US": "1/1/2030",
        "Document_Number_en_US": "USA1234567",
        "Nationality_en_US": "USA",
        "Issuing_State_Code_en_US": "USA",
        "Date_of_Birth_ISO": "1990-01-01T00:00:00.000Z",
        "Date_of_Expiry_ISO": "2030-01-01T00:00:00.000Z",
        "mrz": "P<USADOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<\nUSA1234567USA9001019M3001019<<<<<<<<<<<<<<00"
    },
    "visualData": {
        "Given_Names_en_US": "JOHN",
        "Surname_en_US": "DOE",
        "Nationality_Code_en_US": "USA",
        "Sex_en_US": "M",
        "Personal_Number_en_US": "1234567890",
        "Date_of_Birth_en_US": "1/1/1990",
        "Date_of_Expiry_en_US": "1/1/2030",
        "Date_of_Issue_en_US": "1/1/2020",
        "Document_Number_en_US": "USA1234567",
        "Nationality_en_US": "USA",
        "Issuing_State_Code_en_US": "USA",
        "Place_of_Birth_en_US": "NEW YORK",
        "Authority_en_US": "USA AUTHORITY",
        "Date_of_Birth_ISO": "1990-01-01T00:00:00.000Z",
        "Date_of_Expiry_ISO": "2030-01-01T00:00:00.000Z",
        "Date_of_Issued_ISO": "2020-01-01T00:00:00.000Z"
    },
    "requestId": "1234567890abcdef1234567890abcdef",
    "person": {
        "first_name": "JOHN",
        "last_name": "DOE",
        "birthday": "1/1/1990",
        "birthday_time": "1990-01-01T00:00:00.000Z",
        "age": 34,
        "birth_place": "NEW YORK",
        "nationality": "USA",
        "document_number": "USA1234567",
        "document_issued": "1/1/2020",
        "document_expires": "1/1/2030",
        "document_expires_time": "2030-01-01T00:00:00.000Z",
        "document_issued_time": "2020-01-01T00:00:00.000Z",
        "personal_number": "1234567890",
        "authority": "USA AUTHORITY",
        "issuing_state": "USA",
        "sex": "M",
        "status": "FIELDS_MISMATCH",
        "mrz": "P<USADOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<\nUSA1234567USA9001019M3001019<<<<<<<<<<<<<<00"
    }
}

Additional processing

compare-faces/ - Get a similarity score for two faces

The minimum recommended face size in the picture is 80 pixels. If the face size is between 65-79 pixels, an error code will be returned along with the similarity score.

URL:

https://external-api.identomat.com/compare-faces

Parameters:

• companyKey (string, required) - The company's secret key.

• face1 (file, required) - A JPEG image file for face1

• face2 (file, required) - A JPEG image file for face2

cURL example:

curl https://external-api.identomat.com/compare-faces \
    -F 'companyKey={some_company_key}' \
    -F 'face1=@{some_face1.jpg}' \
    -F 'face2=@{some_face2.jpg}'

Result examples:

default:

{
    "result": {
        "similarity": 0.9399788229619534,
        "face1Statuses": [],
        "face2Statuses": []
    }
}

error:

{
    "result": {
        "similarity": null,
        "face1Statuses": [
            "FACE_FAR_AWAY"
        ],
        "face2Statuses": []
    }
}