> ## Documentation Index
> Fetch the complete documentation index at: https://docs.answeringagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts

> Search your customers and read their recent conversations.

A contact is one of your customers. The dashboard's **Contacts** page shows the same records.

## Search contacts

```
GET /contacts
```

[Try it in the playground](/api-reference/contacts/search-contacts).

Returns contacts, newest first.

<ParamField query="query" type="string">
  Matches the name, phone number, email, company, or notes. Up to 100 characters.
</ParamField>

<ParamField query="limit" type="integer" default="10">
  Results per page, 1 to 50.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number. Use `next_page` from the previous response.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://answeringagent.com/api/v1/contacts?query=ruiz" \
    -H "X-API-KEY: $ANSWERING_AGENT_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({ query: 'ruiz' });
  const res = await fetch(`https://answeringagent.com/api/v1/contacts?${params}`, {
    headers: { 'X-API-KEY': process.env.ANSWERING_AGENT_API_KEY },
  });
  if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
  const { contacts, next_page } = await res.json();
  ```
</CodeGroup>

```json theme={null}
{
  "total_matching": 1,
  "page": 1,
  "next_page": null,
  "contacts": [
    {
      "id": 77310,
      "url": "https://answeringagent.com/dashboard/contacts/77310",
      "name": "Dana Ruiz",
      "phone": "+15125550118",
      "email": "dana.ruiz@example.com",
      "company": null,
      "stage": null,
      "tags": ["unlimited-member"],
      "notes": "Prefers text over calls.",
      "blocked": false,
      "phone_call_count": 4,
      "first_contact_at": "2025-03-14T16:02:10.000Z",
      "last_call_at": "2026-10-05T14:21:07.000Z"
    }
  ]
}
```

### Contact fields

<ResponseField name="id" type="integer">
  The contact ID.
</ResponseField>

<ResponseField name="url" type="string">
  The contact in the dashboard.
</ResponseField>

<ResponseField name="name" type="string | null">
  The customer's name, when known.
</ResponseField>

<ResponseField name="phone" type="string | null">
  Phone number.
</ResponseField>

<ResponseField name="email" type="string | null">
  Email address.
</ResponseField>

<ResponseField name="company" type="string | null">
  Company name.
</ResponseField>

<ResponseField name="stage" type="string | null">
  The contact's stage, when your team sets one.
</ResponseField>

<ResponseField name="tags" type="string[]">
  Tags on the contact. Empty when there are none.
</ResponseField>

<ResponseField name="notes" type="string | null">
  Notes on the contact. Up to 2,000 characters.
</ResponseField>

<ResponseField name="blocked" type="boolean">
  `true` when the contact is blocked.
</ResponseField>

<ResponseField name="phone_call_count" type="integer">
  How many phone calls with this contact the key can see, inbound and outbound. Texts, chats, and emails that started on their own are not counted. Spam and unanswered calls are not counted.
</ResponseField>

<ResponseField name="first_contact_at" type="string | null">
  When the contact record was created, as an ISO 8601 UTC timestamp. Despite the name, it is not read from the contact's conversations.
</ResponseField>

<ResponseField name="last_call_at" type="string | null">
  When the contact's latest phone call or website chat handoff started. Texts and emails do not change it. `null` when that conversation was spam or unanswered, or is on a phone line the key cannot see.
</ResponseField>

## Get a contact

```
GET /contacts/{contact_id}
```

[Try it in the playground](/api-reference/contacts/get-a-contact).

Returns one contact with every [contact field](#contact-fields), plus their 10 most recent conversations.

<ParamField path="contact_id" type="integer" required>
  The contact ID.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://answeringagent.com/api/v1/contacts/77310 \
    -H "X-API-KEY: $ANSWERING_AGENT_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch('https://answeringagent.com/api/v1/contacts/77310', {
    headers: { 'X-API-KEY': process.env.ANSWERING_AGENT_API_KEY },
  });
  if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
  const contact = await res.json();
  ```
</CodeGroup>

```json theme={null}
{
  "id": 77310,
  "url": "https://answeringagent.com/dashboard/contacts/77310",
  "name": "Dana Ruiz",
  "phone": "+15125550118",
  "email": "dana.ruiz@example.com",
  "company": null,
  "stage": null,
  "tags": ["unlimited-member"],
  "notes": "Prefers text over calls.",
  "blocked": false,
  "phone_call_count": 4,
  "first_contact_at": "2025-03-14T16:02:10.000Z",
  "last_call_at": "2026-10-05T14:21:07.000Z",
  "recent_conversations": [
    {
      "id": 184532,
      "url": "https://answeringagent.com/dashboard/conversations/184532",
      "channel": "phone",
      "channels": ["phone", "text"],
      "started_at": "2026-10-05T14:21:07.000Z",
      "last_activity_at": "2026-10-05T14:26:40.000Z",
      "title": "Cancel monthly membership",
      "summary": "Dana called to cancel her Unlimited plan before the next charge on the 12th.",
      "category": "cancellation",
      "customer": { "name": "Dana Ruiz", "phone": "+15125550118", "email": "dana.ruiz@example.com" },
      "phone_line": { "id": 2181, "name": "Westside Wash", "phone_number": "+15125550142" },
      "duration_seconds": 214,
      "has_recording": true
    }
  ]
}
```

<ResponseField name="recent_conversations" type="object[]">
  Up to 10 conversations, most recent activity first, in the [conversation format](/api/conversations#conversation-fields).
</ResponseField>

A contact that does not exist, or that the key's owner cannot see, returns `404`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.