Identity Check

Run an identity check

To run an Identity Check, you must create a check with type set to identity_check.

The documentId provided must have associated image attachments that adhere to our image specifications.

Learn more about Identity Checks.

We will use the front side of the document for the Identity Check.

Check request

Attribute Type Description

Attribute	Type	Description
`clientId`	string	The ID of the client associated with this check. (Required)
`type`	string	This must be set to `identity_check`. (Required)
`documentId`	string	The ID of the document. (Required)
`livePhotoId`	string	The ID of the live photo. (Required)
`options`	string	The optional settings for the check. Also, see the options object below. (Optional)

clientId

string

The ID of the client associated with this check. (Required)

type

string

This must be set to identity_check. (Required)

documentId

string

The ID of the document. (Required)

livePhotoId

string

The ID of the live photo. (Required)

options

string

The optional settings for the check. Also, see the options object below. (Optional)

The `options` object

Attribute Type Description

Attribute	Type	Description
`enableEnrolledFaces`	boolean	Determines whether enrolled face matching is enabled. When this attribute is not provided, it will default to true.
`enableSpecimenMatching`	boolean	Determines whether specimen matching is enabled. When this attribute is not provided, it will default to true.
`enableVpnDetection`	boolean	Determines whether VPN detection is enabled. When this attribute is not provided, it will default to true.

enableEnrolledFaces

boolean

Determines whether enrolled face matching is enabled. When this attribute is not provided, it will default to true.

enableSpecimenMatching

boolean

Determines whether specimen matching is enabled. When this attribute is not provided, it will default to true.

enableVpnDetection

boolean

Determines whether VPN detection is enabled. When this attribute is not provided, it will default to true.

Example request

Simple request

curl -X POST https://api.complycube.com/v1/checks \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "clientId":"CLIENT_ID",
          "livePhotoId":"LIVE_PHOTO_ID",
          "documentId":"DOCUMENT_ID",
          "type": "identity_check"
        }'

const { ComplyCube } = require("@complycube/api");

const complycube = new ComplyCube({ apiKey: "<YOUR_API_KEY>" });

const check = await complycube.check.create("CLIENT_ID", {
        livePhotoId: "LIVE_PHOTO_ID",
        documentId: "DOCUMENT_ID",
        type: "identity_check"
});

from complycube import ComplyCubeClient

cc_api = ComplyCubeClient(api_key='<YOUR_API_KEY>')

check = cc_api.check.create(
    'CLIENT_ID', 
    'identity_check', 
    livePhotoId='LIVE_PHOTO_ID',
    documentId='DOCUMENT_ID'
)

use ComplyCube\ComplyCubeClient;

$ccapi = new ComplyCubeClient('<YOUR_API_KEY>');

$result = $ccapi->checks()->create(
    'CLIENT_ID',
    [
        'type' => 'identity_check',
        'livePhotoId' => 'LIVE_PHOTO_ID',
        'documentId' => 'DOCUMENT_ID'
    ]
);

using ComplyCube.Net;
using ComplyCube.Net.Resources.Checks;

var checkApi = new CheckApi(new ComplyCubeClient("<YOUR_API_KEY>"));

var checkRequest = new CheckRequest {
  clientId = "CLIENT_ID",
  documentId = "DOCUMENT_ID",
  livePhotoId = "LIVE_PHOTO_ID",
  type = "identity_check"
};

var check = await checkApi.CreateAsync(checkRequest);

Request with optional attributes

curl -X POST https://api.complycube.com/v1/checks \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "clientId":"CLIENT_ID",
          "livePhotoId":"LIVE_PHOTO_ID",
          "documentId":"DOCUMENT_ID",
          "type": "identity_check"
          "options":{
               "enableEnrolledFaces": false,
               "enableSpecimenMatching": false,
               "enableVpnDetection": false
          }
        }'

const { ComplyCube } = require("@complycube/api");

const complycube = new ComplyCube({ apiKey: "<YOUR_API_KEY>" });

const check = await complycube.check.create("CLIENT_ID", {
    livePhotoId: "LIVE_PHOTO_ID",
    documentId: "DOCUMENT_ID",
    type: "identity_check",
    options: {
        enableEnrolledFaces: false,
        enableSpecimenMatching: false,
        enableVpnDetection: false
    }
});

from complycube import ComplyCubeClient

cc_api = ComplyCubeClient(api_key="<YOUR_API_KEY>")

options = {
    enableEnrolledFaces: false,
    enableSpecimenMatching: false,
    enableVpnDetection: false,
}

check = cc_api.check.create(
    "CLIENT_ID",
    "identity_check",
    livePhotoId="LIVE_PHOTO_ID",
    documentId="DOCUMENT_ID",
    options=options,
)

