# Create Account to link processes by user

{{<tags >}}

An account identifies users in Truora's system and is represented by an ``account_id``.
This unique identifier enables tracking **validations** and **processes** while allowing access to the associated user's data.

In this guide, you'll learn about the available options for creating account IDs in Truora's system.

## Account creation options

There are three ways to generate an ``account_id``:

  - **Use your user's ID** as the ``account_id`` in Truora's system.
  - **Use an automatically generated** ``account_id``, assigned by Truora's system.
  - **Create a customized account** using the **Create Validation Account** endpoint.

The following sections explain each option so you can choose the best approach for your use case.

### Use your user ID as the account_id
If your system already assigns a unique identifier to users, you can use it as the ``account_id`` in Truora's system.
This approach will initially create an empty account, but you can update or add data to it later as needed.

To use this option:

 - When generating a {{< newtab href="/guides/web_integration_token/" >}}Web Token{{< /newtab >}} for user processes or creating a {{< newtab href="/validators/" >}}Validation{{< /newtab >}}, provide your system's user identifier as the value for the ``account_id`` parameter.
 - Ensure that the same ``account_id`` is used consistently across all user processes in Truora's system to maintain correct associations with the user account and data.

>**Note:** 
> - Only Account IDs matching the regex pattern [a-zA-Z0-9_.-]+ are supported.

### Use an account_id generate by Truora's system
This option provides a unique, automatically generated ``account_id``, creating an empty account initially. You can update or add data to the account later as needed.

- When generating the {{< newtab href="/guides/web_integration_token/" >}}Web Token{{< /newtab >}} for user processes or creating a {{< newtab href="/validators/" >}}Validation{{< /newtab >}}, leave the ``account_id`` parameter empty.
This tells the system to generate a random alphanumeric ``account_id`` automatically.

> **Note:** Be sure to save the generated ``account_id`` and use it consistently across all user processes within Truora's system.

### Create Validation Account endpoint

This feature allows you to create an ``account_id`` while also storing user information within Truora's system. The stored data can be accessed or updated as needed.

To create an account follow these steps. You may also refer to our {{< newtab href="/docs/#main-validator-suite-api_accounts-section" >}}API Reference{{< /newtab >}}:

1. Create a ``POST`` request to the endpoint ``https://api.validations.truora.com/v1/accounts``.
2. Add the next headers
   - ``Truora-API-Key``: Your {{< newtab href="/guides/authentication/" >}}Truora API-key{{< /newtab >}}.
   - ``Content-Type``: Set to ``application/x-www-form-urlencoded``.
