---
title: Quickstart
description: Run Human Plugin and a PostgreSQL database with Docker, create a Human Token process and read it back with curl.
canonical: https://developer.unico.io/human-plugin/get-started/quickstart
locale: en
generated_by: markdown-export
---

# Quickstart

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

This page runs Human Plugin alongside a throwaway PostgreSQL container for a quick start on your environment. To deploy it, see [Docker Compose](/human-plugin/self-hosting/docker-compose) or [Kubernetes](/human-plugin/self-hosting/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](/human-plugin/get-started/prerequisites).

## 1. Get the image

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

```bash
echo "<token>" | docker login pkg.unico.run -u <username> --password-stdin
```

```bash
docker pull pkg.unico.run/human-plugin-api:latest
```

## 2. Start PostgreSQL and Human Plugin

```bash
docker network create human-plugin
```

```bash
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:

```bash
export HUMAN_API_ACCESS_KEY='<your access key>'
```

```bash
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](/human-plugin/self-hosting/configuration).

Check that Human Plugin is ready:

```bash
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](/human-plugin/api-reference/create-process#flows). `clientId`, `correlationId` and `credential` are the same in every flow.

### humantoken (the person captures)

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

```bash
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"
  }'
```

```json
{
  "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.

### api+humantoken (you send the selfie)

Your back-end already has the selfie and sends it in `imageBase64`. The answer is final, with the Human Token and the intelligence.

```bash
curl -s -X POST http://127.0.0.1:8080/v1/processes \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": "api+humantoken",
    "clientId": "client-a",
    "correlationId": "quickstart-002",
    "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
    "imageBase64": "<base64 selfie>"
  }'
```

```json
{
  "id": "5d1f7c2e-1b8a-4e0f-9a4b-2f6c3d9e8a71",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "ndocs": {
      "distinctClientsCount": 1,
      "transactionsCount": 1,
      "firstSeen": "2026-11-03",
      "lastSeen": "2026-11-03",
      "credentials": [
        { "type": "DUI_TYPE_NG_BVN", "countryCode": "NGA", "distinctCredentialCount": 1 }
      ]
    }
  }
}
```

- `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](/human-plugin/additional-resources/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](/human-plugin/get-started/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`](/human-plugin/api-reference/create-process#result).

## 4. Read it back

Replace the id with the one from your response:

```bash
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

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

## Next

- [Flows](/human-plugin/api-reference/create-process#flows): which flow to use and what each one needs.
- [Create a process](/human-plugin/api-reference/create-process): every field and rule.
- [Integrate your backend](/human-plugin/integrations/backend): what to store and how to handle failures.
- [Human Token Journey](/human-plugin/integrations/human-token-journey): the capture journey.
- Capture guides for [Web](/human-plugin/integrations/web), [Android](/human-plugin/integrations/android), [iOS](/human-plugin/integrations/ios), [Ionic](/human-plugin/integrations/ionic), [React Native](/human-plugin/integrations/react-native) and [Flutter](/human-plugin/integrations/flutter): the front-end side of the capture.
- [Run Human Plugin in your infrastructure](/human-plugin/self-hosting/overview)