Listar contatos

Método

GET https://oapi.ogmma.com.br/v1/contacts

Conceituação

Este endpoint retorna uma lista paginada de contatos da sua instituição. Você pode buscar por nome ou telefone e filtrar por tags.

A busca por search realiza uma pesquisa parcial (like) nos campos de nome e telefone, permitindo encontrar contatos mesmo com informações incompletas.

---

Atributos

Header

Atributo	Tipo	Obrigatório	Descrição
Authorization	string	Sim	Bearer {API_KEY} - Chave de autenticação

Query Parameters

Atributo	Tipo	Obrigatório	Descrição
search	string	Não	Busca por nome ou telefone (pesquisa parcial)
tags	string	Não	Filtrar por tags (separadas por vírgula, ex: vip,cliente)
page	number	Não	Número da página. Padrão: 1
limit	number	Não	Quantidade de itens por página. Padrão: 20. Máximo: 100

---

Request

cURL

curl -X GET "https://oapi.ogmma.com.br/v1/contacts?search=Maria&tags=vip&page=1&limit=20" \
  -H "Authorization: Bearer {API_KEY}"

Node.js

const axios = require('axios');

const response = await axios.get(
  'https://oapi.ogmma.com.br/v1/contacts',
  {
    params: {
      search: 'Maria',
      tags: 'vip',
      page: 1,
      limit: 20
    },
    headers: {
      'Authorization': 'Bearer {API_KEY}'
    }
  }
);

console.log(response.data);

Python

import requests

response = requests.get(
    'https://oapi.ogmma.com.br/v1/contacts',
    params={
        'search': 'Maria',
        'tags': 'vip',
        'page': 1,
        'limit': 20
    },
    headers={
        'Authorization': 'Bearer {API_KEY}'
    }
)

print(response.json())

---

Response

200 - Success

Retorna a lista paginada de contatos.

{
  "data": [
    {
      "id": "6650b2c3d4e5f6a7890124",
      "name": "Maria Silva",
      "phone": "5511999990001",
      "email": "maria@email.com",
      "tags": ["vip", "recorrente"],
      "createdAt": "2025-05-01T10:00:00Z",
      "updatedAt": "2025-06-10T14:30:00Z"
    },
    {
      "id": "6650b2c3d4e5f6a7890128",
      "name": "Carlos Souza",
      "phone": "5511999990002",
      "email": null,
      "tags": ["novo"],
      "createdAt": "2025-06-10T14:25:00Z",
      "updatedAt": "2025-06-10T14:25:00Z"
    },
    {
      "id": "6650b2c3d4e5f6a7890132",
      "name": "Ana Oliveira",
      "phone": "5511999990003",
      "email": "ana@empresa.com",
      "tags": [],
      "createdAt": "2025-06-08T09:15:00Z",
      "updatedAt": "2025-06-09T16:45:00Z"
    }
  ],
  "meta": {
    "total": 3,
    "page": 1,
    "limit": 20
  }
}

401 - Unauthorized

Chave de API inválida ou ausente.

{
  "message": "Chave de API inválida ou expirada.",
  "code": "UNAUTHORIZED"
}

429 - Too Many Requests

Limite de requisições excedido.

{
  "message": "Limite de requisições excedido. Tente novamente em alguns segundos.",
  "code": "RATE_LIMIT_EXCEEDED"
}