Logo / Docs

Identity Verify

Overview

This API has been available since 1.59.0

The identity verification APIs allow you to manage a workflow for verifying a user’s identity. This API is similar to the Verify Email API.

An identity verification workflow involves three steps:

  1. Starting the verification process, which generates a verification code
  2. Delivering the code to a user in a way that is specific to the identity (e.g. sending and email to an email address, or an SMS message to a phone number)
  3. Having the user complete the verification workflow by presenting the code

In general you will not need to call these APIs directly, as most of identity verification is handled automatically by FusionAuth. The main verification use cases and the applicability of the API are shown below.

Use CaseStart APISend APIComplete API
User creationAutomaticAutomaticN/A
User updateAutomaticAutomaticN/A
Hosted Pages - loginN/AN/AAutomatic
Hosted Pages - resend verificationAutomaticAutomaticN/A
Login APIN/AN/AYes*
Login API - resending verification emails or SMS messagesYesYesN/A

* You will need to use the Complete API if you want to use FormField verification or if you don’t want to use FusionAuth’s ClickableLink page.

Start Identity Verification

This API allows you to generate a verification code for a User’s identity. This code can be sent to the User via email or SMS using the Send Identity Verification API, or can be delivered by some other method of your choosing. The User will then use this code to complete the verification process.

Request

API Key Authentication
Start identity verification
POST /api/identity/verify/start

Request Headers

X-FusionAuth-TenantIdString

The unique Id of the tenant used to scope this API request.

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Request Body

loginIdStringrequired

The login identifier of the User identity to begin verification for. The login identifier can be one of the following:

  • Email address
  • Phone number

For email , the value will be used exactly as provided to resolve a User. If the provided value contains leading or trailing white space, these characters will not be removed, and then would only match if the values stored in FusionAuth also contain these same leading or trailing spaces.

For phoneNumber , loginId can be any valid phone number (in E.164, national, or international format) and FusionAuth will canonicalize the value. The User will be resolved if the User’s E.164 formatted phone number matches the canonical E.164 phone number from loginId . If no country code is provided, a US/NANP country code of 1 is assumed.

loginIdTypeStringrequired

The identity type that FusionAuth will use when comparing the loginId . Can be one of the following:

  • email
  • phoneNumber
applicationIdUUID

An application Id. If this is not provided and there are multiple tenants, the X-FusionAuth-TenantId header is required.

When this value is provided, it will be used to resolve an application-specific email or message template and make application available as a template variable.

If not provided, only the tenant configuration will be used when resolving templates, and application will not be available as a template variable.

stateObject

An optional object that will be returned un-modified when you complete verification. This may be useful to return the User to particular state once verification is completed.

verificationStrategyStringDefaults to tenant value

The strategy to use when verifying the User. Can be one of the following:

  • ClickableLink - send the User a code with a clickable link.
  • FormField - send the User a short code intended to be manually entered into a form field

The default, when loginIdType is email, is tenant.emailConfiguration.verificationStrategy . When loginIdType is phoneNumber, the default is tenant.phoneConfiguration.verificationStrategy .

Response

Response Codes
Code Description
200 The request was successful. The response will contain a JSON body.
400 The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401 You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
500 There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body

verificationIdString

The verification Id that was generated by this API request. This identifier should be used by the Complete Identity Verification API and may be used by the Send Identity Verification API.

oneTimeCodeString

The verification One Time Code is used with the gated Email or Phone Verification workflow. The User enters this code to verify their email or phone number when the ClickableLink strategy is not in use.

This is only returned if the effective verification strategy is FormField, which is determined by the tenant configuration or the verificationStrategy field, if it was used in the request.

Example Response JSON

{
  "verificationId": "EdxLRUIQvmqrv1UCQWme-8Ttt8VDUX0S7ZzYmoWI3ZU"
}

Example Response JSON with oneTimeCode

{
  "verificationId": "EdxLRUIQvmqrv1UCQWme-8Ttt8VDUX0S7ZzYmoWI3ZU",
  "oneTimeCode": "8RHLVK"
}

Send Identity Verification

This API allows you to send a verification code, previously generated by the Start Identity Verification API, to a User via email or SMS. This is typically used to notify the User that they need to verify their identity.

If the verificationId was generated for:

  • an email identity - the message will be sent via email using the SMTP settings for the user’s tenant and the message template defined by tenant.emailConfiguration.verificationEmailTemplateId
  • a phone number identity - the message will be sent via SMS using the message template defined by tenant.phoneConfiguration.verificationTemplateId and the messenger defined by tenant.phoneConfiguration.messengerId

Request

API Key Authentication
Send identity verification
POST /api/identity/verify/send

Request Headers

X-FusionAuth-TenantIdString

The unique Id of the tenant used to scope this API request.

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Request Body

verificationIdStringrequired

The verification Id that was generated by the start API.

Response

This API does not return a JSON response body.

Response Codes
Code Description
200 The request was successful. The response will be empty.
400 The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401 You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
500 There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Complete Identity Verification

This API allows you to complete the identity verification process by providing the verification code sent to the User. If the code is valid, the User’s identity will be verified and user.identities[x].verifiedReason will be set to Completed.

Request

API Key Authentication
Complete identity verification
POST /api/identity/verify/complete

Request Headers

X-FusionAuth-TenantIdString

The unique Id of the tenant used to scope this API request.

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Request Body

verificationIdStringrequired

The verification Id generated by the Start Identity Verification API, used to verify the User’s identity is valid by ensuring they have access to the provided email address or phone number.

When using the FormField strategy for verification, this value is used along with the oneTimeCode as a pair to perform verification.

oneTimeCodeString

The short code used to verify the User’s account is valid by ensuring they have access to the provided email address or phone number. This field is required when the verification strategy is FormField.

Response

Response Codes
Code Description
200 The request was successful. The response will contain a JSON body.
400 The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401 You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
500 There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body

stateObject

If state was provided during the Start Identity Verification API request, this value will be returned exactly as it was provided.

Example Response JSON

{}

Example Response JSON with state

{
  "state": {
    "abc": 123
  }
}