use ComplyCube\ComplyCubeClient;

$ccapi = new ComplyCubeClient('<YOUR_API_KEY>');

$result = $ccapi->checks()->create(
    'CLIENT_ID',
    [
        'type' => 'identity_check',
        'livePhotoId' => 'LIVE_PHOTO_ID',
        'documentId' => 'DOCUMENT_ID',
        'options' => [
               'enableEnrolledFaces' => false,
               'enableSpecimenMatching' => false,
               'enableVpnDetection' => false
              ]
    ]
);

using ComplyCube.Net;
using ComplyCube.Net.Resources.Checks;

var checkApi = new CheckApi(new ComplyCubeClient("<YOUR_API_KEY>"));

var checkRequest = new CheckRequest {
  clientId = "CLIENT_ID",
  documentId = "DOCUMENT_ID",
  livePhotoId = "LIVE_PHOTO_ID",
  type = "identity_check"
};

checkRequest.options = new CheckRequestOptions {
  enableEnrolledFaces = false,
  enableSpecimenMatching = false,
  enableVpnDetection = false,
};

var check = await checkApi.CreateAsync(checkRequest);

Result object

The result object is only returned when the status of the check is complete . It has two components - outcome and breakdown.

Outcome

The outcome attribute represents the overall check result. Returned values include:

clear: Indicates every analysis conducted returned a successful result, and hence the identity is authentic.
attention: Indicates at least one of the analysis results requires attention.

Breakdown

The breakdown comprises the following objects:

`faceAnalysis` object

The facial analysis results. It has the following constituents:

faceDetection: Indicates whether a face is detected and that number of faces detected on the ID and live photo are valid.
facialSimilarity: Indicates whether the faces on the live photo and document belong to the same person.
previouslyEnrolledFace: Indicates whether the face on the live photo has been previously enrolled as a different client.
breakdown: Breakdown related to facial analysis.
- facialSimilarityScore: Indicates the similarity level of whether two faces belong to the same person. The score will be 100 for a perfect match.
- enrolledFacesMatches: If a face is deemed to have been enrolled previously, this will contain an array of objects that contain the following:
  - clientId: The unique identifier for the matching client.
  - entityName: The client's full name.
  - livePhotoId: The unique identifier for the matching live photo.
  - liveVideoId: The unique identifier for the matching live video. Either a liveVideoId or livePhotoId will exist in the object, not both.
  - facialSimilarityScore: The similarity level of the client's face against the live photo associated with the check.

`authenticityAnalysis` object

The facial analysis results. It has the following constituents:

spoofedImageAnalysis: Indicates whether the images are spoofed, copied from the internet, or are known blacklisted images.
livenessCheck: Indicates if the live photo is genuine and not a photo-of-an-image or photo-of-a-screen.
breakdown: Breakdown related to authenticity analysis.
- specimenCheckMatches: If an image is deemed copied from the internet, this will contain an array of URLs pointing to the image.
- livenessCheckScore: Indicates the liveness score of the live photo. The score will be 100 when it is assumed to be authentic.

`integrityAnalysis` object

The integrity analysis results. It has the following constituents:

faceDetection: Indicates whether the images contained the expected number of faces.
vpnDetected: Indicates whether the client was using a Virtual Private Network (VPN) when conducting the check.

Sample Response

{
   "id": "5e94b88a01bce00008c86f06",
   "entityName": "John Doe",
   "type": "identity_check",
   "clientId": "5e94b75d01bce00008c86f02",
   "documentId": "5e94b87b01bce00008c86f03",
   "livePhotoId": "5e94b88901bce00008c86f05",
   "status": "complete",
   "result": {
      "outcome": "clear",
      "breakdown": {
         "faceAnalysis": {
            "faceDetection": "clear",
            "facialSimilarity": "clear",
            "previouslyEnrolledFace": "clear",
            "breakdown": {
               "facialSimilarityScore": 100
            }
         },
         "authenticityAnalysis": {
            "spoofedImageAnalysis": "clear",
            "livenessCheck": "clear",
            "breakdown": {
               "livenessCheckScore": 100
            }
         },
         "integrityAnalysis": {
            "faceDetection": "clear",
            "vpnDetected": "clear"
         }
      }
   },
   "createdAt": "2020-01-04T17:25:21.116Z",
   "updatedAt": "2020-01-04T17:25:21.116Z"
}

PreviousDocument Check NextEnhanced Identity Check

Last updated 7 months ago

Run an identity check

Check request

The options object

Example request

Simple request

Request with optional attributes

Result object

Outcome

Breakdown

faceAnalysis object

authenticityAnalysis object

integrityAnalysis object

Sample Response

The `options` object

`faceAnalysis` object

`authenticityAnalysis` object

`integrityAnalysis` object