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

ApiKeyAuth

x-api-keystringRequired

Body

application/json

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

HTTPcURLJavaScriptPython

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

Click on the side to see more

400 Bad Request

403 Forbidden

500 Internal Server Error

Get Result

get

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

Authorizations

ApiKeyAuth

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

HTTPcURLJavaScriptPython

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

Click on the side to see more

400 Bad Request

404 Not Found

500 Internal Serve Error