KYC Tools

KYC (Know Your Customer) tools let your voice agents collect identity information from callers and run an automated risk-scoring verification during the conversation. Two verification types are supported: Individual (personal identity documents and address) and Business (company registration, tax ID, and beneficial owners).

How it works

When an ElevenLabs agent invokes a KYC tool, it follows a three-step pattern:

Call the tool with action: get_requirements to discover which fields are required.
Collect the required information through conversation.
Call the tool with action: verify_individual or action: verify_business with all collected fields.

The tool stores a KycVerification record, calculates a risk score based on the configured weights, and returns a verification_status of approved, pending_review, rejected, or incomplete.

KYC types

Individual KYC

Verifies personal identity. Collects name, date of birth, nationality, country of residence, government ID type and number, address, email, phone, occupation, and source of funds.

Business KYB

Know Your Business verification. Collects business name, registration number, tax ID, business type, incorporation details, business address, authorized representative, and beneficial owners.

Creating a KYC tool

Navigate to KYC Tools

Open KYC Tools in the sidebar and click Create KYC Tool.

Name and type

Enter a name and optional description. Choose Individual KYC or Business KYB as the verification type.

Configure required fields

The form pre-fills with the default fields for the chosen type. For each field you can set whether it is required.Default individual fields:

Field	Required by default
Full name	Yes
Date of birth	Yes
ID type	Yes
ID number	Yes
Nationality	No
Country of residence	No
Address (street, city, state, postal code, country)	No
Email	No
Phone	No
Occupation	No
Source of funds	No

Default business fields:

Field	Required by default
Business name	Yes
Registration number	Yes
Tax ID	Yes
Business type	Yes
Incorporation country	Yes
Representative name	Yes
Incorporation date	No
Business address	No
Representative title / contact	No
Beneficial owners	No

Configure validation rules

Validation rules are regex patterns applied to each field value before the risk score is computed. The defaults enforce common formats:

Field	Default pattern	Notes
`full_name`	`^[a-zA-Z\s\'-]{2,100}$`	Letters, spaces, hyphens
`date_of_birth`	`^\d{4}-\d{2}-\d{2}$`	ISO 8601 date
`email`	Standard email format
`phone`	`^\+?[\d\s\-]{7,20}$`	Optional country code
`nationality` / `country_of_residence`	`^[A-Z]{2}$`	ISO alpha-2 code

Configure risk settings

Risk settings control how the verification score is computed and how outcomes are decided:

Setting	Default	Description
Missing field weight	10	Score added per missing required field
Format failure weight	15	Score added per field that fails its regex
Age verification weight	25	Score added if the subject is under the minimum age
Geographic risk weight	20	Score added for high-risk countries
PEP/sanctions weight	30	Score added if a PEP/sanctions check is triggered
Duplicate check weight	20	Score added for a duplicate submission
Minimum age	18	Minimum acceptable age
Auto-approve threshold	30	Risk scores at or below this value are auto-approved
Review threshold	60	Scores above this value are rejected; scores between approve and review thresholds go to `pending_review`
High-risk countries	`[]`	ISO country codes that increase the geographic risk score
PEP check	`false`	Enable Politically Exposed Person check
Duplicate check	`true`	Reject or flag duplicate submissions

Enable Register immediately to register the tool with ElevenLabs during creation. You can also register later from the tool detail page.

Registering with ElevenLabs

Open the KYC tool detail page

Click the tool name from the KYC Tools index.

Click Register

Click Register with ElevenLabs. Sniko calls POST /convai/tools with the tool configuration:

{
  "tool_config": {
    "name": "kyc_{slug}",
    "description": "...",
    "type": "webhook",
    "response_timeout_secs": 60,
    "api_schema": {
      "url": "https://your-app.com/api/tools/kyc/{id}/{secret}",
      "method": "POST",
      "request_body_schema": {
        "type": "object",
        "required": ["action"],
        "properties": {
          "action": {
            "type": "string",
            "enum": ["verify_individual", "check_status", "get_requirements"]
          },
          "full_name": { "type": "string" },
          "date_of_birth": { "type": "string" }
        }
      }
    }
  }
}

