Criar contacto

POST https://app.sendapp.ai/api/contacts

Cria (ou atualiza via upsert) um único contacto. Deve ter pelo menos um telefone OU um email. Contactos existentes com o mesmo telefone/email são unidos (etiquetas combinadas, metadata unida).

Respostas: 201 Created com o contacto criado — 403 se atingido o limite de contactos do plano — 422 se faltarem tanto o telefone como o email.

Podes escrever os campos personalizados já na criação com custom_fields, por nome, com as mesmas regras de Atualizar contacto: um nome desconhecido ou um valor inválido devolvem 422 e o contacto não é guardado. Se o contacto já existe, os valores enviados substituem os guardados e os valores vazios são ignorados. Os nomes dos campos encontras com GET /api/contact-fields.

Parâmetros

9 · 3 obrigatórios

apikey obrigatório

A sua API Key (o cabeçalho X-API-Key também funciona).

name opcional

Nome completo, até 255 caracteres.

first_name opcional

Nome próprio. Com first_name e/ou last_name o nome completo é composto a partir deles (têm prioridade sobre name).

last_name opcional

Sobrenome.

phone obrigatório

Formato internacional (ex. +393391234567). Obrigatório se faltar o email.

email obrigatório

Email válido. Obrigatório se faltar o telefone.

tags opcional

Array de strings ou string separada por vírgulas (ex. "vip,newsletter").

metadata opcional

Objeto JSON com campos personalizados.

custom_fields opcional

Objeto cuja chave é o NOME do campo personalizado, p. ex. {"Cidade": "Lisboa", "Newsletter": true}. Cada valor é verificado segundo o tipo do campo, como em Atualizar contacto.

Precisa de ajuda com a integração? info@sendapp.live

Pedido

curl -X POST 'https://app.sendapp.ai/api/contacts' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Mario Rossi",
    "phone": "+393391234567",
    "email": "mario@example.com",
    "tags": ["newsletter", "vip"],
    "metadata": { "source": "landing_page_a" },
    "custom_fields": { "City": "Milano" }
  }'

<?php
$ch = curl_init('https://app.sendapp.ai/api/contacts');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'name'     => 'Mario Rossi',
        'phone'    => '+393391234567',
        'email'    => 'mario@example.com',
        'tags'     => ['newsletter', 'vip'],
        'metadata' => ['source' => 'landing_page_a'],
        'custom_fields' => ['City' => 'Milano'],
    ]),
]);
echo curl_exec($ch);
curl_close($ch);

const res = await fetch('https://app.sendapp.ai/api/contacts', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Mario Rossi',
    phone: '+393391234567',
    email: 'mario@example.com',
    tags: ['newsletter', 'vip'],
    metadata: { source: 'landing_page_a' },
    custom_fields: { City: 'Milano' }
  })
});
console.log(await res.json());

Resposta

{
  "status": "success",
  "contact": {
    "id": 4022,
    "name": "Giulia Bianchi",
    "first_name": "Giulia",
    "last_name": "Bianchi",
    "phone": "393334455667",
    "email": "giulia.bianchi@example.com",
    "tags": [
      "lead"
    ],
    "metadata": { "source": "api", "created_via": "api", "custom_12": "Milano" },
    "created_at": "2026-07-13 10:00:00",
    "updated_at": "2026-07-13 10:00:00",
    "custom_fields": { "City": "Milano", "Newsletter": null }
  }
}

{
  "status": "error",
  "message": "Contact limit reached. Please upgrade your plan."
}