Create ProcessPOST

Create a Human Token process from your back-end and get the humanToken in data.humanToken.

Markdown

Human Token runs on the Human API POST /client/v1/process endpoint. With the API Only flows (api+humantoken, api+liveness+humantoken and api+liveness+humantoken+revalidation), the process is created and finished in a single call: the response already carries the result in data.humanToken. With the Human Token Journey flows (humantoken and humantoken+revalidation), the response carries the process id, a token and the journey link, and the result is available after the user completes the journey. The +revalidation flows require a references array with a previously obtained humanToken for revalidation.

Flows

Human Token runs in two integration models:

• API Only — your back-end sends the selfie in imageBase64.
• Human Token Journey — the user goes through the Unico journey on Web and returns to your callbackUri.

Flow	Capabilities	Possible result	Integration components required	Example
api+humantoken	Human Token	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
api+liveness+humantoken	LivenessHuman Token	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
api+liveness+humantoken+revalidation	LivenessHuman TokenRevalidation	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
humantoken	LivenessHuman Token	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELED	APIWeb
humantoken+revalidation	LivenessHuman TokenRevalidation	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELED	APIWeb

Endpoint

Environment	URL
Production	POST https://humantoken.unico.app/client/v1/process

Request

Headers

Header	Value
x-unico-accesskey	<your_access_key> (see Authentication)
Content-Type	application/json

Body parameters

Field	Type	Required	Description
flow	string	yes	Human Token flow: api+humantoken, api+liveness+humantoken, api+liveness+humantoken+revalidation (API Only) or humantoken, humantoken+revalidation (Human Token Journey). See Flows.
imageBase64	string	API Only	The selfie, captured by your front-end and sent directly, in base64. PNG, JPEG or WebP, up to 800 KB. Follow the Capture Standard.
callbackUri	string	Human Token Journey	URL the user is redirected to after the journey ends.
companyBranchId	string	no	Branch identifier. When provided, the process uses the configuration of the specified branch.
references	array	Revalidation flows	Array of reference objects. Required for +revalidation flows. Each object has referenceType (REFERENCE_TYPE_HUMAN_TOKEN) and referenceContent (the previously obtained humanToken value).

Responses

200 OK

Field	Type	Description
id	string (UUID)	Process identifier. Use it to fetch the process again via Get Process.
state	string	Process state — see Interpreting the result. Only in the API Only flows.
token	string	Token of the created process, you can use this to open Journey SDK experience. Only in the Human Token Journey flows (humantoken, humantoken+revalidation).
link	string	URL of the Human Token Journey: send the user to it. Only in the Human Token Journey flows (humantoken, humantoken+revalidation).
data.​humanToken.​value	string	Stable, opaque identifier of the face (up to 100 characters). The same person always resolves to the same value. Only in the API Only flows (non-revalidation).
data.​humanTokenMatch	string	"true" if the selfie matches the referenced humanToken, "false" otherwise. Only in the +revalidation API Only flow.

Interpreting the result

state	Meaning	What to do
PROCESS_STATE_FINISHED	data.humanToken.value filled: real person, with a Human Token.	Look up value in your records: if it exists, it is a returning user or a possible duplicate; if not, it is a new person.
PROCESS_STATE_FINISHED	No data.humanToken, or an empty value: inconclusive.	Treat it as inconclusive. Never store or match an empty value; retry the process or reject, per your business rules.
PROCESS_STATE_FAILED	The identification process failed.	Retry the process or reject it, per your business rules.
PROCESS_STATE_CREATED	Process created.	Wait. Fetch the result later with Get Process.
PROCESS_STATE_CANCELED	The process was canceled.	Create a new process, if the user still needs to be verified.

warning

Always check that data.humanToken.value is not empty before using it.

Error Codes

note

The HTTP status returned when the access key in the x-unico-accesskey header is missing or invalid is still being confirmed. See Authentication.

400 Bad Request

Code	Message	Description
3	invalid flow	When the specified flow does not exist.
3	INVALID_IMAGE	When the image is not valid base64, or looks like an injection attempt.
3	IMAGE_TOO_LARGE	When the image exceeds the maximum size of 800 KB.
3	UNSUPPORTED_IMAGE_FORMAT	When the image format is not PNG, JPEG or WebP.
3	MISSING_IMAGE	When the image is required for this flow and was not sent.
3	INVALID_REQUEST	When the request body is null or cannot be interpreted.
9	monthly process limit of <monthly_limit> reached for this tenant	When the monthly usage limit has been reached.
9	PROCESS_FAILED	When the process reached a terminal failure while being created.

403 Forbidden

Code	Message	Description
7	PERMISSION_DENIED	When the credentials are valid but not entitled to this action.

429 Too Many Requests

Rate limit reached. When your system receives an HTTP 429 error, you must implement mechanisms to prevent cascading failures and avoid worsening the restriction.

Best practices:

• Cool-down period (backoff): Immediately halt or throttle subsequent requests from your system. Do not continuously retry failed requests in a tight loop.
• Queueing & throttling: Buffer or queue outgoing requests on your end to control the traffic flow before re-sending them.
• Exponential backoff with jitter: When retrying, increase the waiting time exponentially between attempts (e.g., 1 s, 2 s, 4 s, 8 s) and add a small random delay ("jitter") to prevent a herd effect where all queued requests retry at the exact same millisecond.

warning

Continuously hitting a rate-limited endpoint without backing off can prolong the restriction period and severely impact your system's operational throughput. Properly throttling requests on your side ensures a smoother, more resilient integration.

For default limits, increase requests and additional details, see Rate Limits.

500 Internal Server Error

Code	Message	Description
13	Internal failure! Try again later	When there is an internal error.

For the full list of codes of this endpoint, see the Human API Create Process reference.

What's next

• Store the humanToken value alongside your user record to recognize the same person on later Human Token calls.
• To fetch the process again, for auditing or support, use Get Process.