The enum values differ for business tools: verify_business, check_status, get_requirements.

Confirm

On success, the ElevenLabs tool ID is stored and the tool status changes to active.

Updating a registered KYC tool automatically syncs the changes to ElevenLabs via PUT /convai/tools/{elevenlabs_tool_id}.

Assigning to agents

The KYC tool must be registered before it can be assigned to agents.

Open the tool detail page

Navigate to the KYC tool you want to assign.

Click Assign Agents

Provide one or more ElevenLabs agent IDs. The service sends POST /agents/{agentId}/tools for each agent and records the assignment in the KycToolAgent table.

Admins can view all KYC tools across all users. Regular users can only see and manage their own tools.

Webhook endpoint

ElevenLabs posts to the KYC tool webhook when the agent invokes it:

POST /api/tools/kyc/{id}/{secret}

Example get_requirements request:

{ "action": "get_requirements", "conversation_id": "conv_xyz" }

Example individual verification request:

{
  "action": "verify_individual",
  "full_name": "Jane Smith",
  "date_of_birth": "1985-03-22",
  "nationality": "US",
  "id_type": "passport",
  "id_number": "A12345678",
  "email": "jane@example.com",
  "phone": "+14155550100",
  "conversation_id": "conv_xyz"
}

Verification results

Each agent invocation of a KYC tool creates a KycVerification record. View verifications from the tool detail page.

KycVerification fields

Field	Type	Description
`kyc_tool_id`	integer	The KYC tool that processed this verification
`user_id`	integer	The account owner of the tool
`tool_call_id`	string	ElevenLabs tool call ID for the invocation
`agent_id`	string	ElevenLabs agent ID that invoked the tool
`conversation_id`	string	ElevenLabs conversation ID
`verification_type`	string	`individual` or `business`
`collected_data`	JSON	The field values submitted by the agent
`field_results`	JSON	Per-field validation outcomes
`risk_score`	decimal	Computed numeric risk score
`risk_level`	string	`low`, `medium`, `high`, or `critical`
`risk_factors`	JSON	List of factors that contributed to the score
`flags`	JSON	Array of flag strings raised during verification
`verification_status`	string	`approved`, `pending_review`, `rejected`, or `incomplete`
`reviewed_by`	integer	User ID of the reviewer (if manually reviewed)
`review_notes`	string	Notes added during manual review
`reviewed_at`	datetime	When the manual review was completed
`audit_trail`	JSON	Full audit log of actions taken on this verification
`metadata`	JSON	Additional metadata from the conversation
`verification_started_at`	datetime	When the agent first invoked the tool
`verification_completed_at`	datetime	When the final verification decision was made

Risk levels

Level	Meaning
`low`	Risk score ≤ auto-approve threshold — automatically approved
`medium`	Score between thresholds — routed to `pending_review`
`high`	Score above review threshold — rejected
`critical`	Highest risk — rejected and flagged

Analytics

The tool detail page shows:

Total verifications, approval rate, and average risk score
Pending review count
Risk distribution (low / medium / high / critical)
Verification status distribution (approved / pending_review / rejected / incomplete)
Per-field completion rates (for the last 100 processed verifications)
Daily verification trend for the last 30 days with approved/rejected breakdown
Top 10 most frequently raised flags

Get Started

Core Features

Communication Tools

Agent Tools

Integrations

How it works

KYC types

Individual KYC

Business KYB

Creating a KYC tool

Registering with ElevenLabs

Assigning to agents

Webhook endpoint

Verification results

KycVerification fields

Risk levels

Analytics

Build docs developers (and LLMs) love

Get Started

Core Features

Communication Tools

Agent Tools

Integrations

​How it works

​KYC types

Individual KYC

Business KYB

​Creating a KYC tool

​Registering with ElevenLabs

​Assigning to agents

​Webhook endpoint

​Verification results

​KycVerification fields

​Risk levels

​Analytics

Build docs developers (and LLMs) love

How it works

KYC types

Creating a KYC tool

Registering with ElevenLabs

Assigning to agents

Webhook endpoint

Verification results

KycVerification fields

Risk levels

Analytics