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 prefersmeta: {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-namemeta: 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")
generate-one-time-link
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))
one-time-link
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"
print-inquiry
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"])
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"]})