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", {
  check_type: "identity",
  buyer: {
    name: "Maria Silva",
    document: "12345678900",
    country: "BR",
    email: "maria@example.com",
  },
  metadata: { order_id: "1234" },
});

console.log(inquiry.tool_call_id, inquiry.data.verification_id, inquiry.data.status);

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

For onboarding, check_type: "status" returns pending, documentscopy_pending (with a hosted_url where the consumer finishes document capture), approved (with the funding source and the Pix key), rejected, or unknown when the provider state cannot be resolved yet. In sandbox, a phoneNumber ending in 1 auto-approves both gates.

Result shape

type ToolResult = {
  success: boolean;
  data: {
    verification_id: string;
    status: string;        // provider status on create (e.g. CREATED, PROCESSING); the verdict comes from polling
    hosted_url: string | null; // hosted-flow URL when the provider needs the subject to complete steps
    check_type: string;
  };
  error: string | null;
  tool_call_id?: string;
};

For onboarding, the create call returns hosted_url: null; the document-capture link is surfaced by check_type: "status" while the state is documentscopy_pending.

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