Skip to main content
Quickstart

From an empty host to your first created and retrieved process, in a few minutes.

Markdown

This page runs Human Plugin alongside a throwaway PostgreSQL container for a quick start on your environment. To deploy it, see Docker Compose or Kubernetes.

Prerequisites​

  • Docker 24 or later, on linux/amd64 or linux/arm64 (Docker Desktop on macOS works).
  • The registry credentials and the access key from Unico. See Prerequisites and access.

1. Get the image​

Log in to Unico's registry with your username and token, once per host:

echo "<token>" | docker login pkg.unico.run -u <username> --password-stdin
docker pull pkg.unico.run/human-plugin-api:latest

2. Start PostgreSQL and Human Plugin​

docker network create human-plugin
docker run -d --name human-plugin-db --network human-plugin \
  -e POSTGRES_USER=human_plugin -e POSTGRES_PASSWORD=human_plugin -e POSTGRES_DB=human_plugin \
  postgres:16

Set your access key in the shell, then start Human Plugin:

export HUMAN_API_ACCESS_KEY='<your access key>'
docker run -d --name human-plugin --network human-plugin --stop-timeout 60 -p 127.0.0.1:8080:8080 \
  -e HUMAN_API_ACCESS_KEY \
  -e POSTGRES_ADDRESS_HOST=human-plugin-db \
  -e POSTGRES_USER=human_plugin \
  -e POSTGRES_PASSWORD=human_plugin \
  -e POSTGRES_SSL_MODE=disable \
  pkg.unico.run/human-plugin-api:latest

POSTGRES_SSL_MODE=disable is only for this local database. Keep the default, require, for any other. See Configuration.

Check that Human Plugin is ready:

curl --fail http://127.0.0.1:8080/health/ready

You should see {"status":"ok"}. If the command fails, docker logs human-plugin says why.

3. Create a process​

Pick one of the flows. clientId, correlationId and credential are the same in every flow.

The person takes the selfie in the capture journey. The response carries the link to it.

curl -s -X POST http://127.0.0.1:8080/v1/processes \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": "humantoken",
    "clientId": "client-a",
    "correlationId": "quickstart-001",
    "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
    "callbackUri": "https://example.com/callback"
  }'
{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_CREATED",
  "token": "<SDK token>",
  "link": "https://…"
}

Open the link on a phone and take the selfie. The token and the link are returned only here: Human Plugin does not store them.

  • id is Human Plugin's own id for the process. Keep it: it is the only way to read the process later.
  • correlationId is your reference and must be unique. Reusing one returns 409 CORRELATION_ID_ALREADY_USED.
  • credential is the person's document. Send null when there is none. The types you can use are in the attribute catalog.
  • data.humanToken is who the person is, and data.ndocs is the person's intelligence: what they have done with you. See Intelligence.
  • With a Journey, the finished process also has data.liveness: live when the capture came from a live person, not_live when it did not. See The result in data.

4. Read it back​

Replace the id with the one from your response:

curl -s http://127.0.0.1:8080/v1/processes/b063041c-7529-4e70-a2b4-c71c00f19801

A Journey stays PROCESS_STATE_CREATED until the person finishes the capture. Read it again after that: the answer turns PROCESS_STATE_FINISHED, with data.humanToken, data.liveness and data.ndocs. Check that data.liveness.value is live before you trust the result.

5. Clean up​

docker rm -f human-plugin human-plugin-db && docker network rm human-plugin

Next​

Last updated on