---
title: "Lookup Client"
method: POST
path: "/vapi/lookup-client"
tags: ["Vapi"]
---

# Lookup Client

`POST /vapi/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

## Request body

- VapiCustomToolRequest — Wrapper for Vapi custom tool requests.
  - `message` VapiMessage, required
    - `type` string, required
    - `toolCallList` VapiToolCall[], required
      - `id` string, required
      - `type` string
      - `function` VapiToolCallFunction, required
        - `name` string, required
        - `arguments` object, required
    - `call` VapiCallObject
      - `id` string, required

## Response `200`

Successful Response

- VapiCustomToolResponse — Standard Vapi custom tool response format.
  - `results` VapiToolResult[], required
    - `toolCallId` string, required
    - `result` string, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/openintake/apis/fastapi.md) · [All operations](https://skmtc.dev/openintake/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openintake/fastapi/revisions/b642b91e0a5c/schema)