---
title: "List Contacts"
method: POST
path: "/contacts/list"
tags: ["Contacts"]
---

# List Contacts

`POST /contacts/list`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/contacts/list`
- Auth: API key in header `PINNACLE-API-KEY`

List all contacts with optional filtering and pagination. Results are sorted by creation date, newest first.

## Request body

- ListContactsRequest
  - `pageIndex` integer
  - `pageSize` integer
  - `phoneNumber` string: Filter contacts by phone number (E.164 format).
  - `name` string: Filter contacts by name (partial match).
  - `tags` string[]: Filter contacts by tags.
  - `isArchived` boolean: Filter contacts by archived status.

## Response `200`

Returns paginated list of contacts.

- ListContactsResponse
  - `data` Contact[], required
    - `description` string: Additional information about the contact.
    - `email` string: Contact's email address, if available.
    - `id` string, required: Unique ID of the contact. This identifier is a string that always begins with the prefix `co_`, for example: `co_1234567890`.
    - `name` string: Full name of the contact, if available.
    - `phoneNumber` string, required: Contact's phone number in E.164 format.
    - `tags` string[]: List of tags associated with the contact.
  - `hasMore` boolean, required
  - `count` integer, required

## Other responses

- `400`: Validation failed. The payload has missing required fields and/or invalid types. <br> See https://zod.dev/error-formatting for more information.
- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `500`: An unexpected error occurred on Pinnacle's servers while processing your request. <br> If this error persists, please contact support with the request details.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)