Skip to main content
The TruU IDV API gives you programmatic access to everything the IDV Console and help desk app can do: create and deliver verification links, track requests, run verification sessions, manage factors and flows, connect a directory, and read or export the audit trail.

What you can build

Automate configuration

Manage factor definitions and flows from scripts or CI for bulk configuration and migration between environments.

Consume verification results

Poll request status, update tickets, gate downstream automation on a verified outcome, and pull audit evidence into your SIEM through the export API.

Create verification links from your systems

One call to POST /integrations/links creates a request, delivers the link, and returns the URL and expiry. This is the endpoint the ServiceNow app uses, and the fastest way to wire verification into any ITSM or portal.

Build a custom verification surface

Use the session APIs (/verify/start, /verify/execute, /verify/complete) to embed verification in your own application instead of the hosted page.

Base URL

All endpoints in the reference are relative to your workspace’s API base URL:
OAuth and discovery endpoints (/oauth/token, /.well-known/*) live at the API origin root, above the /api/v1 base path.

API groups

The complete endpoint reference is generated from the OpenAPI specification and appears in the navigation alongside these guides.

A typical integration

Verification requests move through a fixed lifecycle:
verified, failed, expired, cancelled, and declined are terminal. The progress_events array on the request records each step (preflight skips, factor successes and failures, fallbacks, and the final outcome), so you can render a timeline or write work notes from a single GET.

Versioning

The API is versioned in the URL path (/v1). Within a version, changes are backwards-compatible: new fields, new endpoints, and new enum values may be added, but existing fields are not renamed or removed. Build clients that ignore unknown fields.

Authentication

Server-to-server calls authenticate with OAuth 2.0 client credentials (ES256-signed access tokens valid for 15 minutes) or a long-lived sk-ti- API key. You create an M2M client in the IDV Console (under Settings → API clients), then either exchange its credentials at POST /oauth/token for a short-lived access token or send a long-lived sk-ti- API key directly. Each client carries idv:* scopes that gate what it can call. Verification session calls use the session token returned by start. The complete scope list: See Authentication for clients, scopes, and rotation.

Rate limiting

Requests that return 429 carry a Retry-After header; honor it before retrying. Repeated failed authentications temporarily lock the client (error code M2M_CLIENT_LOCKED). API keys have a maximum lifetime and a short grace window after rotation; see Authentication.

Errors

All errors share a single JSON envelope with a stable code, a human-readable message, and optional details. See Errors for the full status code and error code reference.
Outbound webhooks are not available. Poll request status as shown above, or use the ServiceNow connector, which pushes lifecycle events to your instance.