Verification Statuses

Status Descriptions

We return a status at the top-level of our API responses describing the outcome of each verification session. The possible values, along with their meanings, are listed below.

Within the dashboard, these statuses are referred to by the values in the "Status" column.

Type: Required string enum (never null)

When populated: Always populated from the moment of session creation. The status field is required.

Example

"status": "canceled"

Status	Description	Terminal Status
`success`	The session is complete and the user was passed according to your project.	Yes. Unless marked as Manual Fail.
`fail`	The session is complete and the user was rejected according to your project.	Yes. Unless marked as Manual Pass.
`deferred`	A final decision could not be made. One or more required checks returned “Indeterminate” or “Awaiting Async Response”, so the session did not return a determinate result.	Yes. Unless marked as Manual Pass.
`awaiting_user_input`	The session is not complete and there is some piece of user information CLEAR still needs to collect.	No. Listen to events via webhooks to get updates on this verification session.
`processing_data`	The session is not complete yet and CLEAR is processing the user's data.	No. Listen to events via webhooks to get updates on this verification session.
`expired`	The session is not complete, is expired, and cannot accept any more data. By default, verification sessions expire after 10 days, but the length of time is configurable.	Yes
`awaiting_manual_review`	The session is complete and awaiting manual review.	Yes. Upon review, session may change to Manual Pass or Manual Fail.
`manual_success`	The session is complete, was sent to manual review, and was set to pass by a human reviewer.	Yes
`manual_fail`	The session is complete, was sent to manual review, and was set to fail by a human reviewer.	Yes
`canceled`	The "Canceled" status represents a user who has actively chosen to exit the verification session before providing any data, or a user who was ineligible to start a verification (e.g. IP blocklist)	Yes

Status Details Descriptions

status_details is an optional contextual qualifier that provides the specific reason why a verification session ended in a particular terminal state. While the status field tells you what happened (e.g., "fail", "canceled"), the status_details field tells you why it happened (e.g., "blocked_by_provider", "ineligible").

📘
status_details are only available in the Get Verification Session endpoint. They are not returned in the access or identity token of the OAuth integration.

Type: Optional string enum (can be null)

When populated: Only when a verification session reaches certain terminal state that have associated failure/cancellation reasons.

Example

"status_details": "authentication_error"

Status Details	Description	Mapped Status	Retry Behavior
`ineligible`	The user is not eligible to be verified by CLEAR based on parameters set by the project configuration.	`canceled`	Must contact CLEAR or use different project.
`ip_blocked`	The user's IP location is blocked by the project configuration.	`canceled`	Must use different network/location.
`error_creating_clear_member`	User account could not be confirmed. Direct user to contact CLEAR support for resolution.	`fail`	Contact CLEAR support.
`authentication_error`	The user's authentication attempt failed due to various technical or biometric issues. This is a catch-all for authentication failures that aren't related to user cancellation. ^1	`fail` or `canceled`	Create new session to retry or contact CLEAR support.
`blocked_by_provider`	This status occurs when a third-party SMS/OTP provider actively blocks the delivery of an OTP to the user's phone number due to various security or technical restrictions. ^2	`fail`	Try different phone or auth method.

Authentication Errors
1. Biometric/Selfie Authentication Failures:
  1. User's selfie doesn't match the biometric data on file
  2. No biometric portrait found in the CLEAR database
  3. Liveness check fails (selfie appears to be a photo of a photo, etc.)
  4. Multiple failed selfie attempts
2. OTP/SMS Authentication Issues:
  1. OTP provider returns an error (that isn't a provider block)
  2. Technical errors during OTP delivery
3. authentication_canceled (also returns authentication_error in status details)
  1. Authentication was canceled due to missing biometric data
  2. User attempted biometric authentication but no portrait/biometric data exists in their CLEAR account
  3. Distinct from a general authentication failure
  4. Final overall status will be canceled (not fail)
Blocked by Provider
1. Geo-Permissions block
  1. Verification cannot proceed because this phone number's region is not supported for SMS verification.
2. Region not available
  1. Verification cannot proceed because this phone number is from a region that is not supported.
3. Landline number
  1. User provided a phone number that cannot receive SMS OTPs (e.g., landline).
4. Rate limit exceeded
  1. Too many OTP delivery requests were made in a short period, and further messages were temporarily blocked.
5. Fraud guard block
  1. Verification attempt blocked due to a security safeguard. The system flagged this request as potentially unusual.
6. Invalid mobile number
  1. Phone number is not a valid mobile number
7. Daily message cap
  1. Daily message cap reached

🚧
Exception Handling Note
The only edge case is if a session expires while in awaiting user input, it can transition to status: "expired"without having a status_details value. But once status_details is populated, the session is definitively terminal.