Contatos

Listar contatos

Changed on Oct 12, 2026

Contatos da organização, no envelope { contacts, total, page, size, totalPages } (não segue o padrão { data, pagination }). Exige plano com contatos (403 PLAN_FEATURE_LOCKED). Permissão: ADMIN.

get/v1/contacts

Request

Base URL
https://api.ararahq.com
Auth
HTTP bearer
TypeScript
https://skmtc.dev/ararahq/apis/ararahq-api/docs/v1/contacts/get.ts
A function with typed inputs. Its response is checked against the schema.

Query parameters

qstring

Busca por nome, telefone ou email.

Estágio do contato. ALL (ou omitido) traz todos.

pageinteger

Página, começando em 0.

sizeinteger

Itens por página. Máximo 200.

Headers

X-Waba-Idstring uuid

Restringe o resultado a uma conta WhatsApp Business (WABA) da organização.

Response

Página de contatos

totalinteger required

pageinteger required

sizeinteger required

totalPagesinteger required

Example response

{
  "contacts": [
    {
      "id": "1f2e3d4c-5b6a-7890-abcd-ef1234567890",
      "name": "João Silva",
      "phone": "+5511999999999",
      "email": "joao@exemplo.com",
      "attributes": {
        "plano": "pro"
      },
      "tags": [
        "vip"
      ],
      "createdAt": "2026-09-01T14:30:00Z",
      "lifecycle": "ENGAGED",
      "source": "API",
      "outboundCount": 12,
      "inboundCount": 3,
      "firstSeenAt": "2026-09-01T14:30:00Z",
      "lastOutboundAt": "2026-09-14T10:00:00Z",
      "lastInboundAt": "2026-09-14T10:05:00Z",
      "lastMessageAt": "2026-09-14T10:05:00Z",
      "optOutAt": null,
      "lastTemplateName": "pedido_confirmado"
    }
  ]
}

Changes

Oct 12, 2026d576cd28afc0 Revision changes
- breaking
  the query request parameter lifecycle was restricted to a list of enum values
- info
  api tag Contatos added
- info
  api tag contacts removed
- info
  added the new enum value ALL to the query request parameter lifecycle
- info
  added the new enum value DORMANT to the query request parameter lifecycle
- info
  added the new enum value ENGAGED to the query request parameter lifecycle
- info
  added the new enum value NEW to the query request parameter lifecycle
- info
  added the new enum value OPTED_OUT to the query request parameter lifecycle
- info
  added the new enum value SILENT to the query request parameter lifecycle
- info
  added the non-success response with the status
Sep 15, 2026372d8c2e735d Revision changes
- breaking
  the response property became optional for the status
- breaking
  the response's property type changed from object to string for status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- warning
  removed the optional property / from the response with the status
- info
  added the new optional header request parameter X-Waba-Id
- info
  added the new optional query request parameter lifecycle
- info
  for the query request parameter size, the max was increased from 100.00 to 200.00
- info
  added the non-success response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status

Operation history (3 revisions)