> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API quickstart

> Send your first verification from your own system in five minutes: create an API client with the idv:verification scope, get an access token, create a link with curl, and poll for the result.

This page is for the developer connecting a portal, chatbot, ticketing tool or script to TruU IDV. When you finish you will have sent a verification link with `curl` and read its result.

## Before you start

* An **Owner** or **Admin** seat, to create the API client.
* A connected directory with at least one person you can verify (yourself is fine).
* `curl` and `jq`.

## 1. Create an API client

**1. Open API clients**

In the console, go to **Settings → API clients** and choose **Create client**.

**2. Name it and pick an auth method**

Give it a **Name** that says what uses it, for example "Self-service portal". Under **Auth method**, choose **Client secret** (standard OAuth 2.0 client credentials). The other options are **Private key (JWT)**, where you register a public JWK, and **Bearer token**, a long-lived `sk-ti-` API key for platforms that can't exchange tokens.

**3. Grant only the scope you need**

Under **Scopes**, select **Run verification** (`idv:verification`). It lets the client create verification links and read their status, and nothing else.

**4. Set an expiration and create**

Pick an **Expiration**, choose **Create client**, and copy the **Client ID**, **Client secret** and **Token endpoint**. The secret is shown once; put it in your secrets manager.

## 2. Get an access token

Exchange the client's credentials for a short-lived access token (15 minutes):

```bash theme={null}
export TRUU_CLIENT_ID="your-client-id"
export TRUU_CLIENT_SECRET="your-client-secret"

TOKEN=$(curl -s -X POST "https://agent.truu.ai/oauth/token" \
  -u "$TRUU_CLIENT_ID:$TRUU_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=idv:verification" | jq -r .access_token)
```

Use the **Token endpoint** shown when you created the client if it differs. Fetch a new token when it expires rather than caching it. With a **Bearer token** client, skip this step and use the `sk-ti-` key wherever `$TOKEN` appears.

## 3. See which use cases you can send

```bash theme={null}
curl -s "https://agent.truu.ai/api/v1/integrations/use-cases" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
[
  { "key": "onboarding", "label": "Onboarding" },
  { "key": "reset", "label": "Credential reset" },
  { "key": "helpdesk", "label": "Helpdesk" },
  { "key": "default", "label": "Verification" }
]
```

The `key` is what you send as `purpose`. The [use case](https://docs.truu.ai/idv/use-cases/overview.md) decides which flow the person gets and what they're told.

## 4. Create a verification link

```bash theme={null}
curl -s -X POST "https://agent.truu.ai/api/v1/integrations/links" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ref": { "email": "you@contoso.com" },
    "purpose": "reset",
    "delivery_method": "email",
    "context": { "ticket": "INC0012345" }
  }'
```

```json theme={null}
{
  "request_id": "3f9c2a7e-5b14-4d8e-9a61-2c7f0e4b8d35",
  "short_url": "https://verify.truu.ai/v/aB3xY9pQ",
  "expires_at": "2026-10-07T17:45:00Z"
}
```

* `user_ref` identifies the person by `email`, `upn` or `phone`; they must exist in your directory.
* `delivery_method` is `email` or `sms` (sent to the contact on file), or `link` to get the URL back and deliver it yourself.
* Sending again for the same person and use case returns the same request with a fresh expiry, so retries are safe.

Open the link from your inbox and complete the verification.

## 5. Read the result

```bash theme={null}
curl -s "https://agent.truu.ai/api/v1/helpdesk/requests/3f9c2a7e-5b14-4d8e-9a61-2c7f0e4b8d35" \
  -H "Authorization: Bearer $TOKEN" | jq '{status, progress_events}'
```

Poll every few seconds until `status` is final:

| `status` | Meaning |
| - | - |
| `pending`, `in_progress` | Not finished |
| `needs_review` | Waiting for a reviewer |
| `verified` | Passed. Act on this, and only this. |
| `failed`, `declined`, `expired`, `cancelled` | Ended without passing |

`progress_events` lists each step (factor attempts, fallbacks, the outcome) if you want to show a timeline or write a ticket note.

> [!WARNING]
>
> Gate your downstream action (password reset, account unlock) on `verified` only.

## Next steps

* Keep the client secret in a secrets manager and rotate it from **Settings → API clients**, open the client, then **Rotate credential**; the old credential keeps working for a grace window. See [Authentication](https://docs.truu.ai/idv/api/authentication.md).
* Full request and response fields: [Links](https://docs.truu.ai/idv/api/links.md). Error codes: [Errors](https://docs.truu.ai/idv/api/errors.md).
* Building for a help desk? The [ServiceNow](https://docs.truu.ai/idv/connect/servicenow.md) and [Microsoft Teams](https://docs.truu.ai/idv/connect/microsoft-teams.md) connectors already do this for you.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.