Sign in

v1

latestOpenAPI 3.0.02026-07-2612645160.3 KB
Contact

Get contacts by time filters

Retrieve contacts filtered by activity (last message within N days), creation time, or update time. Works across all channels (WhatsApp, Instagram, etc.). At least one of days, created_after, or updated_after is required. For incremental sync, poll with updated_after set to the latest updated_at you have stored: the response includes both created_at and updated_at so you can tell new contacts (created_at > your cursor) apart from updated ones. Results are ordered ascending by updated_at (or created_at) when those filters are used, so you can page forward with limit/offset and advance your cursor safely. Optionally filter by custom field values.

get/api/public/contacts

Query parameters

daysnumber
Example:30

Filter contacts whose last message was within this many days (1-365)

created_afterstring date-time
Example:2024-01-15T10:00:00.000Z

Return only contacts created strictly after this ISO 8601 timestamp. Use for syncing newly created contacts.

updated_afterstring date-time
Example:2024-01-15T10:00:00.000Z

Return only contacts updated strictly after this ISO 8601 timestamp. Use as a sync cursor to pull both new and modified contacts since the last poll.

limitnumber
Example:100

Maximum number of contacts to return (1-1000)

offsetnumber

Number of contacts to skip, for pagination

stage_idstring uuid
Example:123e4567-e89b-12d3-a456-426614174000

Stage ID to filter contacts

pipeline_idstring uuid
Example:123e4567-e89b-12d3-a456-426614174000

Pipeline ID to filter contacts by their active ticket stage

custom_field_keystring
Example:status

The key of the custom field to filter by. Must be provided together with custom_field_value.

custom_field_valuestring
Example:Active

The value to match for the custom field. Must be provided together with custom_field_key.

entity_type'ticket' | 'customer'

Specify "ticket" or "customer" to filter only by custom fields of that entity type. Only applies when custom_field_key and custom_field_value are provided.

with_utm_eventsboolean
Example:true

Set to true to include the per-contact utm_events array (marketing attribution). Off by default — the key is omitted entirely unless requested, since it costs an extra lookup. Opt in only if you consume UTM attribution.

Headers

x-api-keystring required

API key needed to authorize the request

Response

Contacts retrieved successfully.

idstring
namestring
phonestring
emailstring
platformstring
last_message_atstring
chat_statusstring
created_atstring
updated_atstring
client_idstring
ai_customer_idstring nullable
default_stage_idstring nullable
blockedboolean
is_chat_readboolean

Example response

[
  {
    "id": "df980fc8-b6db-4820-bf22-2969482d106d",
    "name": "John Doe",
    "phone": "+56912345678",
    "email": "john@example.com",
    "platform": "whatsapp",
    "last_message_at": "2024-09-30T10:00:00.000Z",
    "chat_status": "ATTENDED",
    "created_at": "2024-01-15T10:00:00.000Z",
    "updated_at": "2024-01-16T09:30:00.000Z",
    "client_id": "123e4567-e89b-12d3-a456-426614174000",
    "ai_customer_id": "123e4567-e89b-12d3-a456-426614174000",
    "default_stage_id": "123e4567-e89b-12d3-a456-426614174000",
    "is_chat_read": true,
    "active_ticket_v2": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "current_stage_id": "123e4567-e89b-12d3-a456-426614174000"
    },
    "utm_events": [
      {
        "created_at": "2024-01-15T10:00:00.000Z",
        "integration_type": "facebook",
        "referrer_url": "https://example.com/landing"
      }
    ]
  }
]