Pular para o conteúdo
MModari

Contatos

Criar, listar, buscar e atualizar contatos (leads) através da API do Modari.

Um contato representa um lead. É a entidade vinculada a negociações, conversas e qualificações.

POST /api/contacts
Authorization: Bearer elv_...
Content-Type: application/json

Criar um contato#

POST /api/contacts
Campo Tipo Obrigatório Descrição
name string sim Nome do contato.
phones array sim Telefones do contato. Pelo menos um é obrigatório.
title string não Título/cargo do contato.
notes string não Anotações livres.
origin string não Origem do contato. Ver valores possíveis.
emails array não Lista de e-mails, cada item com email.
birthday data não Data de nascimento, ISO 8601.
facebook, linkedin string não Perfis sociais.
referralSource string não Fonte da indicação.
country, state, city string não Localização do contato.
utmMedium, utmCampaign string não UTMs da campanha de origem.
customFields array não Campos personalizados, cada item com key, label, type, value. A key precisa existir já configurada para a empresa.

Objeto phones[]#

Campo Tipo Obrigatório Descrição
phone string sim Telefone no formato 55DDDNNNNNNNN.
phoneType string não Tipo do telefone (ex.: mobile).

Origem do contato#

not_tracked, meta, google, manual, organic, door, architect_referral, customer_referral, returning_customer, seller_contact.

Exemplo#

{
  "name": "Ana Souza",
  "phones": [{ "phone": "5511999999999", "phoneType": "mobile" }],
  "emails": [{ "email": "ana@exemplo.com.br" }],
  "origin": "google",
  "city": "Florianópolis",
  "state": "SC",
  "utmCampaign": "black-friday-2025"
}

Resposta — 201#

{
  "status": 201,
  "createdRegistry": {
    "_id": "677a8121849dfc001b863851",
    "name": "Ana Souza",
    "discardContact": false,
    "origin": "google",
    "emails": [{ "email": "ana@exemplo.com.br" }],
    "phones": [{ "phone": "5511999999999", "phoneType": "mobile" }],
    "qualifications": [],
    "hasActiveFollowUp": false,
    "customFields": [],
    "createdAt": "2025-07-18T14:15:13.321Z",
    "updatedAt": "2025-07-18T14:15:13.321Z"
  }
}

Listar contatos#

GET /api/contacts

Suporta paginação e busca padrão da API (ver Paginação), além dos filtros abaixo:

Filtro (query string) Tipo Descrição
phone string Busca parcial por telefone. "54999" encontra "5499958466".
origin string Filtra por origem do contato.
createdAt data Retorna contatos criados a partir desta data (ISO 8601).

Resposta — 200#

{
  "status": 200,
  "registersList": [
    { "_id": "677a8121849dfc001b863851", "name": "Ana Souza", "...": "..." }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 1,
    "totalItems": 1,
    "itemsPerPage": 10,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

Buscar contato por ID#

GET /api/contacts/:contactId

Retorna 404 se o contato não existir para a empresa dona da API key.

{
  "status": 200,
  "register": { "_id": "677a8121849dfc001b863851", "name": "Ana Souza", "...": "..." }
}

Atualizar contato#

PUT /api/contacts/:contactId

Mesmos campos da criação, todos opcionais — envie apenas o que deseja alterar. Campos omitidos permanecem inalterados.

{
  "notes": "Retornou contato via WhatsApp, aguardando orçamento.",
  "phones": [{ "phone": "5511999999999", "phoneType": "mobile" }]
}

Resposta — 200#

{
  "status": 200,
  "updatedRegistry": { "_id": "677a8121849dfc001b863851", "name": "Ana Souza", "...": "..." }
}

Paginação e filtros comuns#

Os endpoints de listagem da API aceitam:

Parâmetro Tipo Padrão Descrição
page number 1 Página atual.
limit number 10 Itens por página (máx. 1000).
sortBy string — Campo de ordenação.
sortOrder string desc asc ou desc.
search string — Busca textual.
ids array — Filtra por uma lista de IDs específicos.
createdAtStart, createdAtEnd data — Intervalo de criação, ISO 8601.

Exemplo com curl#

curl -X POST "https://moveis-api.smarktech.app.br/api/contacts" \
  -H "Authorization: Bearer $MODARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ana Souza",
    "phones": [{ "phone": "5511999999999" }]
  }'

Erros comuns#

Situação Resposta
phones vazio ou ausente 400 — pelo menos um telefone é obrigatório
contactId que não existe para a sua empresa 404
API key sem permissão para o endpoint 401

Atualizado em 05 de out. de 2026 · modari