Inquiries: one end user's run through an inquiry template (KYC or KYB). Create one, send the user to the hosted flow (a one-time link, or a resume link with a session token), wait for the inquiry.* webhook, read the result, then approve, decline or mark it for review.

Statuses: created, pending, completed, needs_review, approved, declined, failed, expired. See ::persona::decisions/inquiry-decision to normalize them.

Values

DONE_STATUSES

DONE_STATUSES: Vec [
  "completed",
  "needs_review",
  "approved",
  "declined",
  "failed",
  "expired"
]

HOSTED_FLOW_SECRET_KEYS

HOSTED_FLOW_SECRET_KEYS: Vec [
  "session-token",
  "session_token",
  "sessionToken",
  "one-time-link",
  "one_time_link",
  "oneTimeLink",
  "one-time-link-short",
  "one_time_link_short",
  "oneTimeLinkShort"
]

Functions

add-tag

fn (inquiry-id: Str, tag-name: Str): Map
fn (inquiry-id: Str, tag-name: Str, options: Map): Map

POST /inquiries/{id}/add-tag - Add a tag by name.

Example

::persona::inquiries/add-tag("inq_123", "escalated")

approve-inquiry

fn (inquiry-id: Str): Map
fn (inquiry-id: Str, comment: Str?): Map
fn (inquiry-id: Str, comment: Str?, options: Map): Map

POST /inquiries/{id}/approve - Approve an inquiry, with an optional reviewer comment. Fires inquiry.approved.

Example

::persona::inquiries/approve-inquiry("inq_123")

// With a reviewer comment and per-call options
::persona::inquiries/approve-inquiry("inq_123", "Documents match.", {idempotency-key: "inq_123-approve"})

collect-inquiries

fn (filters: Map, limit: Int): Vec
fn (filters: Map, limit: Int, options: Map): Vec

Up to limit inquiries matching filters (see list-inquiries), following cursors.

Example

queue ::persona::inquiries/collect-inquiries({status: ["needs_review"]}, 500)
map(queue, %.id)

create-body

fn (template-id: Str, opts: Map): Map

The JSON:API body for create-inquiry. Exposed for testing.

Example

::persona::inquiries/create-body("itmpl_1", {reference-id: "user-42"})
// {data: {attributes: {inquiry-template-id: "itmpl_1", reference-id: "user-42"}}}

create-inquiry

fn (template-id: Str): Map
fn (template-id: Str, opts: Map): Map
fn (template-id: Str, opts: Map, options: Map): Map

POST /inquiries - Create an inquiry from a template (itmpl_..., itmplv_... or legacy tmpl_...).

opts (all optional):

  • reference-id: your user id (Persona now prefers meta: {auto-create-account-reference-id: ...})
  • account-id: attach to an existing account (act_...)
  • fields: prefill, e.g. {name-first: "Jane", birthdate: "1990-01-31"} (template field keys; plain values). These are PII; they go in the request body only, never a URL.
  • note, tags, redirect-uri, theme-set-id, initial-step-name
  • meta: e.g. {auto-create-account-reference-id: "user-42", auto-create-one-time-link: true, auto-create-inquiry-session: true, expiration-after-create-interval-seconds: 86400}

Pass {idempotency-key: ...} as the trailing options so a retry can't create a second inquiry.

Example

inquiry ::persona::inquiries/create-inquiry("itmpl_...", {
  reference-id: "user-42",
  meta: {auto-create-one-time-link: true}
}, {idempotency-key: "user-42-kyc"})
inquiry.data.id              // "inq_..."
inquiry.meta.one-time-link   // send this to the user

decline-inquiry

fn (inquiry-id: Str): Map
fn (inquiry-id: Str, comment: Str?): Map
fn (inquiry-id: Str, comment: Str?, options: Map): Map

POST /inquiries/{id}/decline - Decline an inquiry, with an optional reviewer comment. Fires inquiry.declined.

Example

::persona::inquiries/decline-inquiry("inq_123", "Document is expired.")

expire-inquiry

fn (inquiry-id: Str): Map
fn (inquiry-id: Str, options: Map): Map

POST /inquiries/{id}/expire - Expire every session and cancel pending verifications. The inquiry can still be resumed.

Example

::persona::inquiries/expire-inquiry("inq_123")
fn (inquiry-id: Str): Map
fn (inquiry-id: Str, expires-in-seconds: Int?): Map
fn (inquiry-id: Str, expires-in-seconds: Int?, options: Map): Map

