Contacts API Documentation

This document describes how to use the /api/v1/contacts endpoints for fetching contacts and contact tags for your company.

Base URL

GET /api/v1/contacts

Authentication

All requests require authentication:

API Key Pass your company API key as a Bearer token in the

Authorization: Bearer <API_KEY>

Your API key is scoped to your company — only data belonging to your company is returned.

Endpoints

GET /api/v1/contacts

Fetch a paginated list of contacts for the authenticated company.

Headers:

Header	Required	Description
`Authorization`	Yes	`Bearer`

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-based).
`limit`	integer	`10`	Number of results per page.
`search`	string	—	Search term matched against `first_name`, `last_name`, `email`, `phone_number`, `phone_number_lid`, and tag names.

Response:

200 OK: Paginated list of contacts.

401 Unauthorized: Invalid or missing API key.

405 Method Not Allowed: Unsupported HTTP method.

500 Internal Server Error: Server error.

Response Example:

{
  "data": [
    {
      "id": "1234567890",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone_number": "1234567890",
      "phone_number_lid": null,
      "profile_picture": "https://cdn.example.com/avatars/jane.jpg",
      "created_at": "2025-08-01T10:00:00.000Z",
      "updated_at": "2025-09-15T08:30:00.000Z",
      "tags": [
        {
          "id": "42",
          "name": "VIP",
          "color": "#1156d6"
        },
        {
          "id": "57",
          "name": "Lead",
          "color": "#e63946"
        }
      ]
    }
  ],
  "currentPage": 1,
  "totalPages": 12,
  "totalRecords": 115
}

GET /api/v1/contacts/tags

Fetch a paginated list of contact tags for the authenticated company. Each tag includes a count of how many contacts are assigned to it.

Headers:

Header	Required	Description
`Authorization`	Yes	`Bearer`

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-based).
`limit`	integer	`10`	Number of results per page.
`search`	string	—	Search term matched against the tag `name` field.

Response:

200 OK: Paginated list of contact tags.

401 Unauthorized: Invalid or missing API key.

405 Method Not Allowed: Unsupported HTTP method.

500 Internal Server Error: Server error.

Response Example:

{
  "data": [
    {
      "id": "42",
      "name": "VIP",
      "color": "#1156d6",
      "created_at": "2025-06-10T09:00:00.000Z",
      "_count": {
        "contact_tag": 38
      }
    },
    {
      "id": "57",
      "name": "Lead",
      "color": "#e63946",
      "created_at": "2025-07-22T14:15:00.000Z",
      "_count": {
        "contact_tag": 12
      }
    }
  ],
  "currentPage": 1,
  "totalPages": 3,
  "totalRecords": 25
}

Pagination

Both endpoints return the same pagination envelope:

Field	Type	Description
`currentPage`	integer	The current page returned.
`totalPages`	integer	Total number of pages available.
`totalRecords`	integer	Total number of matching records across all pages.
`data`	array	The records for the current page.

Error Codes

Code	Meaning
`401`	Missing or invalid API key / session token.
`405`	HTTP method not supported (only `GET` is allowed).
`500`	Internal server error.