Lookup Client

Look up an existing client, either by name + date of birth or by a server-injected contact id.

Vapi custom tool. Two argument modes:

• first_name + last_name + date_of_birth (YYYY-MM-DD): identify by name and DOB against synced SmartAdvocate contacts.
• contact_id: the saContactId variable injected at call start from the caller-ID phone match. Verified server-side against the calling number (message.call.customer.number) — an id that doesn't belong to a contact matching the caller's phone returns match=none, so the model cannot look up arbitrary contacts. Use only after the caller confirms the injected name.

Returns one of three shapes:

• match=exact: the client's cases and upcoming appointments
• match=candidates: contacts sharing the DOB when the name doesn't match exactly, so the agent can retry with a corrected name
• match=none: no matching contact