> For the complete documentation index, see [llms.txt](/docs/llms.txt)

# Identity Verify API | FusionAuth Docs

Learn about the APIs for starting, sending, and completing identity verification.

# Identity Verify API

Available since `1.59.0`

The identity verification APIs allow you to manage a workflow for verifying a user's identity, including both email address and phone number. Unlike the [Verify Email](/docs/apis/users/verify-email) API, which verifies an existing user's email, Identity Verify can be used to verify an identity (email address and phone number) before creating the user.

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 an 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 identity verification is handled automatically by FusionAuth. The main verification use cases and the applicability of the API are shown below.

| Use Case | Start API | Send API | Complete API |
| --- | --- | --- | --- |
| **User creation** | Automatic | Automatic | N/A |
| **User update** | Automatic | Automatic | N/A |
| **Hosted Pages - login** | N/A | N/A | Automatic |
| **Hosted Pages - resend verification** | Automatic | Automatic | N/A |
| **Login API** | N/A | N/A | Yes\* |
| **Login API - resending verification emails or SMS messages** | Yes | Yes | N/A |
| **Verifying identities before user creation** | Yes | Yes | Yes |

\* 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.

For tutorials on verifying identities before user creation using hosted pages with Advanced Registration Forms, see:

*   [Identity Pre-Verification Using Email](/docs/lifecycle/manage-users/verification/identity-pre-verification-using-email)
*   [Identity Pre-Verification Using Phone](/docs/lifecycle/manage-users/verification/identity-pre-verification-using-phone)

## Start Identity Verification[#](#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](#send-identity-verification), or can be delivered by some other method of your choosing. The User will then use this code to complete the verification process. This API can also be used to verify an identity before creating a user.

### Request[#](#request)

Start identity verification

POST/api/identity/verify/start

OpenAPI Spec

#### Request Headers[#](#request-headers)

`X-FusionAuth-TenantId`Stringoptional

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](/docs/apis/authentication#making-an-api-request-using-a-tenant-id) for additional information.

#### Request Body[#](#request-body)

`loginId`Stringrequired

The login identifier of the User identity to begin verification for.

The possible values are:

*   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.

`loginIdType`Stringrequired

The identity type that FusionAuth will use when comparing the **loginId**.

The possible values are:

*   `email`
*   `phoneNumber`

`applicationId`UUIDoptional

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.

`existingUserStrategy`StringoptionalDefaults to mustExistAvailable since 1.62.0

Whether an existing user that matches **loginId** is required.

The possible values are:

*   `mustExist` - There must be a user that matches. Use this to verify an existing user's identity.
*   `mustNotExist` - There must NOT be a user that matches. Use this to verify the identity for a user who does not yet exist.

`state`Objectoptional

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

`verificationStrategy`StringoptionalDefaults to tenant value

The strategy to use when verifying the User.

The possible values are:

*   `ClickableLink` - Sends a link the User can click to verify their identity.
*   `FormField` - Sends 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)

*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](/docs/apis/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](/docs/apis/authentication). |
| 404 | If the request had an existingUserStrategy value of mustExist and the loginId did not match a user in the selected tenant. |
| 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[#](#response-body)

`verificationId`String

The verification Id that was generated by this API request. This identifier should be used by the [Complete Identity Verification](#complete-identity-verification) API and may be used by the [Send Identity Verification](#send-identity-verification) API.

`oneTimeCode`Stringoptional

The verification One Time Code is used with the gated Email or Phone Verification workflow. The User enters this code to verify their email address 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[#](#send-identity-verification)

This API allows you to send a verification code, previously generated by the [Start Identity Verification API](#start-identity-verification), 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[#](#request-1)

Send identity verification

POST/api/identity/verify/send

OpenAPI Spec

#### Request Headers[#](#request-headers)

`X-FusionAuth-TenantId`Stringoptional

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](/docs/apis/authentication#making-an-api-request-using-a-tenant-id) for additional information.

#### Request Body[#](#request-body-1)

`verificationId`Stringrequired

The verification Id that was generated by the start API.

### Response[#](#response-1)

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](/docs/apis/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](/docs/apis/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[#](#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`.

If the [Start Identity Verification API](#start-identity-verification) was called with a **existingUserStrategy** value of `mustNotExist`, then this API will mark the **verificationId** as verification complete. The verification Id can then be used to create a user with the already verified identity using the [User API](/docs/apis/users/create) or [Registration API](/docs/apis/registrations/create-a-user-and-registration-combined).

### Request[#](#request-2)

Complete identity verification

POST/api/identity/verify/complete

OpenAPI Spec

#### Request Headers[#](#request-headers)

`X-FusionAuth-TenantId`Stringoptional

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](/docs/apis/authentication#making-an-api-request-using-a-tenant-id) for additional information.

#### Request Body[#](#request-body-2)

`verificationId`Stringrequired

The verification Id generated by the [Start Identity Verification API](#start-identity-verification), 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.

`oneTimeCode`Stringoptional

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-2)

*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](/docs/apis/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](/docs/apis/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[#](#response-body-1)

`state`Object

If **state** was provided during the [Start Identity Verification API](#start-identity-verification) request, this value will be returned exactly as it was provided.

*Example Response JSON*

```
{}
```

*Example Response JSON with state*

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