KYC

In this section, you will find how to create a process in Unico via the REST API

Getting started

Creates a magic link to start a KYC web process hosted by Unico. After the user finished the process, the user magic link will be inactivated and the user will not be able to use it again. You will need to create a new magic link for the user to start a new KYC process.

Base URL:

Sandbox: https://sandbox.trully.ai;
Production: https://api.trully.ai.

Create a Magic Link

post

Endpoint to create a new KYC process in Magic Link integration.

Authorizations

x-api-keystringRequired

Body

external_idstringOptional

An external identifier for the request, used for tracking and reference purposes.

Responses

200

Magic link successfully created

application/json

post

/v2/magic-link

POST /v2/magic-link HTTP/1.1
Host: sandbox.trully.ai
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 97

{
  "external_id": null,
  "metadata": {
    "redirect_url": null,
    "webhook_url": null,
    "track_webhook_url": null
  }
}

200

Magic link successfully created

{
  "data": {
    "external_id": null,
    "created_on": "2025-07-28T18:11:54.430048399Z",
    "is_active": true,
    "token": "3f6dbcc1-49ba-4935-be90-dd8dd59b5530",
    "magic_link_url": "https://verification.uat.unico.app/link/v2/3f6dbcc1-49ba-4935-be90-dd8dd59b5530",
    "metadata": {
      "redirect_url": null,
      "webhook_url": null,
      "track_webhook_url": null
    },
    "version": "v2"
  },
  "version": "v1.4.2",
  "status": "ok",
  "status_code": 200,
  "request_date": "2025-07-28T18:11:54+0000",
  "request": {
    "metadata": {
      "redirect_url": null,
      "webhook_url": null,
      "track_webhook_url": null
    }
  }
}

Enum track_webhook_url

Key

Description

step

Name of the previous completed step.

user_id

The external_id you set in the magic link.

started_on

UTC timezone. Step starting time.

completed_on

UTC timezone. Step completion time.

Steps Table

Name

Description

form_start

User is currently scanning the document.

form document_front

The user has already captured the INE Front.

form document_back

The user has already captured the INE Back.

form_document

Process is currently in the selfie step.

form_selfie

User reach the final step of the operation.

form_decision_maker

The operation returns the system response.

Tracking process is a silent operation which means there is no UI to represent it. This process will succeed or fail without any interaction with the user.

Webhook V1 Requirements

HTTPS protocol: For security reasons, your webhook endpoint must use the HTTPS protocol;
Response time: The system will wait up to one minute for a response from your webhook server. After this period, the connection will be dropped. This will not impact the main process execution in any way;

Errors responses

{
    "data": {
        "error": "data provided in the field is invalid"
    },
    "version": "v1.4.2",
    "status": "bad request",
    "status_code": 400,
    "request_date": "2025-07-28T20:22:29+0000",
    "request": {
        "metadata": null
    }
}

{
    "data": {
        "error": "internal server error"
    },
    "version": "v1.4.2",
    "status": "bad request",
    "status_code": 400,
    "request_date": "2025-07-28T20:22:29+0000",
    "request": {
        "metadata": null
    }
}

Get Result

get

Endpoint to get the result of a process in Magic Link.

Authorizations

x-api-keystringRequired

Query parameters

magic_link_tokenstringRequired

Token returned when the Magic Link was created.

Responses

200

Successful response containing identity data and images.

application/json

get

/v2/history/request

