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

# Identity Pre-Verification Via API | FusionAuth Docs

Verify email or phone identities entirely via API without using hosted pages.

# Identity Pre-Verification Via API

[Edit on GitHub](https://github.com/FusionAuth/fusionauth-site/blob/main/astro/src/content/docs/lifecycle/manage-users/verification/identity-pre-verification-via-api.mdx)

[View Markdown](https://fusionauth.io/docs/lifecycle/manage-users/verification/identity-pre-verification-via-api.md)

This guide shows how to verify a user's email or phone identity using FusionAuth APIs only, without hosted pages and Advanced Registration Forms. You will:

1.  Start an identity verification flow
2.  Optionally send a code to the user
3.  Complete verification with the code (or via clickable link)
4.  Create the user using the returned verificationId

If you're looking for the hosted pages version with Advanced Registration Forms, see:

*   [Identity Pre-Verification Using Email](https://fusionauth.io/docs/lifecycle/manage-users/verification/identity-pre-verification-using-email.md)
*   [Identity Pre-Verification Using Phone](https://fusionauth.io/docs/lifecycle/manage-users/verification/identity-pre-verification-using-phone.md)

## Prerequisites[#](#prerequisites)

Before you begin, ensure your environment meets these requirements. This guide assumes you are running FusionAuth version 1.62.0 or greater. If you aren't, head on over to the [installation guide](https://fusionauth.io/docs/get-started/download-and-install.md) or the [upgrade guide](https://fusionauth.io/docs/operate/deploy/upgrade.md) to update to a version with support for this feature.

Email/Phone Verification and identity pre-verification are not premium features; however, enforcing pre-verification with Advanced Registration Forms as well as Gating is. If you are following this guide implementing pre-verification entirely via API, you can still build equivalent gating in your application logic. See the [hosted pages](https://fusionauth.io/docs/get-started/core-concepts/hosted-login-vs-api-login.md#hosted-login-pages) guides if you prefer FusionAuth to enforce gating for you.

## General Flow[#](#general-flow)

Identity pre-verification follows these steps:

1.  Start Verification Flow
    
    *   POST /api/identity/verify/start
    *   Provide the identity value in **loginId** and the type in **loginIdType** (`email` or `phoneNumber`).
    *   For pre-verifying identities before user creation, set **existingUserStrategy** to `mustNotExist`.
    *   The response includes a **verificationId** and may include a **oneTimeCode** if using the `FormField` strategy.
2.  Send Code (optional)
    
    *   POST /api/identity/verify/send
    *   Provide the **verificationId**. Use this if you want FusionAuth to send the email or SMS containing the code or clickable link.
3.  Complete Verification
    
    *   POST /api/identity/verify/complete
    *   Provide the **verificationId** and, if using the `FormField` strategy, the **oneTimeCode**.
    *   If the strategy is `ClickableLink`, you can validate using just the **verificationId** (the user clicks the link).
4.  Create the User
    
    *   POST /api/user or /api/user/registration
    *   Include the **verificationIds** array from step 1 associated with the verified identity.

**existingUserStrategy** values are lowercase: `mustExist` and `mustNotExist`.

The default **verificationStrategy** depends on your tenant configuration:

*   email: `tenant.emailConfiguration.verificationStrategy`
*   phone: `tenant.phoneConfiguration.verificationStrategy`

Both are set to either `ClickableLink` or `FormField`.

For full details, see the [Identity Verify API](https://fusionauth.io/docs/apis/identity-verify.md).

## Executing Flow Using Postman[#](#executing-flow-using-postman)

Use these Postman examples to try each step of the API-only flow in a local or test environment.

These examples assume a local FusionAuth instance at [http://localhost:9011](http://localhost:9011) and that you're sending an [API key in the headers](https://fusionauth.io/docs/apis/authentication.md) as required by your configuration. Adjust host, tenant header, and authorization to match your environment.

### 1\. Start Verification Flow[#](#1-start-verification-flow)

Start by creating a verification to obtain a `verificationId` and, if processed in one step, a `oneTimeCode`.

*   URL: [http://localhost:9011/api/identity/verify/start](http://localhost:9011/api/identity/verify/start)
*   Method: POST
*   Body:
    
    ```json
    {
      "existingUserStrategy": "mustNotExist",
      "loginId": "testuser20@example.com",
      "loginIdType": "email"
    }
    ```
    

Example result:

```json
{
  "oneTimeCode": "ZLB632",
  "verificationId": "eIXDJDjMYOrcAEPDHdlnzVGIXE1kzjogdiJDBZLLxJg"
}
```

**existingUserStrategy** can be `mustNotExist` or `mustExist`. The default **verificationStrategy** comes from the tenant settings and may be `FormField` or `ClickableLink`.

For complete parameter and response details, refer to [Start Identity Verification](https://fusionauth.io/docs/apis/identity-verify.md#start-identity-verification).

### 2\. Send Code (optional)[#](#2-send-code-optional)

Optionally have FusionAuth deliver the verification code or clickable link to the user. If you already received a **oneTimeCode** from Start and have another method to deliver it to the user, you may skip sending.

*   URL: [http://localhost:9011/api/identity/verify/send](http://localhost:9011/api/identity/verify/send)
*   Method: POST
*   Body:
    
    ```json
    {
      "verificationId": "eIXDJDjMYOrcAEPDHdlnzVGIXE1kzjogdiJDBZLLxJg"
    }
    ```
    

Example result: HTTP 200 with an empty body.

If you want FusionAuth to send the email or SMS message, call this endpoint to deliver the code or clickable link. Before calling this endpoint, configure the prerequisite email server and messenger settings:

*   [Email servers](https://fusionauth.io/docs/customize/email-and-messages/configure-email.md)
*   [Messengers](https://fusionauth.io/docs/customize/email-and-messages/messengers.md)

For complete parameter and response details, refer to [Send Identity Verification](https://fusionauth.io/docs/apis/identity-verify.md#send-identity-verification)

### 3\. Complete Verification[#](#3-complete-verification)

Confirm the user's control of the email address or phone number using the `verificationId` and, if required, the `oneTimeCode`.

*   URL: [http://localhost:9011/api/identity/verify/complete](http://localhost:9011/api/identity/verify/complete)
*   Method: POST
*   Body (FormField strategy):
    
    ```json
    {
      "verificationId": "eIXDJDjMYOrcAEPDHdlnzVGIXE1kzjogdiJDBZLLxJg",
      "oneTimeCode": "ZLB632"
    }
    ```
    

Example result:

```json
{}
```

If the **verificationStrategy** is `ClickableLink`, completing can be done when the user clicks the link sent to them. In that case, completing with just the **verificationId** will validate the user.

For complete parameter and response details, refer to [Complete Identity Verification](https://fusionauth.io/docs/apis/identity-verify.md#complete-identity-verification)

### 4\. Create the User[#](#4-create-the-user)

Create the user and associate the verified identity using the `verificationIds` from the previous steps.

*   URL: [http://localhost:9011/api/user](http://localhost:9011/api/user)
*   Method: POST
*   Body:
    
    ```json
    {
      "verificationIds": [
        "eIXDJDjMYOrcAEPDHdlnzVGIXE1kzjogdiJDBZLLxJg"
      ]
    }
    ```
    

Example result: user object where the corresponding identity is marked `verified: true`.

For complete parameter and response details, refer to [Create a User](https://fusionauth.io/docs/apis/users/create.md)

Alternatively, you can create the user and registration in a single API call: [Create a User and Registration Combined](https://fusionauth.io/docs/apis/registrations/create-a-user-and-registration-combined.md)

## Test It Out[#](#test-it-out)

Validate the outcome in the FusionAuth admin UI.

![The Application details page with the Self-service registration URL](https://fusionauth.io/img/docs/lifecycle/manage-users/verification/identity-pre-verification-application-details.png)

You can validate the email or phone verification status by viewing the user in the admin UI by navigating to Users -> \[select user\] -> Manage . A verified email address or phone number displays a green checkmark icon next to the address.

![Identity verification settings for Email and Phone in the Tenant configuration](https://fusionauth.io/img/docs/lifecycle/manage-users/verification/identity-pre-verification-user-email-and-phoneNumber-verified.png)

## Tips and Caveats[#](#tips-and-caveats)

Keep the following practical tips and edge cases in mind as you implement this flow.

*   Use `mustNotExist` when verifying identities before creating users; use `mustExist` to verify an identity for an existing user.
*   If you choose `FormField`, plan for collecting and submitting the code from the user. If you choose `ClickableLink`, ensure the link is routable for the user and that your tenant/application templates are configured.
*   For email, ensure your tenant SMTP settings are configured. For phone, ensure a messenger (for example, Twilio) is configured if you plan to call the Send API.
*   If you are running multiple tenants, include the `X-FusionAuth-TenantId` header or provide `applicationId` as appropriate. See the API docs for scoping details.

For complete parameter and response details, refer to the Identity Verify API docs:

*   [Start Identity Verification](https://fusionauth.io/docs/apis/identity-verify.md#start-identity-verification)
*   [Send Identity Verification](https://fusionauth.io/docs/apis/identity-verify.md#send-identity-verification)
*   [Complete Identity Verification](https://fusionauth.io/docs/apis/identity-verify.md#complete-identity-verification)

## Next Steps[#](#next-steps)

Now that you've successfully set up identity pre-verification, refine your verification experience with the following customization:

*   [Customize email templates](https://fusionauth.io/docs/customize/email-and-messages/email-templates-replacement-variables.md)
*   [Customize message templates](https://fusionauth.io/docs/customize/email-and-messages/message-templates-replacement-variables.md)