Face Authentication

Create a face authentication

Beta

Create a face authentication for an applicant you've previously verified using the Identity Verification solution.

Ensure you use your Face Authentication configuration ID.

SecurityOAuth2: OAuth or API Key: ApiSecretKey

Request

Request Body schema: application/json
required

applicant_id required	string^aplt_\w+$ The applicant's unique identifier.
user_journey_id required	string^usj_[a-z2-7]{26}$ Your configuration ID.

Responses

201

Face authentication created successfully

400

Bad Request

401

Unauthorized

422

Unprocessable Content

500

Internal Server Error

503

Service Unavailable

post/face-authentications

Request samples

Payload
curl
Java
C#
Python

application/json

{"user_journey_id": "usj_t5bdzsdmi57ehhkrnmp5omjimu",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we"
}

Response samples

application/json

{"id": "fav_mtta050yudd54y5iqb5ijh8jtvz",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
"status": "created",
"response_codes": [ ],
"risk_labels": [ ],
"_links": {"self": {"href": "https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz"
},
"applicant": {"href": "https://identity-verification.checkout.com/applicants/aplt_lkoi5db4hryu5cei5vwoabqere"
}
}
}

Get a face authentication

Beta

Get the details of a face authentication.

SecurityOAuth2: OAuth or API Key: ApiSecretKey

Request

path Parameters

face_authentication_id

required

string (FavFaceAuthenticationId) ^fav_\w+$

The face authentication's unique identifier.

Example: fav_mtta050yudd54y5iqb5ijh8jtvz

Responses

200

Face authentication retrieved successfully

401

Unauthorized

500

Internal Server Error

503

Service Unavailable

get/face-authentications/{face_authentication_id}

Request samples

curl
Java
C#
Python

Response samples

application/json

{"id": "fav_mtta050yudd54y5iqb5ijh8jtvz",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_t5bdzsdmi57ehhkrnmp5omjimu",
"status": "approved",
"response_codes": [{"code": 10000,
"summary": "approved"
}
],
"risk_labels": ["multiple_faces_detected"
],
"face": {"image_signed_url": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
},
"_links": {"self": {"href": "https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz"
},
"applicant": {"href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7ou"
}
}
}

Anonymize a face authentication

Beta

Remove the personal data in a face authentication.

SecurityOAuth2: OAuth or API Key: ApiSecretKey

Request

path Parameters

face_authentication_id

required

string^fav_\w+$

The face authentication's unique identifier.

Example: fav_mtta050yudd54y5iqb5ijh8jtvz

Responses

200

Personal data removed successfully

401

Unauthorized

404

Not Found

422

Unprocessable Content

500

Internal Server Error

503

Service Unavailable

post/face-authentications/{face_authentication_id}/anonymize

Request samples

curl
Java
C#
Python

Response samples

application/json

{"id": "fav_mtta050yudd54y5iqb5ijh8jtvz",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
"user_journey_id": "usj_t5bdzsdmi57ehhkrnmp5omjimu",
"status": "approved",
"response_codes": [{"code": 10000,
"summary": "approved"
}
],
"risk_labels": ["multiple_faces_detected"
],
"_links": {"self": {"href": "https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz"
},
"applicant": {"href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7ou"
}
}
}

Create a face authentication attempt

Beta

Create an attempt for a face authentication.

If you've already created an attempt for this authentication, the authentication status must be one of the following:

created
pending
capture_in_progress
retry_required

If you create a new attempt while the status is any other value, you receive a 409 Conflict response.

SecurityOAuth2: OAuth or API Key: ApiSecretKey

Request

path Parameters

face_authentication_id

required

string^fav_\w+$

The face authentication's unique identifier.

Example: fav_mtta050yudd54y5iqb5ijh8jtvz

Request Body schema: application/json

redirect_url required	string <uri> The URL to redirect the applicant to after the attempt.
	object (ClientInformation) The applicant's details.

Responses

201

Face authentication attempt created successfully

404

Not Found

409

Conflict

500

Internal Server Error

post/face-authentications/{face_authentication_id}/attempts

Request samples

Payload
curl
Java
C#
Python

application/json

{"redirect_url": "https://myweb.site?query-param=hello"
}

Response samples

application/json

{"id": "fatp_nk1wbmmczqumwt95k3v39mhbh2w",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"client_information": {"pre_selected_residence_country": "FR",
"pre_selected_language": "en-US"
},
"redirect_url": "https://myweb.site?query-param=hello",
"status": "pending_redirection",
"response_codes": [ ],
"_links": {"verification_url": {"href": "https://idv.checkout.com/4hryu5cei5/"
},
"self": {"href": "https://identity-verification.sandbox.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts/fatp_nk1wbmmczqumwt95k3v39mhbh2w"
}
}
}

Get face authentication attempts

Beta

Get the details of all attempts for a specific face authentication.

