API Reference

Verify

Compare two values using one of 7 match strategies. Designed to be called from your server_url tool handler to verify caller-provided answers against stored records -- for identity verification flows, caller authentication, and input validation.

POST/v1/verify

Field	Type	Required	Description
expected	string	required	The known correct value (e.g. from your database)
answer	string	required	The value the caller provided (as transcribed by STT)
match_type	string	optional	One of the 7 match strategies (default: phonetic)

curl -X POST https://api.staffifyai.com/v1/verify \
  -H "Authorization: Bearer sfy_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "answer":     "one two three four",
    "expected":   "1234",
    "match_type": "numeric"
  }'

Response

{
  "verified":   true,
  "match_type": "fuzzy_date"
}

verified: true/false based on the internal threshold for the selected strategy.

Match types

phonetic

Soundex + Levenshtein. Tolerates 2 edits for short strings, 3 for medium, ~40% for long. Handles email-style strings separately.

Use case: Caller says their name -- "Smith" matches "Smyth"

numeric

Numeric equality after stripping spaces, dashes, and dots

Use case: "1 2 3 4" matches "1234"

alphanumeric

Case-insensitive exact match after stripping spaces and dashes

Use case: Reference codes, order IDs

alphanumeric_fuzzy

Levenshtein distance ≤ 1. Designed for audio confusions like E↔C, B↔D.

Use case: Slight typos or mishearings in spoken text

fuzzy_date

Handles English, Dutch, and German month names; digit-by-digit input; EU and US date order. "April 23rd 1987" matches "1987-04-23".

Use case: Date of birth verification

last_4_digits

Extracts and compares the last 4 digits from both values

Use case: SSN last 4, card last 4

phone_number

Normalizes NL, BE, DE, UK international prefixes to local format, then compares

Use case: Callback number verification

Examples

Verify date of birth (spoken vs ISO format)

curl -X POST https://api.staffifyai.com/v1/verify \
  -H "Authorization: Bearer sfy_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expected":   "1987-04-23",
    "answer":     "April twenty-third nineteen eighty seven",
    "match_type": "fuzzy_date"
  }'

Verify account number last 4

curl -X POST https://api.staffifyai.com/v1/verify \
  -H "Authorization: Bearer sfy_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expected":   "4242424242424242",
    "answer":     "4 2 4 2",
    "match_type": "last_4_digits"
  }'

Phonetic name match

curl -X POST https://api.staffifyai.com/v1/verify \
  -H "Authorization: Bearer sfy_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expected":   "Smith",
    "answer":     "Smythe",
    "match_type": "phonetic"
  }'

Integration patterns

Pattern 1: Spoken answer (AI asks, caller speaks)

Define a tool in your call.started response. The AI asks the caller to state their date of birth verbally. Your handler calls /v1/verify with the transcribed answer.

// Tool definition in call.started response
{
  "name":        "verify_dob",
  "description": "Verify the caller's date of birth. Ask them to state it verbally.",
  "parameters": {
    "type": "object",
    "properties": {
      "dob_spoken": { "type": "string", "description": "Date of birth as stated by the caller" }
    },
    "required": ["dob_spoken"]
  }
}

// Tool handler
case 'verify_dob': {
  const customer = await db.getCustomerByPhone(from);
  if (!customer) return res.json({ result: { verified: false, reason: 'Not found' } });

  const { verified } = await fetch('https://api.staffifyai.com/v1/verify', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.STAFFIFY_API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      expected:   customer.date_of_birth, // "1987-04-23" from DB
      answer:     args.dob_spoken,        // "April 23rd 1987" from caller
      match_type: 'fuzzy_date',
    }),
  }).then(r => r.json());

  return res.json({
    result: verified
      ? { verified: true,  name: customer.name, tier: customer.tier }
      : { verified: false, reason: 'Date of birth did not match' },
  });
}

Pattern 2: DTMF keypress (caller presses digits)

Add a gather field to the tool definition. When the AI calls the tool, Staffify plays your prompt and waits for the caller to press digits. The digits arrive in args.gathered_input. No STT -- so there are no transcription variations to worry about.

// Tool definition -- the gather field triggers DTMF collection
{
  "name":        "verify_ssn_last4",
  "description": "Verify identity using the last 4 digits of the caller's SSN.",
  "parameters":  { "type": "object", "properties": {} },
  "gather": {
    "prompt":          "Please enter the last 4 digits of your Social Security Number.",
    "max_digits":      4,
    "timeout_seconds": 15,
    "terminator":      ""
  }
}

// Tool handler -- gathered_input contains the 4 digits pressed
case 'verify_ssn_last4': {
  const { gathered_input, gather_status } = args;
  if (gather_status !== 'valid' || !gathered_input) {
    return res.json({ result: { verified: false, reason: 'No input received' } });
  }

  const customer = await db.getCustomerByPhone(from);
  if (!customer) return res.json({ result: { verified: false, reason: 'Not found' } });

  const { verified } = await fetch('https://api.staffifyai.com/v1/verify', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.STAFFIFY_API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      expected:   customer.ssn,       // full SSN -- /v1/verify extracts last 4
      answer:     gathered_input,     // e.g. "1234"
      match_type: 'last_4_digits',
    }),
  }).then(r => r.json());

  return res.json({
    result: verified
      ? { verified: true,  name: customer.name }
      : { verified: false, reason: 'SSN did not match' },
  });
}

DTMF-based verification is more reliable than spoken digit verification because there is no speech-to-text step. Use it for SSN last 4, PIN codes, account numbers, and postal codes. See the mid-call DTMF guide for the full gather field reference.

← server_url Guide Credits →