Face Authentication

​
Face Authentication Operations

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.

Body·
required
application/json
  • Type: object
    • applicant_id
      Type: string · Pattern: ^aplt_\w+$
      required

      The applicant's unique identifier.

    • user_journey_id
      Type: string · Pattern: ^usj_[a-z2-7]{26}$
      required

      Your configuration ID.

Responses
  • application/json
  • application/json
  • 401

    Unauthorized

  • application/json
  • 500

    Internal Server Error

  • 503

    Service Unavailable

Request Example for post/face-authentications
curl https://identity-verification.checkout.com/face-authentications \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "user_journey_id": "usj_t5bdzsdmi57ehhkrnmp5omjimu",
  "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we"
}'

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

Face authentication created successfully

Get a face authentication

​

Beta

Get the details of a face authentication.

Path Parameters
  • face_authentication_id
    Type: string · Pattern: ^fav_\w+$
    read-only
    required

    The face authentication's unique identifier.

Responses
  • application/json
  • 401

    Unauthorized

  • 500

    Internal Server Error

  • 503

    Service Unavailable

Request Example for get/face-authentications/{face_authentication_id}
Shell Curl
curl https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

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

Face authentication retrieved successfully

Anonymize a face authentication

​

Beta

Remove the personal data in a face authentication.

Path Parameters
  • face_authentication_id
    Type: string Pattern: ^fav_\w+$
    required

    The face authentication's unique identifier.

Responses
  • application/json
  • 401

    Unauthorized

  • 404

    Not Found

  • application/json
  • 500

    Internal Server Error

  • 503

    Service Unavailable

Request Example for post/face-authentications/{face_authentication_id}/anonymize
Shell Curl
curl https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/anonymize \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

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

Personal data removed successfully

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.

Path Parameters
  • face_authentication_id
    Type: string Pattern: ^fav_\w+$
    required

    The face authentication's unique identifier.

Body·
application/json
  • redirect_url
    Type: string Format: uri
    required

    The URL to redirect the applicant to after the attempt.

  • phone_number
    Type: object ·

    The applicant's mobile phone number, if sharing the attempt URL via SMS.

  • client_information
    Type: object ·

    The applicant's details.

Responses
  • application/json
  • 404

    Not Found

  • 409

    Conflict

  • 500

    Internal Server Error

Request Example for post/face-authentications/{face_authentication_id}/attempts
curl https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "redirect_url": "https://myweb.site?query-param=hello"
}'

{
  "id": "fatp_nk1wbmmczqumwt95k3v39mhbh2w",
  "created_on": {},
  "modified_on": {},
  "phone_number": {
    "country_code": "+1",
    "number": "5555550102"
  },
  "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"
    }
  }
}

Face authentication attempt created successfully

Get face authentication attempts

​

Beta

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

Path Parameters
  • face_authentication_id
    Type: string Pattern: ^fav_\w+$
    required

    The face authentication's unique identifier.

Query Parameters
  • skip
    Type: integer

    The number of attempts to skip.

  • limit
    Type: integer

    The maximum number of attempts to return.

Responses
  • application/json
  • 404

    Not Found

  • 500

    Internal Server Error

Request Example for get/face-authentications/{face_authentication_id}/attempts
Shell Curl
curl https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "total_count": 2,
  "skip": 10,
  "limit": 10,
  "data": [
    {
      "id": "fatp_nk1wbmmczqumwt95k3v39mhbh2w",
      "created_on": {},
      "modified_on": {},
      "status": "completed",
      "response_codes": [],
      "phone_number": {
        "country_code": "+1",
        "number": "5555550102"
      },
      "client_information": {
        "pre_selected_residence_country": "FR",
        "pre_selected_language": "en-US"
      },
      "applicant_session_information": {
        "ip_address": "123.123.123.01",
        "number_of_sessions": 2,
        "user_agent": "Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36",
        "initial_device": "mobile"
      },
      "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?..."
    }
  }
}

Face authentication attempts retrieved successfully

Get a face authentication attempt

​

Beta

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

Path Parameters
  • face_authentication_id
    Type: string Pattern: ^fav_\w+$
    required

    The face authentication's unique identifier.

  • attempt_id
    Type: string Pattern: ^fatp_\w+$
    required

    The attempt's unique identifier.

Responses
  • application/json
  • 404

    Not Found

  • 500

    Internal Server Error

Request Example for get/face-authentications/{face_authentication_id}/attempts/{attempt_id}
Shell Curl
curl https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts/fatp_nk1wbmmczqumwt95k3v39mhbh2w \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "id": "fatp_nk1wbmmczqumwt95k3v39mhbh2w",
  "created_on": {},
  "modified_on": {},
  "redirect_url": "https://myweb.site?query-param=hello",
  "status": "capture_in_progress",
  "phone_number": {
    "country_code": "+1",
    "number": "5555550102"
  },
  "client_information": {
    "pre_selected_residence_country": "FR",
    "pre_selected_language": "en-US"
  },
  "applicant_session_information": {
    "ip_address": "123.123.123.01",
    "number_of_sessions": 2,
    "user_agent": "Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36",
    "initial_device": "mobile"
  },
  "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"
    }
  }
}

Face authentication attempt retrieved successfully

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.

Path Parameters
  • face_authentication_id
    Type: string Pattern: ^fav_\w+$
    required

    The face authentication's unique identifier.

  • attempt_id
    Type: string Pattern: ^fatp_\w+$
    required

    The attempt's unique identifier.

Query Parameters
  • skip
    Type: integer

    The number of assets to skip.

  • limit
    Type: integer

    The maximum number of assets to return.

Responses
  • application/json
  • 404

    Not Found

  • 500

    Internal Server Error

Request Example for get/face-authentications/{face_authentication_id}/attempts/{attempt_id}/assets
Shell Curl
curl https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts/fatp_nk1wbmmczqumwt95k3v39mhbh2w/assets \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "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?..."
    }
  }
}

Face authentication attempt assets retrieved successfully