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
Body
external_idstringOptional

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

Responses
200

Magic link successfully created

application/json
post
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 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;

  • CORS configuration: Ensure that your webhook server allows the following URLs in its CORS settings:

    • Production: https://verification.unico.app

    • Sandbox: https://verification.uat.unico.app

Errors responses

Get Result

get

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

Authorizations
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
GET /v2/history/request 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"
}

Errors responses

PreviousAPI ReferenceNextResponse Enum

Last updated