Skip to main content
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.
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:
See Authentication for creating clients and requesting scopes.

Request body

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

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.

Errors

See Errors for the envelope and retry guidance.

Example

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:
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. Generic webhooks are not available; see Webhooks.