Create Account to link processes by user

Others: Account

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 Web Token for user processes or creating a Validation, 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 Web Token for user processes or creating a Validation, 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 API Reference:

  1. Create a POST request to the endpoint https://api.validations.truora.com/v1/accounts.
  2. Add the next headers
    • Truora-API-Key: Your Truora API-key.
    • 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.
    • 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:

POST
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
        }
    }

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 API Reference.

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 API Reference:

  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 Truora API-key.
    • 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 section, “my_test_account_6543”, generates the following response:

GET
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
        }
    }

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 API Reference:

  1. Create a GET request to the endpoint https://api.validations.truora.com/v1/accounts.
  2. Add the next headers
    • Truora-API-Key: Your Truora API-key.
    • 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:

GET
https://api.validations.truora.com/v1/accounts 
                {
    "self": "/v1/accounts",
    "next": "/v1/accounts?start_key=ACC008ffXXXXXXXX",
    "accounts": [
        {
            "account_id": "ACC0004cXXXXXXXX",
            "creation_date": "2023-08-18T07:41:21.283968711Z",
            "validators_prepared": {
                "document-validation": true,
                "electronic-signature": false,
                "email-verification": false,
                "enterprise-data": false,
                "face-recognition": false,
                "face-search": false,
                "identity-questions": false,
                "phone-verification": false,
                "voice-recognition": false
            }
        },
        {"...":"..."},
        {"...":"..."},
        {"...":"..."},
        {
            "account_id": "ACC008ffXXXXXXXX",
            "creation_date": "2025-02-05T15:23:42.92770442Z",
            "validators_prepared": {
                "authenticate": false,
                "document-validation": true,
                "electronic-signature": false,
                "email-verification": false,
                "face-recognition": false,
                "face-search": false,
                "phone-verification": false
            }
        }
    ]
}

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 API Reference:

  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 Truora API-key.
    • 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:

GET
https://api.validations.truora.com/v1/accounts/{{account_id}}/validations 
                {
    "self": "/v1/accounts/my_test_account_1234/validations",
    "next": "",
    "history": [
        {
            "validation_id": "VLDa881c7XXXX",
            "ip_address": "186.XXX.XXX.XXX",
            "account_id": "my_test_account_1234",
            "type": "face-recognition",
            "validation_status": "success",
            "threshold": 0.65,
            "creation_date": "2025-02-05T16:38:19.916821179Z",
            "details": {
                "face_recognition_validations": {
                    "...":{}
                }
            },
            "identity_process_id": "IDP62f3dd9XXXX"
        },
        {
            "validation_id": "VLDdfd542XXXX",
            "ip_address": "186.XXX.XXX.XXX",
            "account_id": "my_test_account_1234",
            "type": "document-validation",
            "validation_status": "success",
            "creation_date": "2025-02-05T16:33:51.464521422Z",
            "details": {
                "...":{}
            },
            "identity_process_id": "IDP62f3dd9XXXX",
            "attachment_status": "valid",
            "allowed_retries": 2,
            "remaining_retries": 2
        },
        {
            "validation_id": "VLD06f466XXXX",
            "ip_address": "186.XXX.XXX.XXX",
            "account_id": "my_test_account_1234",
            "type": "phone-verification",
            "validation_status": "success",
            "creation_date": "2024-11-20T18:40:39.135367055Z",
            "identity_process_id": "IDPa2319XXXX",
            "allowed_retries": 3,
            "remaining_retries": 3
        }
    ]
}

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 API Reference.

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
    • 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”:

GET
https://api.identity.truora.com/v1/processes/?search=1234567_client 
                {
    "self": "/v1/processes?search=1234567_client",
    "next": "",
    "identity_processes": [
        {
            "process_id": "IDP0000000000",
            "account_id": "1234567_client",
            "client_id": "client_id",
            "flow_id": "client_id",
            "country": "CO",
            "status": "pending",
            "geolocalization": "geolocalization",
            "city": "city",
            "time_to_live": 120,
            "config": {
                "redirect_urls": {
                    "failure": "https://truora.com",
                    "pending": "https://truora.com",
                    "success": "https://truora.com"
                },
                "continue_flow_in_new_device": true,
                "enable_desktop_flow": true,
                "time_to_live": 120,
                "follow_up_delay": 120,
                "follow_up_message": "Tienes un proceso activo en curso",
                "start_business_hours": "2021-01-01T13:00:00Z",
                "end_business_hours": "2021-01-01T00:00:00Z"
            },
            "redirect_url": "https://dev.truora.com",
            "creation_date": "2023-07-31T14:34:43.019112173Z",
            "update_date": "2023-07-31T14:34:43.024034634Z",
            "steps": [
                {
                    "step_id": "IPS4875XXXXXXXX",
                    "type": "enter_document_type",
                    "verification_output": null,
                    "redirect_url": "",
                    "config": {
                        "allowed_document_types": [
                            {
                                "country": "CO",
                                "documents": [
                                    {
                                        "document_type": "national-id"
                                    }
                                ]
                            }
                        ],
                        "retries": 2,
                        "timeout": 300
                    },
                    "expected_inputs": [
                        {
                            "type": "select",
                            "value": "CO",
                            "name": "country",
                            "placeholder": "Ingresa el pais",
                            "description": "¿Cuál es el país de tu documento de identificación?",
                            "length": 0,
                            "read_only": true
                        },
                        {
                            "type": "select",
                            "value": "national-id",
                            "name": "document_type",
                            "placeholder": "Selecciona el tipo de documento",
                            "description": "¿Cuál es el tipo de tu documento de identificación?",
                            "length": 0,
                            "read_only": true
                        }
                    ],
                    "files_upload_urls": null,
                    "remaining_retries": 0,
                    "async_step": null
                },
                {
                    "step_id": "IPSf5f3XXXXXXXX",
                    "type": "take_document_photo",
                    "verification_output": null,
                    "redirect_url": "",
                    "config": {
                        "allowed_document_types": [
                            {
                                "country": "CO",
                                "documents": [
                                    {
                                        "document_type": "national-id"
                                    }
                                ]
                            }
                        ],
                        "retries": 2,
                        "timeout": 300
                    },
                    "expected_inputs": null,
                    "files_upload_urls": [
                        {
                            "name": "document_front",
                            "url": "",
                            "description": "Envía una foto de *la parte de adelante* de tu documento de identidad: en la imagen puedes ver un ejemplo de cómo debería quedar."
                        },
                        {
                            "name": "document_back",
                            "url": "",
                            "description": "Envía una foto de *la parte de atrás* de tu documento de identidad: en la imagen puedes ver un ejemplo de cómo debería quedar."
                        }
                    ],
                    "remaining_retries": 2,
                    "async_step": true
                }
            ],
            "current_step_type": "enter_document_type",
            "variables": {
                "document_validation": {}
            },
            "created_via": "web"
        }
    ]
}