Lookup API

Query verifications by document number, metadata, ID, or date.

Authentication

Use your webhook_secret as a Bearer token:

Authorization: Bearer TR_WHS_xxx

All queries are scoped to your account — you cannot see other clients' verifications.

GET /api/v1/public/kyc/verifications

Parameters

Parameter	Type	Description
q	string	Searches three places: the verification_id, the metadata you sent in the widget, and the document data extracted by OCR (name, document number, etc)
status	string	Filter by status: pending, processing, approved, rejected
from	date	From date (YYYY-MM-DD)
to	date	To date (YYYY-MM-DD)
limit	int	Page size (default 20, max 100)
offset	int	Pagination offset (default 0)

How search works (q)

The q parameter searches simultaneously across:

1. Verification ID — the UUID Trusty generates on init (e.g. 601e510f-b0c4-...)
2. Metadata — the JSON you sent in the widget (e.g. {"userId":"123"}). Searching userId will find that verification
3. Document data (OCR) — data the AI extracted from the document: full name, document number, date of birth, etc

It's a partial match (LIKE). q=60518799A finds any verification where the extracted document number contains that text.

Example: search by document number

curl "https://trusty-api.trusty.sh/api/v1/public/kyc/verifications?q=60518799A" \
  -H "Authorization: Bearer TR_WHS_xxx"

Example: search by userId (metadata)

curl "https://trusty-api.trusty.sh/api/v1/public/kyc/verifications?q=user123" \
  -H "Authorization: Bearer TR_WHS_xxx"

Example: filter by status and date

curl "https://trusty-api.trusty.sh/api/v1/public/kyc/verifications?status=approved&from=2026-07-01&to=2026-07-31&limit=10" \
  -H "Authorization: Bearer TR_WHS_xxx"

Response 200

{
  "items": [
    {
      "id": "601e510f-b0c4-4f6d-a8a2-132fb9b40cf3",
      "status": "approved",
      "country_code": "ES",
      "city": "Madrid",
      "failure_reason": null,
      "full_name": "GUILLERMO DANIEL CANELON LOVERA",
      "document_number": "60518799A",
      "metadata": { "userId": "123" },
      "created_at": "2026-07-24 02:56:48",
      "updated_at": "2026-07-24 03:17:05"
    }
  ],
  "total": 57,
  "limit": 20,
  "offset": 0
}

Response fields

Field	Description
id	Verification UUID
status	Current status: pending, processing, approved, rejected
country_code	Country where the verification was performed (ISO 2-letter code)
city	City where the verification was performed
failure_reason	If rejected, comma-separated reasons. If approved, null
full_name	Full name extracted from the document via OCR
document_number	Document number extracted via OCR
metadata	The JSON you sent in the widget, unmodified
created_at	Creation date
updated_at	Last update date

Use cases

• Search by userId: ?q=user123 — searches the metadata you sent
• Search by ID: ?q=60518799A — searches the extracted document data
• Check for duplicates: search by document number to see if already verified
• Audit by date: ?from=2026-07-01&to=2026-07-31

Errors

Status	Error	Description
401	unauthorized	Token invalid or missing