POST /inquiries/{id}/generate-one-time-link - A single-use hosted-flow link (meta.one-time-link, plus meta.one-time-link-short), valid for expires-in-seconds (default 24 hours). Resume an expired inquiry first. Read it with one-time-link.

Example

out ::persona::inquiries/generate-one-time-link("inq_...", 3600)
::persona::inquiries/one-time-link(out)  // "https://inquiry.withpersona.com/verify?code=..."

get-inquiry

fn (inquiry-id: Str): Map
fn (inquiry-id: Str, opts: Map): Map
fn (inquiry-id: Str, opts: Map, options: Map): Map

GET /inquiries/{id} - Retrieve an inquiry. opts.include lists relationships to embed in included (since 2025-10-27 nothing is included unless asked), e.g. ["verifications", "reports", "account", "documents", "sessions"]; opts.fields takes sparse fieldsets.

Example

inquiry ::persona::inquiries/get-inquiry("inq_...", {include: ["verifications", "reports"]})

hosted-flow-url

fn (template-id: Str, opts: Map): Str

A hosted-flow link that creates a new inquiry when opened: https://inquiry.withpersona.com/verify?inquiry-template-id=....

opts (all optional): environment-id (env_..., from the dashboard; required for sandbox templates), reference-id or account-id, account-type-id, redirect-uri (Persona appends ?inquiry-id=...), language, theme-set-id, style-variant.

Field prefill (fields[...]) is deliberately not supported: values in a URL end up in browser history, proxies and logs. To prefill PII, create the inquiry with create-inquiry(..., {fields: ...}) and send a generate-one-time-link or resume-url link instead.

Example

::persona::inquiries/hosted-flow-url("itmpl_abc", {environment-id: "env_123", reference-id: "user-42"})
// => "https://inquiry.withpersona.com/verify?inquiry-template-id=itmpl_abc&environment-id=env_123&reference-id=user-42"

is-done

fn (doc: Any): Bool

True when the end user has nothing left to do: the status is completed, needs_review, approved, declined, failed or expired. Use it after a webhook, or from a scheduled check, instead of waiting in a run.

Example

::persona::inquiries/is-done({data: {id: "inq_1", type: "inquiry", attributes: {status: "completed"}}})  // true
::persona::inquiries/is-done({data: {id: "inq_2", type: "inquiry", attributes: {status: "pending"}}})  // false

is-sandbox-key

fn (api-key: Any): Bool

True when an API key is a sandbox key (persona_sandbox_...). Exposed for testing.

Example

::persona::inquiries/is-sandbox-key("persona_sandbox_abc")  // true
::persona::inquiries/is-sandbox-key("persona_production_abc")  // false

list-inquiries

fn (filters: Map): Map
fn (filters: Map, opts: Map): Map
fn (filters: Map, opts: Map, options: Map): Map

GET /inquiries - One page of inquiries, newest first. filters become filter[...]: reference-id, account-id, inquiry-id, inquiry-template-id, template-id, status (Vec values are comma-joined), created-at-start, created-at-end, note. opts: page-size (1-100), after, before. Continue with ::persona::api/next-cursor(page).

Example

page ::persona::inquiries/list-inquiries({status: ["needs_review"]}, {page-size: 50})

mark-for-review

fn (inquiry-id: Str): Map
fn (inquiry-id: Str, options: Map): Map

POST /inquiries/{id}/mark-for-review - Move an inquiry to needs_review for a human. Not allowed once approved or declined.

Example

::persona::inquiries/mark-for-review("inq_123")

mark-hosted-flow-secrets

fn (response: Result): Any

Mask a response's session token and one-time links in call records and return the response unchanged. Each one lets anyone continue the user's verification. An Err passes through. Exposed for testing.

Example

response ::persona::api/send("POST", "/inquiries/inq_123/resume", {}, null, {})
::persona::inquiries/session-token(::persona::inquiries/mark-hosted-flow-secrets(response))
fn (doc: Any): Str?

The meta.one-time-link of a response (any inflection), or null.

Example

::persona::inquiries/one-time-link({meta: {one_time_link: "https://inquiry.withpersona.com/verify?code=abc"}})
// "https://inquiry.withpersona.com/verify?code=abc"
fn (inquiry-id: Str): Bytes
fn (inquiry-id: Str, options: Map): Bytes

