> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
last_verified: 2026-05-13
title: "Get contacts"
description: "Retrieve your contacts list from Protocol. You can optionally filter and paginate the results."
endpoint: "/v1/contacts"
method: "GET"
---


**Endpoint**: `GET /v1/contacts`
**Auth**: `Authorization: Bearer <api_key>` (required)
**Query parameters**: see "Optional query parameters" below for filter and pagination keys
**Error envelope**: 4xx/5xx return `{"error": {"code": string, "message": string}}`


<ApiEndpoint
  method="GET"
  endpoint="/v1/contacts"
  description="This endpoint allows you to retrieve your contacts list from Protocol. You can optionally filter and paginate the results."
>
    <section>
      ## Optional query parameters

      <ApiAttribute
        name="page"
        type="integer"
        description="The page number for pagination. Defaults to 1."
        required={false}
      />

      <ApiAttribute
        name="per_page"
        type="integer"
        description="Number of contacts per page. Defaults to 20, maximum is 100."
        required={false}
      />

      <ApiAttribute
        name="username"
        type="string"
        description="Filter contacts by username."
        required={false}
      />
    </section>

    <section>
      ## Request example

      <MultiLanguageCodeBlock
        languages={["javascript", "bash"]}
        value={[
          {
            language: 'javascript',
            code: `fetch('https://api.protocol.chat/v1/contacts', {
  headers: {
    'Authorization': 'Bearer {token}'
  }
})`
          },
          {
            language: 'bash',
            code: `curl https://api.protocol.chat/v1/contacts \\
  -H "Authorization: Bearer {token}"`
          }
        ]}
      />

      ```json {{ title: 'Response' }}
      {
        "data": [
          {
            "id": "WAz8eIbvDR60rouK",
            "username": "johndoe",
            "phone_number": "+1 (555) 123-4567",
            "avatar_url": "https://assets.protocol.chat/avatars/johndoe.jpg",
            "display_name": "John Doe",
            "created_at": 692233200
          },
          {
            "id": "hSIhXBhNe8X1d8Et"
            // ... more contacts
          }
        ],
        "pagination": {
          "total": 35,
          "per_page": 20,
          "current_page": 1,
          "total_pages": 2
        }
      }
      ```
    </section>
</ApiEndpoint>