Skip to main content

​
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"
}
SettingTypeDefaultDescription
callerAuthEnabledbooleanfalseEnable caller authentication
callerAuthTypestringpinAuth type: pin, dob, passphrase, custom
callerAuthPromptstringauto-generatedCustom authentication prompt
callerAuthMaxAttemptsinteger3Maximum verification attempts
callerAuthFailActionstringend_callOn max failures: end_call, transfer, continue
callerAuthTransferTargetstring—Phone number for transfer on failure

​
Auth Types

TypeWhat 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.”
customUses 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

ActionBehavior
end_callAgent says goodbye and hangs up
transferAgent transfers to the configured phone number
continueAgent 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" }