Get ProcessGET

Retrieve a Human Token process by its identifier — after the user returns from the Human Token Journey, or to query an API Only result again.

Markdown

Endpoint

Environment	URL
Production	GET https://humantoken.unico.app/client/v1/process/{processId}

Request

Headers

Header	Value
x-unico-accesskey	<your_access_key> (see Authentication)

Path parameters

Parameter	Type	Required	Description
processId	string (UUID)	yes	Process identifier returned by Create Process.

Example

cURL

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

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  `https://humantoken.unico.app/client/v1/process/${processId}`,
  { headers: { 'x-unico-accesskey': process.env.UNICO_ACCESS_KEY } }
);
const result = await res.json();
// result.data.humanToken.value

Responses

200 OK

The response has the same format as Create Process. The shape of data depends on the flow used when the process was created.

Standard flows (api+humantoken, api+liveness+humantoken, humantoken):

{
  "id": "6ed74799-4c2f-4023-b43f-a73cf7c847b2",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": {
      "value": "3f9a1c7e5b2d4086a1e3c5f7092b4d6e8a0c2e4f6183a5c7e9b1d3f5072a4c6e",
      "status": "validated"
    }
  }
}

Revalidation flows (api+liveness+humantoken+revalidation, humantoken+revalidation):

{
  "id": "cb0472c0-6dbc-46c6-b830-2be7edc35424",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanTokenMatch": "true"
  }
}

Field	Type	Description
id	string (UUID)	Process identifier.
state	string	Process state — see state values.
data.​humanToken.​value	string	Standard flows only. Stable, opaque identifier of the face (up to 100 characters). The same person always resolves to the same value.
data.​humanTokenMatch	string	Revalidation flows only. "true" if the selfie matches the referenced humanToken, "false" otherwise.

state values

Value	Meaning
PROCESS_STATE_UNSPECIFIED	State not set.
PROCESS_STATE_CREATED	The process was created and still accepts new sessions. data is {}.
PROCESS_STATE_FINISHED	The process was finished and no longer accepts new sessions. For standard flows, data.humanToken is present when a Human Token was generated; for revalidation flows, data.humanTokenMatch indicates whether the selfie matched the referenced token. Otherwise data is {}.
PROCESS_STATE_FAILED	The process failed. data is {}.
PROCESS_STATE_CANCELED	The process was canceled. data is {}.
PROCESS_STATE_AWAITING_FOR_DOCUMENT	The process is waiting for an identification document. data is {}.

warning

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

Error Codes

400 Bad Request

Code	Message	Description
3	process id is invalid	When the process ID is invalid.

401 Unauthorized

Access key missing or invalid in the x-unico-accesskey header. See Authentication.

404 Not Found

Code	Message	Description
5	error getting process: rpc error: code = NotFound desc = process not found	When the process ID was not found.

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
99999	Internal failure! Try again later	When there is an internal error.

What's next

• Back to Create Process to send a new selfie.
• To understand what the humanToken represents and when it is not generated, see the Human Token overview.