# Verify Identity Steps via API

{{<notification message_top="**IMPORTANT!**: Consider using **Truora's** ready-to-use **Digital Identity** <a class='text-blue-600 hover:underline' href='/digital-identity/create_first_flow/'>**Web Integration**</a> before implementing your own front-end."
message_bottom="Our <a class='text-blue-600 hover:underline' href='/digital-identity/create_first_flow/'>**web integration**</a> is the recommended approach, providing a faster, more reliable, and easier solution for **identity verification**. It removes the complexity of handling API calls manually and ensures seamless compatibility with our platform.<br><br>This guide is intended only for advanced users who require full control over their front-end and are comfortable managing complex API requests. If you’re unsure, we strongly recommend starting with our <a class='text-blue-600 hover:underline' href='/digital-identity/create_first_flow/'>**web integration**</a> as your first option."
link=" " 
link_text=" ">}}

This guide explains how to use **Truora's API** to verify each step in an identity verification **process**, primarily through the **Verify Identity** endpoint along with other supporting endpoints. This API allows you to provide the required inputs for each step in the **processes** of your **flows**, enabling you to build a custom front-end when [Truora's ready-to-use solution](/digital-identity/create_first_flow/) does not meet your specific needs.

## Prerequisites

1. **Truora Account**: If you don't already have one, learn how to {{< newtab href="/digital-identity/account_set_up/" >}}Set up a Truora account{{< /newtab >}}.  
2. **Truora API-Key**: This key grants access to our services. If you don't have one already go to {{< newtab href="/digital-identity/authentication/" >}}Create Truora API-Key{{< /newtab >}}.  
3. **A created Web Flows**: Understand and have at least one flow already built. Learn how to {{< newtab href="/digital-identity/create_first_flow/" >}}Create a Web Flow{{< /newtab >}} in **Truora**.  
4. **Basic Understanding of Validators**: Familiarity with **Digital Identity Validators** is helpful. If needed, refer to the **Validations Workflow** section in the {{< newtab href="/validators/" >}}DI - Validators API{{< /newtab >}} documentation.

 > **Disclaimer:** 
 > - This guide involves making API requests, handling authentication, and interpreting JSON responses. To follow along effectively, we recommend involving a developer or someone with technical expertise.

 > **Need Help?**
 > - The examples in this guide cover typical use cases. If you require assistance with a specific integration scenario, please contact our **Support Team**.

## The Example Flow

The following is a simple **Web Flow** that includes an **Email Validator** and a **Document + Face Validator** block. This **flow** serves as the example used throughout this guide for all verification steps.

{{<img src="/images/illustrations/verify_identity_test_flow.png" alt="Example test flow" width="60%" class="border border-slate-400 rounded-md">}}

<br>

---

## Create Identity endpoint

To create and start a verification process for a user, use the **Create Identity** endpoint. Before making this request, you must:

  - Have a flow already created.
  - Generate a temporary ``api_key`` linked to the corresponding ``flow_id``.

Follow the {{< newtab href="/guides/web_integration_token/" >}}Web Integration Token Guide{{< /newtab >}} to complete this setup.

> **Important:** A unique ``api_key`` must be generated for each identity verification process, even if performed by the same user.

**Request setup**:

1. Create a **POST** request to the endpoint ``https://api.identity.truora.com/v1/processes/``
2. Set the **Header**
    - ``Truora-API-Key``: Enter the value of the generated token (``api_key``) of the instructions above.

Send the request. The response will include a ``process_id``, which is required for subsequent API calls, and the key details of each step, including ``step_id``, ``verification_id``, ``type``, ``expected_inputs``, and ``files_upload_urls``.

If everything is set correctly, you should receive a response similar to the following:

{{<code lang="json" method="POST" endpoint="/v1/processes/" response="200 - Success" file="/static/jsons/verify_identity_guide/1_create_identity_example_response.json">}}

{{</code>}}

Extract the ``process_id`` from the response for the next steps.

## Read Identity endpoint

The **Read Identity** endpoint provides step details and progression tracking for a specific process. The response includes the ``steps`` section, allowing you to:

  - Determine the number of steps in the process, each identified by a unique ``step_id``.
  - Retrieve key details for **verifying each step**, including ``step_id``, ``verification_id``, ``type``, ``expected_inputs``, and ``files_upload_urls``.
    - The ``expected_inputs`` object specifies the required data to verify the **step**.
  - Track step progression by checking ``current_step_data`` and ``verification_output``.
    - After making a **Verify Identity** request for a step, poll the **Read Identity** endpoint to confirm the process has moved to the next step before proceeding with its verification.

### Retrieving process steps

