# Criar contato

> Cria um contato e, na mesma chamada, roda ações nele: etiquetar, preencher campos e enviar um fluxo.

Endereço: https://docs.nextags.com.br/referencia/contatos/criar-contato/
Tipo: Endpoint

```http
POST https://app.nextagsai.com.br/api/contacts
X-ACCESS-TOKEN: <sua chave de API>
```

Cria um contato e, na mesma chamada, roda ações nele: etiquetar, preencher campos e enviar um fluxo. O telefone vai completo, com o código do país e o DDD, só com números, como `5511988776655`: veja [O formato certo do telefone](https://help.nextags.com.br/tutoriais/contatos/formato-do-telefone/). Para não criar o mesmo contato duas vezes, procure antes pelo telefone ou pelo e-mail em [Buscar contato por campo personalizado](https://docs.nextags.com.br/referencia/contatos/buscar-contato-por-campo-personalizado/). Veja [Criar ou atualizar um contato](https://docs.nextags.com.br/guias/criar-ou-atualizar-contato/).

> Se o contato nunca mandou mensagem para a conta, a janela de 24 horas do WhatsApp está fechada: o fluxo da ação `send_flow` precisa começar com um Modelo de Mensagem aprovado. Veja [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/).

Autenticação: Mande a chave de API da conta no cabeçalho `X-ACCESS-TOKEN` de cada chamada. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/).

## Corpo da requisição (JSON)

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `phone` | string | sim | O telefone com o código do país (DDI) e o DDD, só com números. |
| `email` | string | não | O e-mail do contato. |
| `first_name` | string | não | O nome. |
| `last_name` | string | não | O sobrenome. |
| `gender` | string | não | O gênero: `male` (masculino), `female` (feminino) ou `unknown` (desconhecido). Valores: `male`, `female`, `unknown`. |
| `actions` | array de objeto Ação | não | Ações para rodar no contato, na ordem da lista: `add_tag`, `set_field_value`, `send_flow` e as outras de [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/). |
| `actions[].action` | string | sim | Valores: `add_tag`, `remove_tag`, `set_field_value`, `unset_field_value`, `send_flow`, `transfer_conversation_to`, `assign_conversation`, `unassign_conversation`. |
| `actions[].tag_name` | string | não | O nome da etiqueta (add_tag, remove_tag). |
| `actions[].field_name` | string | não | O nome do campo (set_field_value, unset_field_value). |
| `actions[].value` | string | não | O valor do campo (set_field_value) ou human/bot (transfer_conversation_to). |
| `actions[].flow_id` | integer ou string | não | O ID do fluxo (send_flow). |
| `actions[].admin_id` | integer ou string | não | O ID do administrador (assign_conversation). |

```json
{
  "phone": "5511988776655",
  "email": "ana@exemplo.com.br",
  "first_name": "Ana",
  "last_name": "Souza",
  "gender": "female",
  "actions": [
    {
      "action": "add_tag",
      "tag_name": "cliente-vip"
    },
    {
      "action": "set_field_value",
      "field_name": "cidade",
      "value": "São Paulo"
    },
    {
      "action": "send_flow",
      "flow_id": 1000001
    }
  ]
}
```

## Exemplo

```bash
curl -X POST "https://app.nextagsai.com.br/api/contacts" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511988776655",
    "email": "ana@exemplo.com.br",
    "first_name": "Ana",
    "last_name": "Souza",
    "gender": "female",
    "actions": [
      {
        "action": "add_tag",
        "tag_name": "cliente-vip"
      },
      {
        "action": "set_field_value",
        "field_name": "cidade",
        "value": "São Paulo"
      },
      {
        "action": "send_flow",
        "flow_id": 1000001
      }
    ]
  }'
```

Os exemplos em JavaScript, Python e PHP estão na página e no contrato (`x-codeSamples` em https://docs.nextags.com.br/openapi.json).

## Respostas

### 200 Sucesso

Deu certo: o contato foi criado.

### 401 Chave inválida

A chave de API não veio no cabeçalho ou não vale (foi excluída ou está incompleta). Veja [Autenticação](https://docs.nextags.com.br/comecar/autenticacao/).

```json
{
  "error": {
    "code": 401,
    "message": "No valid API key provided."
  }
}
```