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/

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, optioanl) – Defines the sequence of steps in the identification process.

or:

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

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"
}

Result examples:

default:

{
"47fjzxvvzapi4ztasth3c2ozfucli3l0qx13hisc"
}
result/ - Session results

URL:

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

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": "johndoe@email.com",
        "phoneNumber": "+1234567890",
        "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"
                }
            ]
        }
    ],
    "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": "johndoe@email.com",
        "phoneNumber": "+1234567890",
        "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"
                }
            ]
        }
    ],
    "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/

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

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/

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/

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/

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/

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/

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/

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/

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

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

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

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

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

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

Parameters:

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

  • query (object, required) – The parameters for querying the database. ( Either firstName , lastName or fullName must be provided.)

    • firstName (string, optional) – The first name of the individual.

    • lastName (string, optional) – The last name of the individual.

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

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

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

    • scoreThreshold (integer, optional) – 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.

cURL example:

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

Request parameter examples:

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

Result examples:

default - no results for person:

{
    "result": []
}

default - person found:

{
  "result": {
    "personId": "5ff45878f44e95bbf987a801",
    "source": "cdc",
    "name": "John Smith",
    "score": 100
  }
}

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

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": {
    "firstName": "John",
    "middleName": "Doe",
    "lastName": "Smith",
    "gender": "Male",
    "isDeceased": false,
    "birthdayTime": "1946-06-14T00:00:00.000Z",
    "nationality": "US",
    "photoUrl": "https://abcd.ef/0020851600.jpg",
    "sanctions": [
      {
        "country": "Iran",
        "measures": [
          "Asset Freeze",
          "Travel Ban"
        ]
      }
    ],
    "pep": [
      {
        "country": "US",
        "branch": "Executive Branch - Head of State and Deputy",
        "position": "President | US Presidency"
      }
    ]
  }
}

companyMissing:

{
  "argumentError": "company-missing"
}

accessDenied:

{
  "argumentError": "access-denied"
}
monitor-screening-query - Set person on monitoring

URL:

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

Parameters:

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

  • query (object, required) – The parameters for querying the database. ( Either firstName , lastName or fullName must be provided.)

    • firstName (string, optional) – The first name of the individual.

    • lastName (string, optional) – The last name of the individual.

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

cURL example:

curl https://external-api.identomat.com/monitor-screening-query \
  -d '{ "companyKey":"abcd", "query": {"firstName": "John", "lastName": "Smith"}}'

Request parameter examples:

{
  "companyKey": "abcd",
  "query": {
    "firstName": "John",
    "lastName": "Smith"
  }
}

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

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

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.

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": [
      {"firstname":"John","lastname":"Smith","id":"64ad3b14090678e34512eab8"},
      {"firstname":"John2","lastname":"Smith2","id":"64ad3ef45fcf054afc73ebb4", "lastUpdatedDate": "2023-07-01T10:50:42.389Z"},
      {"firstname":"John3","lastname":"Smith3","id":"64ad3f3a8b3f54aca29fc0a2", "lastUpdatedDate": "2023-07-20T10:50:42.389Z"},
      {"firstname":"John4","lastname":"Smith4","id":"64ad3f3a8b3f54aca29fc0a3"}
    ]
  }
}

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

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

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 - Ends video call for the connected user

URL:

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

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

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": "user1@example.com"},
                {"username": "user2@example.com"}
            ]
        }
]
}

noGroups:

{
  "result": []
}

notFound:

{  "argumentError": "not-found"}
make-group - Create a new group

URL:

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

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

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

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

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": "user@identomat.com",
            "roles": [
                "identomat_admin",
                "administrator",
                "operator",
                "call_center_operator"
            ]
        }
    ]
}

wrongParameters:

{
  "argumentError": "wrong-parameters"
}

invalidAccess:

{
  "argumentError": "invalid-access"
}
get-session-config - Get session configuration

URL:

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

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 - The company's secret key.

  • image - A JPEG image file

cURL example:

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

URL:

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

Parameters:

  • company_key - The company's secret key.

  • image - A JPEG image file

cURL example:

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

URL:

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

Parameters:

  • company_key - The company's secret key.

  • image - A JPEG image file

cURL example:

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

URL:

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

Parameters:

  • company_key - The company's secret key.

  • image - A JPEG image file

cURL example:

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

URL:

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

Parameters:

  • company_key - The company's secret key.

  • image - A JPEG image file

cURL example:

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

URL:

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

Parameters:

  • company_key - The company's secret key.

  • image - A JPEG image file

cURL example:

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

URL:

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

Parameters:

  • company_key - The company's secret key.

  • image - A JPEG image file

cURL example:

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

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://widget.identomat.com/external-api/compare-faces/

Parameters:

  • company_key - The company's secret key.

  • face1 - A JPEG image file for face1

  • face2 - A JPEG image file for face2

cURL example:

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

Result examples:

default:

{
  "similarity": 0.8,
  "error": null
}

warning:

{
  "similarity": 0.8,
  "error": "FACE_FAR_AWAY"
}

error:

{
  "error": "FACE_FAR_AWAY"
}

PreviousDeveloper guideNextOverview

Last updated