1. Create a **GET** request to the endpoint ``https://api.identity.truora.com/v1/processes/{process_id}``. 
    - Replace the **Path Parameter** ``process_id`` with the ID obtained from the **Create Identity** request.
2. Set the **Headers**
    - ``Truora-API-Key``: Enter your permanent **Truora API Key** (not the temporary ``api_key`` from the previous step).

Upon sending the request, you'll receive a response similar to this:

{{<code lang="json" method="GET" endpoint="/v1/processes/{process_id}" file="/static/jsons/verify_identity_guide/2_read_identity_example_response.json">}}

{{</code>}}

The response corresponds to the process created with the [Example Flow](#the-example-flow). The following table outlines the ``step_id``, ``type``, ``expected_inputs``, and ``files_upload_urls`` for each step in this example process:

#### Example process steps table
{{<table >}}
|Step ID      | Type                              | Expected Inputs       | Files Upload URL              |
|-------------|-----------------------------------|-----------------------|-------------------------------|
|IPSb322XXXX  | enter_email                       | Yes - See response    | null                          |
|IPSc95bXXXX  | enter_email_verification_code     | Yes - See response    | null                          |
|IPSc4cdXXXX  | enter_document_type               | Yes - See response    | null                          |
|IPSb105XXXX  | take_document_photo               | null                  | document_front, document_back |
|IPS01abXXXX  | record_face_photo_liveness        | null                  | null                          |
|IPSe55fXXXX  | record_face_video_liveness        | null                  | null                          |
|IPS31b9XXXX  | enter_face_verification_liveness  | null                  | face_video                    |

{{</table >}}

---

## Verify Identity endpoint

The Verify Identity endpoint processes each step in the identity verification process. It creates and performs validations based on the information supplied in the **request body**. 

To make the request:

1. Create a **POST** request to the endpoint ``https://api.identity.truora.com/v1/processes/{process_id}``. 
    - Replace the **Path Parameter** ``process_id`` with the ID obtained from the **Create Identity** request.
2. Set the **Headers**
    - ``Truora-API-Key``: Enter your permanent **Truora API Key** (not the temporary ``api_key``).
3. Set the **Body**
    - Use **raw JSON** and include the required information for the step being verified.

In the following sections, we'll go through the validation of each step in our example process, detailing the required **request body** for each.

### Verify Identity - Email Validation

As per the [Example process steps table](#example-process-steps-table), email validation consists of two steps:

  - **enter_email**: Requires the user's email.
  - **enter_email_verification_code**: Requires the OTP code sent to the user's email.

#### 1. Enter email

Based on the ``expected_inputs`` of this step, set the **request body** accordingly, providing the ``step_id``, ``verification_id``, the step ``type``, and: 

- Where the ``name`` is "**email**", set the ``value`` to the user's **e-mail address**, which was set to "``john.doe@demo.com``" for our example.

The **request body** should look similar to the following:

{{<code lang="json" lang_title="Verify Identity - Body" file="/static/jsons/verify_identity_guide/3_verify_identity_enter_email.json">}}

{{</code>}}

Send the **Verify Identity** request. Upon receiving a **200 - Request successful** response, poll the [Read Identity endpoint](#read-identity-endpoint) to confirm that the process has moved to the next step.

In the relevant portion of the response:

 - Check the ``current_step_data`` to verify that the current step has moved to ``enter_email_verification_code``.
 - Check that the ``current_step`` is set to **1**.
 - Check the ``steps`` object to verify that the ``enter_email`` step has a ``verification_output`` with a ``status`` of ``success``, and includes the ``validation_type``, ``validation_id`` and ``email`` in ``outputs``.

{{<code lang="json" method="GET" endpoint="/v1/processes/{process_id}" file="/static/jsons/verify_identity_guide/4_read_identity_enter_email.json">}}

{{</code>}}

#### 2. Enter email verification code

Based on the ``expected_inputs`` of this step, set the request body accordingly, providing the ``step_id``, ``verification_id``, the step ``type``, and: 

- Where the ``name`` is "**token**", set the ``value`` to the **OTP** received in the user's e-mail, which was set to "``654321``" for our example.

The **request body** should look similar to the following:

{{<code lang="json" lang_title="Verify Identity - Body" file="/static/jsons/verify_identity_guide/5_verify_identity_email_verification_code.json">}}

{{</code>}}

Send the **Verify Identity** request. Upon receiving a **200 - Request successful** response, poll the [Read Identity endpoint](#read-identity-endpoint) to confirm that the process has moved to the next step.

In the relevant portion of the response:

 - Check the ``current_step_data`` to verify that the current step has moved to ``enter_document_type``.
 - Check that the ``current_step`` is now **2**.
 - Check the ``steps`` object to confirm that the ``enter_email_verification_code`` step has a ``verification_output`` with a ``status`` of ``success`` and contains the ``validation_type`` and ``validation_id`` in ``outputs``.

{{<code lang="json" method="GET" endpoint="/v1/processes/{process_id}" file="/static/jsons/verify_identity_guide/6_read_identity_email_verification_code.json">}}

{{</code>}}

### Verify Identity - Document Validation

As per the [Example process steps table](#example-process-steps-table), document validation consists of two steps:

  - **enter_document_type**: Requires the user's document type and document country. Generates the URLs for the document pictures to be uploaded in the next step.
  - **take_document_photo**: Requires the photo of the user's document to be uploaded to the URLs generated in the previous step.

#### 1. Enter Document Type

Based on the ``expected_inputs`` of this step, set the request body accordingly, providing the ``step_id``, ``verification_id``, the step ``type``, and:

- Where the ``name`` is "**country**", set the ``value`` to the two letters of one of the allowed countries (e.g. ``CO`` for Colombia). 
- Where the ``name`` is "**document_type**", set the ``value`` to one of the allowed document types (e.g. ``national-id`` for National Identification). 

You can find a full list of {{< newtab href="/guides/document_validation_api/#appendix-1-supported-document-types" >}}Supported Document Types and Countries{{< /newtab >}}.
  
The **request body** should look similar to the following:

{{<code lang="json" lang_title="Verify Identity - Body" file="/static/jsons/verify_identity_guide/7_verify_identity_enter_document_type.json">}}

{{</code>}}

Send the **Verify Identity** request. Upon receiving a **200 - Request successful** response, poll the [Read Identity endpoint](#read-identity-endpoint) to confirm that the process has moved to the next step. 

In the relevant portion of the response:

 - Check the ``current_step_data`` to verify that the current step has moved to ``take_document_photo``.
 - Check that the ``current_step`` is now **3**.
 - Check the ``steps`` object to confirm that the ``enter_document_type`` step has a ``verification_output`` with a ``status`` of ``success`` including the ``validation_id`` and the **URLs** for the ``front_document_photo`` and ``back_document_photo`` in ``outputs``.
 > Important: Extract the ``front_document_photo`` and ``back_document_photo`` URLs. You'll need them next to upload the document photos.

{{<code lang="json" method="GET" endpoint="/v1/processes/{process_id}" file="/static/jsons/verify_identity_guide/8_read_identity_enter_document_type.json">}}

{{</code>}}

#### 2. Take document photo

This step requires submitting document images via a ``PUT`` request to the URLs generated in the previous step: ``document_front`` and ``document_back``. Ensure the **request body** is set to **Binary** to send the image files correctly.

- **PUT** ``{{document_front}}``
- **PUT** ``{{document_back}}``

Send each of these requests. Once each document photo is successfully uploaded, the response should return **200 - Request successful**:

{{<code lang="json" method="PUT" endpoint="{{document_front}}" file="/static/jsons/verify_identity_guide/0_upload_media_success.json">}}

{{</code>}}

{{<code lang="json" method="PUT" endpoint="{{document_back}}" file="/static/jsons/verify_identity_guide/0_upload_media_success.json">}}

{{</code>}}

After both images are successfully uploaded, keep polling the [Read Identity endpoint](#read-identity-endpoint) endpoint to confirm the process has moved to the next step.

In the relevant portion of the response:

 - Check the ``current_step_data`` to verify that the current step has moved to ``record_face_photo_liveness``.
 - Check that the ``current_step`` is now **4**.
 - Check the ``steps`` object to confirm that the ``take_document_photo`` step has a ``verification_output`` with a ``status`` of ``success``, ``attachment_status`` is ``valid`` and includes the ``validation_id`` and ``account_id`` in ``outputs``.

{{<code lang="json" method="GET" endpoint="/v1/processes/{process_id}" file="/static/jsons/verify_identity_guide/9_read_identity_take_document_photo.json">}}

{{</code>}}

### Verify Identity - Face Validation

As outlined in the [Example process steps table](#example-process-steps-table), face validation consists of three steps:

  - **record_face_photo_liveness**: No expected inputs. This step creates an **enrollment** for the **account_id** with the face extracted from the document.
  - **record_face_video_liveness**: No expected inputs. This step creates a **validation** using the **enrollment** from the previous step.
  - **enter_face_verification_liveness**: Requires the user's face video and performs the validation by comparing the **enrolled face** from the document with the uploaded **video of the face**.

#### 1. Record face photo liveness

For this step verification, set the request body by including the ``step_id``, ``verification_id`` and the step ``type``. The **request body** should look similar to the following:

{{<code lang="json" lang_title="Verify Identity - Body" file="/static/jsons/verify_identity_guide/10_verify_identity_record_face_photo_liveness.json">}}

{{</code>}}

Send the **Verify Identity** request. Upon receiving a **200 - Request successful** response, poll the [Read Identity endpoint](#read-identity-endpoint) to confirm that the process has moved to the next step. 

In the relevant portion of the response:

 - Check the ``current_step_data`` to verify that the current step has moved to ``record_face_video_liveness``.
 - Check that the ``current_step`` is now **5**.
 - Check the ``steps`` object to confirm that the ``record_face_photo_liveness`` step has a ``verification_output`` with a ``status`` of ``success`` and includes the generated ``enrollment_id`` in ``outputs``.

{{<code lang="json" method="GET" endpoint="/v1/processes/{process_id}" file="/static/jsons/verify_identity_guide/11_read_identity_record_face_photo_liveness.json">}}

{{</code>}}

#### 2. Record face video liveness

For this step verification, set the request body by including the ``step_id``, ``verification_id`` and the step ``type``. The **request body** should look similar to the following:

{{<code lang="json" lang_title="Verify Identity - Body" file="/static/jsons/verify_identity_guide/12_verify_identity_record_face_video_liveness.json">}}

{{</code>}}

Send the **Verify Identity** request. Upon receiving a **200 - Request successful** response, poll the [Read Identity endpoint](#read-identity-endpoint) to confirm that the process has moved to the next step. 

In the relevant portion of the response:

 - Check the ``current_step_data`` to verify that the current step has moved to ``enter_face_verification_liveness``.
 - Check that the ``current_step`` is now **6**.
 - Check the ``steps`` object to confirm that the ``record_face_video_liveness`` step has a ``verification_output`` with a ``status`` of ``success`` and contains the ``validation_id``, ``validation_type`` and the **URL** for the ``face_video`` generated in ``outputs``.
 > Important: Extract the ``face_video`` URL, as you will need it in the next step to upload the user's face video.

{{<code lang="json" method="GET" endpoint="/v1/processes/{process_id}" file="/static/jsons/verify_identity_guide/13_read_identity_record_face_video_liveness.json">}}

{{</code>}}

#### 3. Enter face verification liveness

This step requires submitting the user's face video through a ``PUT`` request to ``face_video`` URL obtained in the previous step. The request body should be set to **Binary** to correctly upload the video file:

- **PUT** ``{{face_video}}``

Send the request. Upon successfully uploading the video, the response should return **200 - Request successful**:

{{<code lang="json" method="PUT" endpoint="{{face_video}}" file="/static/jsons/verify_identity_guide/0_upload_media_success.json">}}

{{</code>}}

Once successfully uploading the video, set the request body by including the ``step_id``, ``verification_id`` and the step ``type``. The **request body** should look similar to the following:

{{<code lang="json" lang_title="Verify Identity - Body" file="/static/jsons/verify_identity_guide/14_verify_identity_enter_face_verification_liveness.json">}}

{{</code>}}

Send the **Verify Identity** request. After receiving a **200 - Request successful** response, keep polling the [Read Identity endpoint](#read-identity-endpoint) to confirm the step verification. This step validates the **document face** against the **uploaded video** for face recognition.

In the relevant portion of the response:

 - Check that the is no longer a ``current_step_data``.
 - Check that the ``current_step`` is now **7**.
 - Check the ``steps`` object to confirm that the ``enter_face_verification_liveness`` step has a ``verification_output`` with a ``status`` of ``success``, along with the ``validation_id``, ``validation_type`` and ``account_id`` set in ``outputs``.

{{<code lang="json" method="GET" endpoint="/v1/processes/{process_id}" file="/static/jsons/verify_identity_guide/15_read_identity_enter_face_verification_liveness.json">}}

{{</code>}}

 **Final Confirmation**: Since there are no more steps left, the ``status`` of the successful process should be ``success``.
 {{<img src="/images/illustrations/api_success_process.png" alt="Successful Process API Response" width="40%" class="border border-slate-400 rounded-md">}}

 > Keep in mind that the ``status`` of a process always begins as ``pending``, and updates to either ``success`` or ``failure`` when the process completes.

## Get Process Result
- You can get the process results with a query to the **Truora's API** or from the **dashboard**. For more information, please see [**Guide to Get Results**](/guides/get_result/).
- To get process result automatically, you must subscribe webhooks. For more information, please visit the [**Webhooks guide**](/guides/webhook_rule).