API Reference Overview

Everything you need to go from zero to your first humanToken.

Markdown

Human Token has three endpoints. This page shows how they fit together so you can start integrating right away.

Base URL

Environment	Base URL
Production	https://humantoken.unico.app

All requests require the x-unico-accesskey header. See Authentication to generate your key.

---

Quick-start flow

---

Step 1 — Authenticate

Generate your x-unico-accesskey in the Human Dashboard or via the Authentication API. Every request below uses this key.

x-unico-accesskey: uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2

---

Step 2 — Create a process

Call Create Process to start the verification. Choose one of two models:

Model	Flows	How it works
API Only	api+humantoken, api+liveness+humantoken, api+liveness+humantoken+revalidation	Your backend sends the selfie as imageBase64. The humanToken comes back in the same response.
Human Token Journey	humantoken, humantoken+revalidation	The user completes the capture on the Unico platform. You get a token and link to present the journey, then fetch the result with Get Process.

API Only example:

curl -X POST https://humantoken.unico.app/client/v1/process \
  -H "x-unico-accesskey: $UNICO_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "api+humantoken",
    "imageBase64": "<base64-encoded-selfie>",
    "companyBranchId": "<your-branch-id>"
  }'

Human Token Journey example:

curl -X POST https://humantoken.unico.app/client/v1/process \
  -H "x-unico-accesskey: $UNICO_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "humantoken",
    "callbackUri": "https://yourapp.com/callback",
    "companyBranchId": "<your-branch-id>"
  }'

See Create Process for all flows, parameters, and response details.

---

Step 3 — Present the journey to the user (Journey flows only)

For humantoken and humantoken+revalidation flows, the Create Process response includes:

• token — initializes the Web SDK or native integration
• link — URL to redirect the user to

Choose the integration that fits your platform:

Platform	Approach
Web — SDK	Embed the journey inline with idpay-b2b-sdk → Web Integration
Web — Redirect	Redirect the user to link → Web Integration
Android	Custom Tabs → Android
iOS	ASWebAuthenticationSession → iOS
Ionic	Capacitor plugin → Ionic
React Native	Native module → React Native
Flutter	Platform Channels → Flutter

When the journey ends, the user returns to your callbackUri. Proceed to Step 4.

API Only flows

Skip this step — the result is already in the Create Process response.

---

Step 4 — Retrieve the result (Journey flows only)

Call Get Process with the process id to fetch the result:

curl https://humantoken.unico.app/client/v1/process/$PROCESS_ID \
  -H "x-unico-accesskey: $UNICO_ACCESS_KEY"

The response includes data.humanToken.value (standard flows) or data.humanTokenMatch (revalidation flows). See Get Process for the full response schema and state values.

---

Step 5 — Use the humanToken

The humanToken is a stable, opaque identifier (up to 100 characters). The same person always resolves to the same value.

const { humanToken } = process.data;

if (!humanToken?.value) {
  // Inconclusive — retry or reject per your business rules
  return;
}

const existing = await db.persons.findByHumanToken(humanToken.value);

if (existing) {
  // Same person seen before — returning user or duplicate
} else {
  // First time — create a new record
  await db.persons.create({ humanToken: humanToken.value });
}

warning

Always check that data.humanToken.value is not empty before storing or matching it.

---

Step 6 — Retrieve the selfie (optional)

Call Get Selfie to download the captured image. The selfie is available for 24 hours after the process finishes — after that, it is permanently deleted.

curl https://humantoken.unico.app/client/v1/process/$PROCESS_ID/selfie \
  -H "x-unico-accesskey: $UNICO_ACCESS_KEY"

See Get Selfie for response details and error codes.

---

Endpoints at a glance

Method	Endpoint	Description
POST	/client/v1/process	Create Process — start a verification
GET	/client/v1/process/{processId}	Get Process — fetch the result
GET	/client/v1/process/{processId}/selfie	Get Selfie — download the selfie (24h)

What's next

• Create Process — full parameter reference for all five flows
• Authentication — generate and manage your access keys
• Build With LLM — paste a prompt into your AI assistant to generate the full integration