GET /inquiries/{id}/print - The inquiry as a PDF (Bytes). It contains the user's PII and document images: store it like the originals, never log it.

Example

pdf ::persona::inquiries/print-inquiry("inq_123")
length(pdf)

redact-inquiry

fn (inquiry-id: Str): Map
fn (inquiry-id: Str, options: Map): Map

DELETE /inquiries/{id} - Permanently remove the inquiry's PII (child objects are redacted asynchronously). Cannot be undone.

Example

::persona::inquiries/redact-inquiry("inq_123")

remove-tag

fn (inquiry-id: Str, tag-name: Str): Map
fn (inquiry-id: Str, tag-name: Str, options: Map): Map

POST /inquiries/{id}/remove-tag - Remove a tag by name.

Example

::persona::inquiries/remove-tag("inq_123", "escalated")

resume-inquiry

fn (inquiry-id: Str): Map
fn (inquiry-id: Str, options: Map): Map

POST /inquiries/{id}/resume - Resume a pending or expired inquiry and get a session token for the hosted flow (meta.session-token; read it with session-token). Persona returns 409 for other statuses. A session token lets anyone continue the user's verification: treat it as a secret and never log it.

Example

resumed ::persona::inquiries/resume-inquiry("inq_...")
url ::persona::inquiries/resume-url("inq_...", ::persona::inquiries/session-token(resumed))

resume-url

fn (inquiry-id: Str, session-token: Str): Str

The hosted-flow link that continues an existing inquiry: ...?inquiry-id=inq_...&session-token=.... Get the token from resume-inquiry. The link carries a session token: send it only to the user, and don't log it.

Example

::persona::inquiries/resume-url("inq_123", "sess_abc")
// "https://inquiry.withpersona.com/verify?inquiry-id=inq_123&session-token=sess_abc"

search-inquiries

fn (query: Map): Map
fn (query: Map, opts: Map): Map
fn (query: Map, opts: Map, options: Map): Map

POST /inquiries/search - Search with a predicate tree. query is a predicate {attribute, operator: "eq"|"gt"|"gte"|"lt"|"lte", value} or {and: [...]}/{or: [...]}/{not: ...}; opts takes sort ({attribute, direction}) and page-size. Search is eventually consistent: don't use it to read your own writes.

Example

::persona::inquiries/search-inquiries({attribute: "status", operator: "eq", value: "needs_review"}, {page-size: 20})

session-token

fn (doc: Any): Str?

The meta.session-token of a create or resume response (any inflection), or null.

Example

::persona::inquiries/session-token({meta: {session-token: "sess_abc"}})  // "sess_abc"
::persona::inquiries/session-token({meta: {}})  // null

simulate

fn (inquiry-id: Str, actions: Vec): Map
fn (inquiry-id: Str, actions: Vec, options: Map): Map

POST /inquiries/{id}/perform-simulate-actions - Sandbox only: drive an inquiry through its lifecycle and fire the real webhooks. actions is a Vec of action names: start_inquiry, complete_inquiry, fail_inquiry, expire_inquiry, mark_for_review_inquiry, approve_inquiry, decline_inquiry. Refuses (without sending) unless the key in use is a persona_sandbox_ key.

Example

::persona::inquiries/simulate("inq_...", ["start_inquiry", "complete_inquiry"])
Context Vars: persona.api.key

status

fn (doc: Any): Str?

An inquiry's status from a document or resource, or null.

Example

::persona::inquiries/status({data: {id: "inq_1", type: "inquiry", attributes: {status: "approved"}}})  // "approved"

template-attribute

fn (template-id: Str): Map

The create attribute for a template id: itmplv_... is inquiry-template-version-id, legacy tmpl_... is template-id, anything else (itmpl_...) is inquiry-template-id. Exposed for testing.

Example

::persona::inquiries/template-attribute("itmpl_1")  // {inquiry-template-id: "itmpl_1"}
::persona::inquiries/template-attribute("itmplv_1")  // {inquiry-template-version-id: "itmplv_1"}
::persona::inquiries/template-attribute("tmpl_1")  // {template-id: "tmpl_1"}

update-inquiry

fn (inquiry-id: Str, attributes: Map): Map
fn (inquiry-id: Str, attributes: Map, options: Map): Map

PATCH /inquiries/{id} - Update note, fields, tags or redirect-uri. Unset keys are left alone.

Example

::persona::inquiries/update-inquiry("inq_123", {note: "Escalated by agent", tags: ["escalated"]})