GET /v2/history/request?magic_link_token=text HTTP/1.1
Host: sandbox.trully.ai
x-api-key: YOUR_API_KEY
Accept: */*

200

Successful response containing identity data and images.

{
  "data": {
    "images": {
      "document_image": "/9j/4ASu7bmVarteP5IAf[...]fyPjOKfgif//Z",
      "document_image_back": "/9j/4ASu7bmVarteP5IAf[...]fyPjOKfgif//Z",
      "selfie": "/9j/4ASu7bmVarteP5IAf[...]fyPjOKfgif//Z"
    },
    "response": {
      "curp": {
        "age": 58,
        "curp": "GOCJ850627HDFRRL09",
        "date_of_birth": "14/11/1956",
        "deceased": false,
        "gender": "M",
        "government_name": "LUKE SKYWALKER",
        "government_valid": true,
        "is_mexican": true,
        "name_to_CURP_valid": true,
        "state_iso": "MX-NLE",
        "state_of_birth": "Nuevo León"
      },
      "document": {
        "back": {
          "cic": "237457894",
          "citizen_id": "237457894",
          "mrz": "IDMEX999999999999<9 VADER<SKYWALKER<<LUKE"
        },
        "details": {
          "detected": true,
          "document_id": 229928,
          "forensics": {
            "is_valid": "no"
          }
        },
        "front": {
          "face_analysis": {
            "face_id": 237437,
            "face_id_v2": 199068,
            "first_seen": "12/22/2022, 18:54:09",
            "inquiry_date": "07/28/2025, 20:53:12",
            "last_seen": "07/28/2025, 18:47:46",
            "last_seen_by_your_company": "07/24/2025, 21:38:21",
            "match": true,
            "match_fraud_flag": true,
            "seen_by_your_company": true,
            "seen_different_companies": 46,
            "times_seen_by_your_company": 3,
            "times_seen_last_month": 111,
            "unique_face_id_v2": 126880,
            "warnings": {
              "external_id": "User found in the company with other external_ids: ['abc-123']"
            }
          },
          "information": {
            "address": {
              "text": "DOMICILIO/ADDRESS, HARLINGEN, TX 78552, UNITED STATES OF AMERICA",
              "valid": false
            },
            "birthdate": {
              "text": "14/11/1956",
              "valid": true
            },
            "complete_name": {
              "text": "LUKE SKYWALKER",
              "valid": true
            },
            "curp": {
              "text": "GOCJ850627HDFRRL09",
              "valid": true
            },
            "electoral_key": {
              "text": "GRCRSN82031007M500",
              "valid": true
            },
            "last_name": {
              "text": "SKYWALKER",
              "valid": true
            },
            "mother_last_name": {
              "text": "ORGANA",
              "valid": true
            },
            "name": {
              "text": "LUKE",
              "valid": true
            },
            "registration_year": {
              "text": "1998",
              "valid": true
            },
            "sex": {
              "text": "H",
              "valid": true
            },
            "valid_thru": {
              "text": "2027",
              "valid": true
            }
          }
        }
      },
      "face_match": false,
      "label": null,
      "reason": null,
      "request_id": "d1kxp9ah8f0s71uv9zx0",
      "selfie": {
        "face_id": 237436,
        "face_id_v2": 4378,
        "first_seen": "02/05/2025, 02:36:19",
        "first_seen_image": true,
        "inquiry_date": "07/28/2025, 20:52:49",
        "last_seen": "07/28/2025, 20:52:51",
        "last_seen_by_your_company": "07/23/2025, 18:14:27",
        "match": true,
        "match_fraud_flag": true,
        "seen_by_your_company": true,
        "seen_different_companies": 2,
        "times_seen_by_your_company": 2,
        "times_seen_last_month": 7,
        "unique_face_id_v2": 494,
        "warnings": {}
      },
      "unico": {
        "process_id": "d333dfac-9ddb-4066-8e2c-44eaf4c86b4a",
        "result": "PROCESS_RESULT_LIVE"
      }
    },
    "user_id": ""
  },
  "request_date": "2025-07-28T20:53:38",
  "status": "Request fulfilled, document follows",
  "status_code": 200,
  "version": "v3.6.0"
}

The valid field is used to indicate that the OCR texts could be extracted and structurally validated; it does not necessarily indicate that the data actually exists.
The address field, due to its lack of a generalized structure and because in some cases people have the option of not providing their address to the INE (National Institute of Statistics), the "valid" field is not taken into account for validating the structure.

Errors responses

{
    "data": {
        "error": [
            {
                "attribute": [
                    "magic_link_token"
                ],
                "message": "Input should be a valid UUID, invalid group length in group 4: expected 12, found 11",
                "type": "uuid_parsing"
            }
        ]
    },
    "request_date": "2025-07-28T20:43:34",
    "status": "There are some errors in the request",
    "status_code": 400,
    "version": "v3.6.0"
}

Name

Type

Description

data

object

Defines an error structure for API responses, encapsulating error messages resulting from request processing.

data.error

string

A detailed description of the error encountered during the processing of the request.

data.error.atributte

array of strings

The list of attributes causing the error.

data.error.message

string

A detailed message explaining the error.

data.error.type

string

The type of error encountered.

request_date

string

The date and time when the request was made, in ISO 8601 format.

status

string

A textual representation of the response status, indicating success or failure of the operation.

status_code

integer

The HTTP status code of the response, providing a standardized indicator of the request's outcome.

version

string

The version of the API that processed the request, useful for tracking changes and compatibility.

{
    "data": {
        "error": "This magic link have no requests associated"
    },
    "request_date": "2025-07-28T20:40:50",
    "status": "Nothing matches the given URI",
    "status_code": 404,
    "version": "v3.6.0"
}

    "data": {
        "error": "internal server error"
    },
    "version": "v1.4.2",
    "status": "bad request",
    "status_code": 400,
    "request_date": "2025-07-28T20:22:29+0000",
    "request": {
        "metadata": null
    }
}

PreviousAPI Reference NextResponse Enum

Last updated 2 months ago