SecurityOAuth2: OAuth or API Key: ApiSecretKey

Request

path Parameters

face_authentication_id

required

string^fav_\w+$

The face authentication's unique identifier.

Example: fav_mtta050yudd54y5iqb5ijh8jtvz

Responses

200

Face authentication attempts retrieved successfully

404

Not Found

500

Internal Server Error

get/face-authentications/{face_authentication_id}/attempts

Request samples

curl
Java
C#
Python

Response samples

application/json

{"total_count": 2,
"skip": 10,
"limit": 10,
"data": [{"id": "fatp_nk1wbmmczqumwt95k3v39mhbh2w",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"status": "completed",
"response_codes": [ ],
"redirect_url": "https://myweb.site?query-param=hello",
"_links": {"verification_url": {"href": "https://idv.checkout.com/4hryu5cei5/"
},
"self": {"href": "https://identity-verification.sandbox.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts/fatp_nk1wbmmczqumwt95k3v39mhbh2w"
}
}
}
],
"_links": {"self": {"href": "https://identity-verification.sandbox.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts"
},
"next": {"href": "https://identity-verification.sandbox.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts?..."
},
"previous": {"href": "https://identity-verification.sandbox.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts?..."
}
}
}

Get a face authentication attempt

Beta

Get the details of a specific attempt for a face authentication.

SecurityOAuth2: OAuth or API Key: ApiSecretKey

Request

path Parameters

face_authentication_id required	string^fav_\w+$ The face authentication's unique identifier. Example: fav_mtta050yudd54y5iqb5ijh8jtvz
attempt_id required	string^fatp_\w+$ The attempt's unique identifier. Example: fatp_nk1wbmmczqumwt95k3v39mhbh2w

Responses

200

Face authentication attempt retrieved successfully

404

Not Found

500

Internal Server Error

get/face-authentications/{face_authentication_id}/attempts/{attempt_id}

Request samples

curl
Java
C#
Python

Response samples

application/json

{"id": "fatp_nk1wbmmczqumwt95k3v39mhbh2w",
"created_on": "2025-07-21T17:32:28Z",
"modified_on": "2025-07-21T17:40:32Z",
"redirect_url": "https://myweb.site?query-param=hello",
"status": "capture_in_progress",
"client_information": {"pre_selected_residence_country": "FR",
"pre_selected_language": "en-US"
},
"applicant_session_information": {"ip_address": "123.123.123.01"
},
"response_codes": [ ],
"_links": {"verification_url": {"href": "https://idv.checkout.com/4hryu5cei5/"
},
"self": {"href": "https://identity-verification.sandbox.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts/fatp_nk1wbmmczqumwt95k3v39mhbh2w"
}
}
}

Get face authentication attempt assets

Beta

Get the assets (face images and videos) captured during a face authentication attempt.

Videos are not exposed by default. Contact your account manager to enable this feature.

Results are paginated. Use the skip and limit query parameters to navigate through pages.

SecurityOAuth2: OAuth or API Key: ApiSecretKey

Request

path Parameters

face_authentication_id required	string^fav_\w+$ The face authentication's unique identifier. Example: fav_mtta050yudd54y5iqb5ijh8jtvz
attempt_id required	string^fatp_\w+$ The attempt's unique identifier. Example: fatp_nk1wbmmczqumwt95k3v39mhbh2w

query Parameters

skip	integer Default: 0 The number of assets to skip.
limit	integer Default: 10 The maximum number of assets to return.

Responses

200

Face authentication attempt assets retrieved successfully

404

Not Found

500

Internal Server Error

get/face-authentications/{face_authentication_id}/attempts/{attempt_id}/assets

Request samples

curl
Java
C#
Python

Response samples

application/json

{"total_count": 2,
"skip": 0,
"limit": 10,
"data": [{"type": "face_image",
"_links": {"asset_url": {"href": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/face_image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600"
}
}
},
{"type": "face_video",
"_links": {"asset_url": {"href": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/face_video.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600"
}
}
}
],
"_links": {"self": {"href": "https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts/fatp_nk1wbmmczqumwt95k3v39mhbh2w/assets"
},
"next": {"href": "https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts/fatp_nk1wbmmczqumwt95k3v39mhbh2w/assets?..."
},
"previous": {"href": "https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts/fatp_nk1wbmmczqumwt95k3v39mhbh2w/assets?..."
}
}
}

➔ Next to ID Document Verification

Face Authentication

Create a face authentication

Request Body schema: application/jsonrequired

Get a face authentication

path Parameters

Anonymize a face authentication

path Parameters

Create a face authentication attempt

path Parameters

Request Body schema: application/json

Get face authentication attempts

path Parameters

Get a face authentication attempt

path Parameters

Get face authentication attempt assets

path Parameters

query Parameters

Request Body schema: application/json
required