# List contacts

> Your contacts, the most recently texted first.

`GET /v1/contacts`

Your contacts, the most recently texted first. `q` finds people by name, company, phone number or email, and a few digits of a number work. Filter by `tag`, or by `stopped` for the stop list.

Needs a key with the `contacts:read` scope. [Keys and scopes](https://getdogbot.com/docs/concepts/api-keys)

## Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string | No | Find people by name, company, phone number or email. Part of one works, and each word can match a different one, so `Dana Oak` finds Dana at Oak Realty. Up to 100 characters |
| `tag` | string | No | Only people with this tag. Up to 50 characters |
| `stopped` | string | No | `true` for only people on your stop list, `false` for only people who aren’t. One of `true`, `false` |
| `limit` | integer | No | How many to return, 1 to 100. Default 25. 1 to 100. Default `25` |
| `cursor` | string | No | The `next_cursor` of the page before. Leave it out for the first page. Up to 200 characters |

## Example

```bash
curl "https://getdogbot.com/api/v1/contacts" \
  -H "Authorization: Bearer $DOGBOT_API_KEY"
```

```ts
import DogBot from '@getdogbot/sdk';

const client = new DogBot({ apiKey: process.env.DOGBOT_API_KEY });

const page = await client.contacts.list();
console.log(page.data);
```

```python
import os
from dogbot import DogBot

client = DogBot(api_key=os.environ["DOGBOT_API_KEY"])

page = client.contacts.list()
print(page.data)
```

## Response

`200`: A page of contacts.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "list" | Yes |   |
| `data` | array of Contact | Yes |   |
| `data[].id` | string | Yes | A ct_ id. Starts with `ct_` |
| `data[].object` | "contact" | Yes |   |
| `data[].handle` | string | Yes | A phone number in E.164 (`+15555550123`) or an email address an Apple ID uses (iMessage only). |
| `data[].kind` | string | Yes | `phone` or `email`. One of `phone`, `email` |
| `data[].first_name` | string or null | Yes |   |
| `data[].last_name` | string or null | Yes |   |
| `data[].company` | string or null | Yes |   |
| `data[].state` | string or null | Yes | The two-letter code of the US state they live in, or DC or PR, when you know it. Texting hours follow it, and without it they follow the area code. One of `AL`, `AK`, `AZ`, `AR`, `CA`, `CO`, `CT`, `DE`, `FL`, `GA`, `HI`, `ID`, `IL`, `IN`, `IA`, `KS`, `KY`, `LA`, `ME`, `MD`, `MA`, `MI`, `MN`, `MS`, `MO`, `MT`, `NE`, `NV`, `NH`, `NJ`, `NM`, `NY`, `NC`, `ND`, `OH`, `OK`, `OR`, `PA`, `RI`, `SC`, `SD`, `TN`, `TX`, `UT`, `VT`, `VA`, `WA`, `WV`, `WI`, `WY`, `DC`, `PR` |
| `data[].tags` | array of strings | Yes | The contact’s tags. |
| `data[].custom_fields` | map of string | Yes | Your own fields, for templates. |
| `data[].stopped` | boolean | Yes | True when the person is on your stop list. Texts to them are canceled. |
| `data[].stopped_at` | timestamp or null | Yes | When they were put on the stop list. |
| `data[].stop_source` | string or null | Yes | How: `reply` (they texted a stop word), `dashboard`, `api`, `import` or `admin`. One of `reply`, `dashboard`, `api`, `import`, `admin` |
| `data[].last_service` | string or null | Yes | The service of the newest text with them. One of `imessage`, `sms` |
| `data[].first_message_at` | timestamp or null | Yes | The first text either way. Null for somebody you have never texted with, who counts as a new person. |
| `data[].last_message_at` | timestamp or null | Yes | The newest text either way. |
| `data[].created_via` | string | Yes | What first added them. One of `message`, `inbound`, `import`, `api`, `dashboard`, `widget`, `hook`, `mcp`, `assistant`, `follow_up_boss`, `facebook` |
| `data[].created_at` | timestamp | Yes | When the contact was added. |
| `has_more` | boolean | Yes | Whether another page follows. |
| `next_cursor` | string or null | Yes | Send as `cursor` for the next page; null on the last. |

The answer, `200`:

```json
{
  "object": "list",
  "data": [
    {
      "id": "ct_1Hq2LxW9cVbN3mKpRtYs0a",
      "object": "contact",
      "handle": "+15555550123",
      "kind": "phone",
      "first_name": "Maria",
      "last_name": "Alvarez",
      "company": null,
      "state": "FL",
      "tags": [
        "buyer"
      ],
      "custom_fields": {
        "showing": "412 Oak St"
      },
      "stopped": false,
      "stopped_at": null,
      "stop_source": null,
      "last_service": "imessage",
      "first_message_at": "2026-11-02T15:20:00.000Z",
      "last_message_at": "2026-11-13T19:41:00.000Z",
      "created_via": "message",
      "created_at": "2026-11-02T15:20:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Errors

Every refusal has the same envelope and a page of its own. These are the ones this operation can give.

| Code                                                    | Status | What it means                                                                                                                                    |
| ------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`unauthorized`](https://getdogbot.com/docs/errors/unauthorized)             | 401    | The request carried no key, or a key DogBot doesn’t know: mistyped, revoked, or a test key sent to the live API.                                 |
| [`insufficient_scope`](https://getdogbot.com/docs/errors/insufficient_scope) | 403    | The key doesn’t carry the scope the endpoint needs. Each endpoint’s reference names its scope.                                                   |
| [`rate_limited`](https://getdogbot.com/docs/errors/rate_limited)             | 429    | Too many requests. A key may make 120 requests a minute. The `RateLimit` header says how many are left, and `Retry-After` how long to wait.      |
| [`internal`](https://getdogbot.com/docs/errors/internal)                     | 500    | Something went wrong on DogBot’s side. It was reported. Send the request again; with an Idempotency-Key that is always safe.                     |
| [`invalid_request`](https://getdogbot.com/docs/errors/invalid_request)       | 400    | Something in the request doesn’t fit: a missing or malformed field, a bad id, or a combination the endpoint refuses. `details` names each field. |

## Try it
