Skip to main content

Endpoint

POST /v1/contacts
Escopo necessário: write:contacts

Corpo da requisição

CampoTipoObrigatórioDescrição
namestringSimNome completo. Máximo 200 caracteres
emailstringNãoEmail. Deve ser válido
phonestringNãoTelefone. Máximo 40 caracteres
instagram_usernamestringNãoUsername do Instagram (sem @)
messenger_psidstringNãoPSID do Facebook Messenger
company_idstringNãoID da empresa para vincular
assigned_tostringNãoID do membro responsável
tagsstring[]NãoLista de tags
sourcestringNãoOrigem do contato. Padrão: "api"
custom_fieldsobjectNãoCampos personalizados (chave → valor)

Detecção de duplicatas

Se phone ou email já existirem em outro contato da organização, a API retorna HTTP 409:
{
  "error": {
    "type": "conflict",
    "message": "Já existe um contato com este telefone ou email.",
    "code": "DUPLICATE_CONTACT",
    "existing_contact": {
      "id": "664f1a2b3c4d5e6f78901234",
      "name": "João Silva"
    }
  }
}

Exemplo de requisição

curl -X POST https://api.socialsell.ai/v1/contacts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ana Costa",
    "email": "ana@empresa.com.br",
    "phone": "+5521988888888",
    "tags": ["lead", "inbound"],
    "source": "site",
    "custom_fields": {
      "cargo": "Gerente de TI"
    }
  }'

Exemplo de resposta

{
  "data": {
    "id": "664f9z8y7x6w5v4u3t2s1r0q",
    "name": "Ana Costa",
    "email": "ana@empresa.com.br",
    "phone": "+5521988888888",
    "instagram_username": null,
    "whatsapp_jid": null,
    "messenger_psid": null,
    "messenger_name": null,
    "source": "site",
    "avatar_url": null,
    "assigned_to": null,
    "company": null,
    "tags": ["lead", "inbound"],
    "custom_fields": {
      "cargo": "Gerente de TI"
    },
    "funnel_stage": null,
    "notes_count": 0,
    "deals_count": 0,
    "last_message_at": null,
    "created_at": "2026-06-10T15:30:00.000Z",
    "updated_at": "2026-06-10T15:30:00.000Z"
  },
  "meta": {
    "request_id": "req_01jx8kz3m4n5p6q7r8s9t0u1v"
  }
}
A criação do contato dispara automaticamente o evento contact.created em webhooks configurados.

Erros

CódigoStatusDescrição
MISSING_REQUIRED_FIELD400Campo name ausente
INVALID_COMPANY_ID400company_id com formato inválido
DUPLICATE_CONTACT409Já existe contato com esse telefone ou email
DUPLICATE409Conflito de índice único no banco