Criar contato

Método

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

Conceituação

Este endpoint permite criar um novo contato manualmente. O contato será associado à sua instituição e poderá ser utilizado em envios de mensagens, envios em massa e segmentações.

O número de telefone deve ser único por instituição. Caso já exista um contato com o mesmo número, a API retornará um erro de duplicidade.

---

Atributos

Header

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

Body

Atributo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome do contato. Mínimo: 1 caractere. Máximo: 200 caracteres
phone	string	Sim	Número de telefone no formato internacional (ex: 5511999999999)
email	string	Não	Endereço de e-mail do contato
tags	string[]	Não	Array de tags para categorização
metadata	object	Não	Objeto com campos personalizados (chave-valor livre)

---

Request

cURL

curl -X POST "https://oapi.ogmma.com.br/v1/contacts" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Silva",
    "phone": "5511999990001",
    "email": "maria@email.com",
    "tags": ["vip", "cliente"],
    "metadata": {
      "empresa": "Acme Ltda",
      "cpf": "123.456.789-00",
      "plano": "premium",
      "dataAniversario": "1990-05-15"
    }
  }'

Node.js

const axios = require('axios');

const response = await axios.post(
  'https://oapi.ogmma.com.br/v1/contacts',
  {
    name: 'Maria Silva',
    phone: '5511999990001',
    email: 'maria@email.com',
    tags: ['vip', 'cliente'],
    metadata: {
      empresa: 'Acme Ltda',
      cpf: '123.456.789-00',
      plano: 'premium',
      dataAniversario: '1990-05-15'
    }
  },
  {
    headers: {
      'Authorization': 'Bearer {API_KEY}',
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.data);

Python

import requests

response = requests.post(
    'https://oapi.ogmma.com.br/v1/contacts',
    json={
        'name': 'Maria Silva',
        'phone': '5511999990001',
        'email': 'maria@email.com',
        'tags': ['vip', 'cliente'],
        'metadata': {
            'empresa': 'Acme Ltda',
            'cpf': '123.456.789-00',
            'plano': 'premium',
            'dataAniversario': '1990-05-15'
        }
    },
    headers={
        'Authorization': 'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
)

print(response.json())

---

Response

201 - Success

O contato foi criado com sucesso.

{
  "data": {
    "id": "6650b2c3d4e5f6a7890140",
    "name": "Maria Silva",
    "phone": "5511999990001",
    "email": "maria@email.com",
    "tags": ["vip", "cliente"],
    "metadata": {
      "empresa": "Acme Ltda",
      "cpf": "123.456.789-00",
      "plano": "premium",
      "dataAniversario": "1990-05-15"
    },
    "createdAt": "2025-06-10T15:00:00Z",
    "updatedAt": "2025-06-10T15:00:00Z"
  }
}

400 - Bad Request

Parâmetros inválidos ou número de telefone duplicado.

{
  "message": "Já existe um contato com o número '5511999990001' nesta instituição.",
  "code": "DUPLICATE_PHONE"
}

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"
}