Verify caller identity using PIN, date of birth, passphrase, or custom credentials before proceeding with sensitive operations.

Caller Authentication

The Caller Authentication tool requires callers to verify their identity before the agent processes any request. The agent prompts for a credential (PIN, date of birth, passphrase, or custom) and tracks attempts with configurable failure actions.

How It Works

Agent: "Before I can help you, I need to verify your identity. What is your 4-digit PIN?"
Caller: "1234"
-> Agent calls verify_caller_identity with response "1234"
Agent: "Thank you, you've been verified. How can I help you today?"

If the caller fails:

Agent: "I'm sorry, that PIN is incorrect. You have 2 attempts remaining."
Caller: "5678"
-> Agent calls fail_caller_auth
Agent: "That's also incorrect. You have 1 attempt remaining."
Caller: "0000"
-> Agent calls fail_caller_auth (max attempts exceeded)
-> fail_action triggers: end_call, transfer, or continue with limited access

Configuration

{
  "callerAuthEnabled": true,
  "callerAuthType": "pin",
  "callerAuthPrompt": "Please provide your 4-digit security PIN.",
  "callerAuthMaxAttempts": 3,
  "callerAuthFailAction": "end_call",
  "callerAuthTransferTarget": "+14155551234"
}

Setting	Type	Default	Description
`callerAuthEnabled`	boolean	`false`	Enable caller authentication
`callerAuthType`	string	`pin`	Auth type: `pin`, `dob`, `passphrase`, `custom`
`callerAuthPrompt`	string	auto-generated	Custom authentication prompt
`callerAuthMaxAttempts`	integer	`3`	Maximum verification attempts
`callerAuthFailAction`	string	`end_call`	On max failures: `end_call`, `transfer`, `continue`
`callerAuthTransferTarget`	string	—	Phone number for transfer on failure

Auth Types

Type	What the Agent Asks
`pin`	"Please provide your PIN code to verify your identity."
`dob`	"Please provide your date of birth to verify your identity."
`passphrase`	"Please provide your passphrase to verify your identity."
`custom`	Uses your custom `callerAuthPrompt`

LLM Tools

`verify_caller_identity`

Called when the caller provides a correct credential.

Parameters:
  response: string (the caller's authentication response)

Returns: "Caller identity verified successfully. You may now proceed with their request."

`fail_caller_auth`

Called when the caller's credential is incorrect.

Parameters:
  reason: string (why authentication failed)

Returns: "Authentication failed. The caller has {N} attempt(s) remaining."
  or on max attempts: triggers the configured fail_action

Failure Actions

Action	Behavior
`end_call`	Agent says goodbye and hangs up
`transfer`	Agent transfers to the configured phone number
`continue`	Agent continues with limited access (no sensitive operations)

Example — Create Agent with PIN Authentication

curl -X POST https://api.thinnest.ai/v1/agents \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Secure Account Agent",
    "model": "gpt-4o",
    "instructions": "You help customers with account inquiries. Caller must verify their identity before you process any request.",
    "voiceEnabled": true,
    "transcriber": { "provider": "deepgram", "model": "nova-2-conversationalai" },
    "voice": { "provider": "deepgram", "voiceId": "aura-2-thalia-en" },
    "callerAuthEnabled": true,
    "callerAuthType": "pin",
    "callerAuthPrompt": "Please provide your 4-digit security PIN.",
    "callerAuthMaxAttempts": 3,
    "callerAuthFailAction": "end_call"
  }'

Webhook Events

Authentication attempts fire webhook events:

// On attempt
{ "event": "caller.auth_attempt", "attempt": 1, "max_attempts": 3, "auth_type": "pin" }

// On success
{ "event": "caller.authenticated", "auth_type": "pin", "attempts_used": 1 }

// On failure
{ "event": "caller.auth_failed", "attempt": 2, "max_attempts": 3, "reason": "Incorrect PIN" }

Caller Authentication

On this page