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

# Lookup Client

`POST /vapi/lookup-client`

## Request

- Base URL: `https://api.openintake.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.openintake.ai/vapi/lookup-client`
- Auth: HTTP bearer

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
    - `artifact` object, nullable
    - `assistant` object, nullable

## 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

## Changes

- **2026-09-14** `2ad5aecbce08`: 2 info
  - added the new optional request property `message/artifact`
  - added the new optional request property `message/assistant`

[Operation history](https://skmtc.dev/openintake/apis/openintake-api/changes/vapi/lookup-client/post.md)

---

[API](https://skmtc.dev/openintake/apis/openintake-api.md) - [All operations](https://skmtc.dev/openintake/apis/openintake-api/llms.txt) - [OpenAPI document](https://skmtc.dev/openintake/apis/openintake-api/revisions/de90a8dcbc07?raw)