3. Add the following ``key : value`` params in the request ``body`` using ``x-www-form-urlencoded`` format:
   - ``account_id`` [***Optional***]: Customized ID for the validation account being created. Only account IDs matching the pattern [a-zA-Z0-9_.-]+ are supported. If omitted, a random alphanumeric account ID is automatically created.
   - ``email`` [***Optional***]: Email address of the person associated with the account.
   - ``country`` [***Optional***]: Country where the person associated with the account is located, specified in ISO 3166 Alpha-2 format (e.g., CO for Colombia). See the full list of [ISO Country Codes](https://www.iso.org/obp/ui#search/code/).
   - ``document_number`` [***Optional***]: Document number of the person associated with the account.
   - ``document_type`` [***Optional***]: Allowed: ``national-id`` | ``foreign-id`` | ``identity-card``| ``passport``. Type of document for the person associated with the account.
   - ``document_issue_date`` [***Optional***]: Issue date of the person's document, formatted in RFC3339 (e.g., 2000-05-24).
   - ``first_name`` [***Optional***]: First name of the person associated with the account.
   - ``last_name`` [***Optional***]: Last name of the person associated with the account.
   - ``phone_number`` [***Optional***]: Phone number of the person associated with the account.
   - ``facebook_user`` [***Optional***]: Facebook username of the person associated with the account.
   - ``twitter_user`` [***Optional***]: X (formerly Twitter) username of the person associated with the account.

> **Notes:** 
> - Only Account IDs following the regex pattern [a-zA-Z0-9_.-]+ are supported.
> - All parameters are optional:
>   - If only ``account_id`` is provided, an empty account is created with that ID. You can update other parameters later.
>   - If no ``account_id`` is provided but other parameters are included, an ``account_id`` will be randomly generated, incorporating the provided parameters.
>   - If no parameters are provided, an empty account is created with a randomly generated ``account_id``. You can update other parameters later.
> - Save the ``account_id``, as it will be the unique identifier for your user in Truora's system. All identity-related processes performed on your user should be associated with this ``account_id``.

Send the request. A successful account creation should show the details of the account, including the parameters provided in the **Create Validation Account** request.

**Example Request and Response**

A request with the following parameters:

  - ``account_id``: "***my_test_account_6543***"
  - ``first_name``: "***John***"
  - ``last_name``: "***Doe***"
  - ``email``: "***``jhon.doe@demo.com``***""

Generates the following response:

{{<code lang="json" method="POST" endpoint="https://api.validations.truora.com/v1/accounts">}}
    {
        "account_id": "my_test_account_1234",
        "email": "jhon.doe@demo.com",
        "first_name": "JOHN",
        "last_name": "DOE",
        "creation_date": "2025-02-10T21:18:02.688990977Z",
        "validators_prepared": {
            "authenticate": false,
            "document-validation": false,
            "electronic-signature": false,
            "email-verification": false,
            "face-recognition": false,
            "face-search": false,
            "phone-verification": false
        }
    }
{{</code>}}

---

## Additional account management endpoints

The following account-related endpoints can help with user account management and integration into Truora's system. For more details and additional endpoints, refer to our {{< newtab href="/docs/#get-validation-account-section" >}}API Reference{{< /newtab >}}.

### Get Account
Allows you to retrieve details of a specific validation ``account_id``.

To get the account details, follow these steps. You may also refer to our {{< newtab href="/docs/#get-validation-account-section" >}}API Reference{{< /newtab >}}:

1. Create a ``GET`` request to the endpoint ``https://api.validations.truora.com/v1/accounts/{{account_id}}``. 
2. Add the next headers
   - ``Truora-API-Key``: Your {{< newtab href="/guides/authentication/" >}}Truora API-key{{< /newtab >}}.
   - ``Content-Type``: Set to ``application/x-www-form-urlencoded``.

Send the request. A successful request should show the details of the account.

**Example Request and Response**

A request using the ``account_id`` from the example in the [Create Validation Account](#create-validation-account-endpoint) section, "***my_test_account_6543***", generates the following response:

{{<code lang="json" method="GET" endpoint="https://api.validations.truora.com/v1/accounts/{{account_id}}">}}
    {
        "account_id": "my_test_account_1234",
        "email": "jhon.doe@demo.com",
        "first_name": "JOHN",
        "last_name": "DOE",
        "creation_date": "2025-02-10T21:18:02.688990977Z",
        "validators_prepared": {
            "authenticate": false,
            "document-validation": false,
            "electronic-signature": false,
            "email-verification": false,
            "face-recognition": false,
            "face-search": false,
            "phone-verification": false
        }
    }
{{</code>}}

### List Validation Accounts
Allows you to retrieve all validation accounts created under your client account in Truora´s system.

To get a list of accounts, follow these steps. You may also refer to our {{< newtab href="/docs/#list-validation-accounts-section" >}}API Reference{{< /newtab >}}:

1. Create a ``GET`` request to the endpoint ``https://api.validations.truora.com/v1/accounts``.
2. Add the next headers
   - ``Truora-API-Key``: Your {{< newtab href="/guides/authentication/" >}}Truora API-key{{< /newtab >}}.
   - ``Content-Type``: Set to ``application/x-www-form-urlencoded``.
3. Use the optional ``start_key`` query parameter for pagination.

Send the request. A successful response will look similar to the following:

{{<code lang="json" method="GET" endpoint="https://api.validations.truora.com/v1/accounts" file="/static/jsons/account_id_guide/1_list_validations_accounts_example.json">}}

{{</code>}}

### Get Account Validations
Allows you to retrieve all validations linked to a specific ``account_id.``

To get all validations of an account, follow these steps. You may also refer to our {{< newtab href="/docs/#get-account-validations-section" >}}API Reference{{< /newtab >}}:

1. Create a ``GET`` request to the endpoint ``https://api.validations.truora.com/v1/accounts/{{account_id}}/validations``.
2. Add the next headers
   - ``Truora-API-Key``: Your {{< newtab href="/guides/authentication/" >}}Truora API-key{{< /newtab >}}.
   - ``Content-Type``: Set to ``application/x-www-form-urlencoded``.

Send the request. A successful response will return the validation history of the specified ``account_id``, similar to the following example:

{{<code lang="json" method="GET" endpoint="https://api.validations.truora.com/v1/accounts/{{account_id}}/validations" file="/static/jsons/account_id_guide/2_get_account_validations_example.json">}}

{{</code>}}

### List Identity

Allows you to retrieve the current status and details of all identity **processes**. Use query parameters to filter results based on specific criteria, such as ``account_id``:
  - Use the ``search`` **query parameter** to filter processes by ``account_id``, or other attributes associated with the processes.

> For complete details on this endpoint and its filtering options, refer to our {{< newtab href="/docs/#list-identity-section" >}}API Reference{{< /newtab >}}.

The following example retrieves processes associated with a specific ``account_id`` using the ``search`` **query parameter**:

1. Create a ``GET`` request to the **endpoint**: ``https://api.identity.truora.com/v1/processes/``. 
2. Add the next headers
    - ``Truora-API-Key``: ``<api key>`` Get an [**API key**](/guides/authentication/)
    - ``Content-Type``: ``application/x-www-form-urlencoded``
3. Include the next query-string parameter:
    - ``search``: The ``account_id`` whose processes you want to retrieve.

The response will list all processes performed under the specified ``account_id``, such as in this example using "***1234567_client***":

{{<code lang="json" method="GET" endpoint="https://api.identity.truora.com/v1/processes/?search=1234567_client" file="/static/jsons/account_id_guide/3_list_identity_example.json">}}

{{</code>}}