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

# Get Contacts

> List your CRM contacts one page at a time, most recent conversation first, or look up one number.

> [!NOTE]
>
> Reads the contacts in your [CRM](https://docs.callkaro.ai/crm/introduction.md), one page at a time, or looks up a single number with its current attributes.

## Quick Example

```bash theme={null}
curl "https://api.callkaro.ai/contact/get?page=1&page_size=20" \
  -H "X-API-KEY: YOUR_API_KEY"
```

Look up one number:

```bash theme={null}
curl "https://api.callkaro.ai/contact/get?to_number=919876543210" \
  -H "X-API-KEY: YOUR_API_KEY"
```

Write the number without `+` in the URL. In a query string, `+` is read as a space.

## Use Cases

* **Syncing out**: copy your CRM contacts, and the attributes your agents collected, into your own database
* **Checking a lead**: see whether a number is already a contact, and what is saved on it, before you create or update it

## Pagination

| Parameter | Default | Notes |
| - | - | - |
| `page` | `1` | Starts at 1 |
| `page_size` | `20` | 1 to 100 |
| `to_number` | none | Returns only that contact, or an empty list |

Contacts come back in the order the CRM shows them: the most recent conversation first, then contacts that have never messaged, most recently updated first.

The response says how many pages there are:

```json theme={null}
"pagination": { "page": 1, "page_size": 20, "total": 57, "total_pages": 3 }
```

Keep asking for the next `page` until it reaches `total_pages`. A page past the end returns an empty `contacts` list.

> [!NOTE]
>
> New messages and edits move contacts up the list, so the pages can shift while you read them. When copying every contact, expect the odd contact to appear on two pages, and match on `to_number`.

## What each contact contains

| Field | Meaning |
| - | - |
| `to_number` | Phone number as stored: digits with country code, such as `919876543210` |
| `channels` | Channels the contact has been reached on, such as `whatsapp` |
| `attributes` | Each saved attribute and its value |
| `created_at`, `updated_at` | When the contact was added and last changed, in IST |
| `last_message_at` | When the last WhatsApp message was exchanged, in IST, or `null` |

## Errors worth handling

> **400 page or page\_size out of range**
>
> `page` must be 1 or more, and `page_size` from 1 to 100, both whole numbers.

> **401 Invalid API key**
>
> The `X-API-KEY` header is missing or does not belong to any account.

> **403 Account is inactive**
>
> The account the key belongs to has been deactivated. Contact support.


## OpenAPI

````yaml GET /contact/get
openapi: 3.1.0
info:
  title: CallKaro AI API
  description: Campaign and outbound call management API for CallKaro AI voice agents
  version: 1.0.0
  contact:
    name: CallKaro AI Support
    email: support@callkaro.ai
    url: https://callkaro.ai
servers:
  - url: https://api.callkaro.ai
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /contact/get:
    get:
      tags:
        - Endpoints
      summary: Get Contacts
      description: >-
        List your CRM contacts one page at a time, most recent conversation
        first, or look up one number.
      operationId: getContacts
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number, starting at 1
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Contacts per page, at most 100
        - name: to_number
          in: query
          required: false
          schema:
            type: string
          example: '919876543210'
          description: >-
            Return only this number. Send it without +, which a URL reads as a
            space.
      responses:
        '200':
          description: One page of contacts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactListResponse'
              example:
                status: done
                contacts:
                  - to_number: '919876543210'
                    channels: []
                    attributes:
                      first_name: Rahul
                      city: Pune
                    created_at: '2026-10-27 11:42:05.118'
                    updated_at: '2026-10-27 11:42:05.118'
                    last_message_at: null
                pagination:
                  page: 1
                  page_size: 20
                  total: 1
                  total_pages: 1
        '400':
          description: page or page_size out of range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: error
                message: page_size must be a whole number from 1 to 100
        '401':
          description: Missing or unknown X-API-KEY
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: error
                message: Invalid API key
        '403':
          description: The account this key belongs to is inactive
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: error
                message: Account is inactive
components:
  schemas:
    ContactListResponse:
      type: object
      properties:
        status:
          type: string
          example: done
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        pagination:
          type: object
          properties:
            page:
              type: integer
              example: 1
            page_size:
              type: integer
              example: 20
            total:
              type: integer
              description: Contacts matching the request across all pages
              example: 57
            total_pages:
              type: integer
              example: 3
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: error
        message:
          type: string
          description: Error description
          example: 'Missing required field: to_number'
    Contact:
      type: object
      properties:
        to_number:
          type: string
          description: 'Phone number as stored: digits only, with country code'
          example: '919876543210'
        channels:
          type: array
          items:
            type: string
          description: Channels this contact has been reached on
          example:
            - whatsapp
        attributes:
          type: object
          additionalProperties: true
          description: Attribute name to value
          example:
            first_name: Rahul
            city: Pune
        created_at:
          type: string
          description: IST, YYYY-MM-DD HH:mm:ss.SSS
          example: '2026-10-27 11:42:05.118'
        updated_at:
          type: string
          description: IST, YYYY-MM-DD HH:mm:ss.SSS
          example: '2026-10-27 11:42:05.118'
        last_message_at:
          type: string
          nullable: true
          description: IST time of the last WhatsApp message, or null
          example: null
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key from https://callkaro.ai/dashboard/api-key

````

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