---
title: "Create an attempt"
method: POST
path: "/v2/face-authentications/{face_authentication_id}/attempts"
tags: ["Face authentications"]
---

# Create an attempt

`POST /v2/face-authentications/{face_authentication_id}/attempts`

## Request

- Base URL: `https://api.ubble.ai`
- URL: `https://api.ubble.ai/v2/face-authentications/{face_authentication_id}/attempts`
- Auth: none declared
- TypeScript: <https://skmtc.dev/ubble/apis/checkout-com-identity-verification/docs/v2/face-authentications/:face_authentication_id/attempts/post.ts> (a function with typed inputs; its response is checked against the schema)

This endpoint allows you to create a new Attempt. It is possible when the face-authentication is in one of the following statuses `created`, `pending`, `capture_in_progress`, `retry_required`

## Path parameters

- `face_authentication_id` string, required

## Request body

- FaceAuthenticationAttemptInputPost
  - `phone_number` PhoneNumber
    - `country_code` string, international phone prefix, required
    - `number` string, domestic phone number, required
  - `client_information` FaceAttemptClientInformation
    - `pre_selected_residence_country` string, ISO 3166-1 alpha-2
    - `pre_selected_language` string, IETF BCP 47 language tag: Language tag following IETF BCP 47 standard
  - `redirect_url` string, uri
  - `mobile_handoff_url` string, uri, nullable: Optional. URL encoded in the QR code shown when the verification is opened on a desktop, so the end user can continue on their phone through your own flow. Defaults to the verification URL. Accepts https URLs and app deeplinks. Max 512 characters.

## Response `201`

Attempt created

- FaceAuthenticationAttemptOutputPost
  - `id` string
  - `status` 'pending_redirection' | 'capture_in_progress' | 'checks_in_progress' | 'completed' | 'expired' | 'capture_aborted' | 'capture_refused' | 'checks_inconclusive' | 'terminated': States of an attempt.
  - `response_codes` ResponseCodes[]
    - `code` integer, required: The numeric code of the response code.
    - `summary` string, required: A descriptive code of the response code.
  - `applicant_session_information` FaceAuthenticationApplicantSessionInformation
    - `ip_address` string: Ip address of the applicant during the session
    - `number_of_sessions` integer: Number of sessions opened by user
    - `user_agent` string: User session user agent
    - `initial_device` 'mobile' | 'desktop': Initial device which started the session
  - `_links` AttemptLinks
    - `verification_url` HalLink, required
      - `href` string, uri, required
    - `self` HalLink, required
      - `href` string, uri, required
  - `created_on` string, date-time, required: UTC Date time when the resource was created
  - `modified_on` string, date-time, required: UTC Date time when the resource was modified
  - `phone_number` PhoneNumber
    - `country_code` string, international phone prefix, required
    - `number` string, domestic phone number, required
  - `client_information` FaceAttemptClientInformation
    - `pre_selected_residence_country` string, ISO 3166-1 alpha-2
    - `pre_selected_language` string, IETF BCP 47 language tag: Language tag following IETF BCP 47 standard
  - `redirect_url` string, uri
  - `mobile_handoff_url` string, uri, nullable: Optional. URL encoded in the QR code shown when the verification is opened on a desktop, so the end user can continue on their phone through your own flow. Defaults to the verification URL. Accepts https URLs and app deeplinks. Max 512 characters.

## Other responses

- `404`: The provided face authentication ID is not valid
- `409`: The current face authentication status does not allow the creation of a new attempt. The face authentication status must be either `created`, `pending`, `capture_in_progress`, or `retry_required`
- `500`: An error occurred while creating the attempt

---

[API](https://skmtc.dev/ubble/apis/checkout-com-identity-verification.md) - [All operations](https://skmtc.dev/ubble/apis/checkout-com-identity-verification/llms.txt) - [OpenAPI document](https://skmtc.dev/ubble/apis/checkout-com-identity-verification/revisions/739e9da12584?raw)