> ## 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.

# Link creation

> Create and deliver a verification link with one call to POST /integrations/links: request fields (user_ref, the use case key, delivery_method, return_url, flow_guid), the response, link lifetimes and reuse, GET /integrations/flows, and errors.

This page is for the engineer starting verifications from an ITSM tool, portal, or script. When you finish, one call creates the request, delivers the link to the directory-known channel, and returns the URL and expiry, and you know how to pick a flow and poll the outcome.

The ServiceNow app is built on this endpoint.

```text theme={null}
POST /integrations/links
```

Relative to your workspace's API base URL: `https://agent.truu.ai/api/v1/integrations/links`.

## Authentication

Send an API client credential (a short-lived OAuth access token or an `sk-ti-` API key) with the `idv:verification` scope:

```bash theme={null}
Authorization: Bearer <access token or sk-ti- API key>
```

See [Authentication](https://docs.truu.ai/idv/api/authentication.md) for creating clients and requesting scopes.

## Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `user_ref` | object | Yes | Who to verify. Provide `email`, `phone` (E.164), `upn`, or any combination; at least one is required. The user must resolve in your connected directory. |
| `purpose` | string | No | The [use case](https://docs.truu.ai/idv/use-cases/overview.md) key: `helpdesk`, `reset`, `onboarding`, `default` (the default), or a custom use case's key. The use case's rules pick the flow, and it sets the wording and link lifetime. List the keys your client may send with `GET /integrations/use-cases`. |
| `delivery_method` | string | No | `email`, `sms`, or `link` (the default). `link` returns the URL without sending anything, so your system delivers it. |
| `recipient_email` | string | No | Override delivery address for `email`. Without it, the link goes to the user's directory email. |
| `recipient_mobile` | string | No | Override number (E.164) for `sms`. Without it, the link goes to the user's directory mobile. |
| `context` | object | No | Free-form key-value metadata recorded in the request's client context (for example, a ticket number). |
| `return_url` | string | No | Where to send the user after the verification page reaches a terminal state. Must be HTTPS. Without it, the page shows its own completion screen. |
| `flow_guid` | string | No | Run a specific flow instead of the one the use case's rules select. Must be one of the flows returned by `GET /integrations/flows`. |

> [!WARNING]
>
> Delivery defaults to the directory-known channel, which is the core defense against link redirection. Recipient overrides exist for legitimate cases such as onboarding to a personal address; use them deliberately. Every request records its source and context in the audit trail.

## Response

`201 Created`:

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

| Field | Description |
| - | - |
| `request_id` | The verification request. Poll it at `GET /helpdesk/requests/{request_id}`. |
| `short_url` | The link on `verify.truu.ai`. With `delivery_method: link`, this is what your system sends. |
| `expires_at` | When the link stops working, set by `purpose`. |

## Link lifetime and reuse

| Use case key | Lifetime |
| - | - |
| `helpdesk` | 30 minutes |
| `reset` | 1 hour |
| `onboarding` | 7 days |
| `default` | 30 minutes |

If an active request already exists for the same user and use case, the call **reuses it**: you get the same `request_id` and link back with a refreshed `expires_at`, instead of a duplicate. Retrying a create after a timeout is therefore safe for the same user and use case.

## Listing available flows

```text theme={null}
GET /integrations/flows
```

Returns the flows in your workspace as a list of `flow_guid` and `name`, so you can populate a picker in your tool or pin a link to a specific flow with `flow_guid`. Requires `idv:verification`.

```json theme={null}
[
  {"flow_guid": "3f9c2a1e-6b7d-4c8e-9f01-2a3b4c5d6e7f", "name": "Standard Corporate Flow"},
  {"flow_guid": "8a1d4e2f-0b3c-4d5e-8f67-1a2b3c4d5e6f", "name": "Catch All Flow"}
]
```

## Errors

| Code | Status | Meaning |
| - | - | - |
| `DIRECTORY_NOT_CONNECTED` | 404 | Your workspace has no connected directory to resolve users against. |
| `USER_NOT_IN_DIRECTORY` | 404 | `user_ref` did not resolve to a directory user. |
| `NO_EMAIL_ON_RECORD` / `NO_MOBILE_ON_RECORD` | 422 | Delivery method chosen but the directory has no address or number for the user and no override was given. |
| `VALIDATION_ERROR` | 422 | A field failed validation: a non-E.164 phone, a non-HTTPS `return_url`, or a `flow_guid` that is not available to the caller. |
| `EMAIL_DELIVERY_FAILED` / `SMS_DELIVERY_FAILED` | 503 | The provider rejected or failed the send. |
| `INSUFFICIENT_PERMISSIONS` | 403 | The credential lacks the `idv:verification` scope. |
| `REQUESTER_NOT_AUTHORIZED` | 403 | The client requires a requester (`requested_by`) from a specific group, and the requester isn't in it. |
| `VALIDATION_ERROR` | 422 | Also returned when `purpose` is unknown, disabled, or not allowed for this client. |
| (401) | 401 | The client was revoked or its credential is invalid. |

See [Errors](https://docs.truu.ai/idv/api/errors.md) for the envelope and retry guidance.

## Example

```bash curl theme={null}
curl -X POST "https://agent.truu.ai/api/v1/integrations/links" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ref": {"email": "nsharma@acme.com"},
    "purpose": "helpdesk",
    "delivery_method": "sms",
    "context": {"ticket": "INC0012345"},
    "return_url": "https://helpdesk.acme.com/verified"
  }'
```

```python Python theme={null}
import httpx

BASE = "https://agent.truu.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {ACCESS_TOKEN}"}

resp = httpx.post(
    f"{BASE}/integrations/links",
    headers=HEADERS,
    json={
        "user_ref": {"email": "nsharma@acme.com"},
        "purpose": "helpdesk",
        "delivery_method": "sms",
        "context": {"ticket": "INC0012345"},
        "return_url": "https://helpdesk.acme.com/verified",
    },
)
resp.raise_for_status()
link = resp.json()
print(link["short_url"], link["expires_at"])
```

> [!TIP]
>
> Prefer `email` over `sms` unless you have checked phone coverage. In most directories a large share of mobile numbers are missing or not in E.164 format, and many organizations restrict SMS. Email coverage is usually far higher.

## Track the outcome

Poll the request until it reaches a terminal state:

```python theme={null}
import time

TERMINAL = {"verified", "expired", "failed", "cancelled", "declined"}
while True:
    req = httpx.get(f"{BASE}/helpdesk/requests/{link['request_id']}", headers=HEADERS).json()
    if req["status"] in TERMINAL:
        break
    time.sleep(3)
```

The request's `progress_events` timeline records every step, so you can write the full sequence into a ticket from a single GET. ServiceNow customers get this pushed automatically; see the [ServiceNow integration](https://docs.truu.ai/idv/connect/servicenow.md). Generic webhooks are not available; see [Webhooks](https://docs.truu.ai/idv/api/webhooks).


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