codespar_kyc

There is no typed wrapper for codespar_kyc itself — call via session.execute(). Tracking has typed wrappers: session.verificationStatus(toolCallId) and session.verificationStatusStream(toolCallId, opts).

Rails

Direct execute

const inquiry = await session.execute("codespar_kyc", {
  operation: "create_inquiry",
  subject: {
    name: "Maria Silva",
    document: "12345678900",
    email: "maria@example.com",
    document_type: "cpf",
  },
  metadata: { order_id: "1234" },
});

console.log(inquiry.tool_call_id, inquiry.inquiry_id, inquiry.status); // "pending"

Then poll until terminal:

let v = await session.verificationStatus(inquiry.tool_call_id);
while (v.status === "pending") {
  await new Promise((r) => setTimeout(r, 3000));
  v = await session.verificationStatus(inquiry.tool_call_id);
}
// v.status is now approved | rejected | review | expired

Or stream:

await session.verificationStatusStream(inquiry.tool_call_id, {
  onUpdate: (s) => console.log("kyc:", s.status),
});

Args shape

Result shape

type KYCResult = {
  tool_call_id: string;
  inquiry_id: string;
  status: "pending"; // always pending; terminal state via verificationStatus
  inquiry_url?: string; // Persona hosted flow URL when subject must complete steps
};

Terminal verification states (returned by verificationStatus), in poll-priority order:

1. approved — KYC passed.
2. rejected — KYC failed.
3. review — manual review pending (provider human-in-the-loop).
4. expired — verification window timed out.
5. pending — still processing.

The polling priority matters: when multiple events have landed for the same tool_call_id (e.g. review then approved), the endpoint returns the highest-priority terminal state.

Operator setup

• Persona (default) — API key (api_key auth_type). Important: stamp inquiry_template_id in connection_metadata when the operator connects Persona — this is per-tenant operator-stamped, not passed at execute time. Without it the inquiry creation will fail.
• Sift — HTTP Basic auth (API key as username, blank password).
• Konduto — HTTP Basic auth.
• Truora — API key.

The Persona inquiry_template_id lives in connected_accounts.connection_metadata (jsonb) — the dashboard's Persona connect modal renders an extra input for it.

Async verification

Verification follows the same correlation chain as payments — idempotency_key ↔ external_reference resolved via webhook. See async settlement → Verification (KYC) sibling for the full flow.

See also

• SDK reference — verificationStatus
• Async settlement → KYC sibling
• SSE streaming — verificationStatusStream
• KYC Agent cookbook — end-to-end gating example
• Tools & meta-tools — full meta-tool list