# Etiquetar contatos e preencher campos

> Ache ou crie a etiqueta, ponha e tire do contato, preencha e limpe campos personalizados e mude o valor de um campo do bot, tudo pela API.

Endereço: https://docs.nextags.com.br/guias/etiquetas-e-campos/
Tipo: Guia

Atualizado em: 26/10/2026

Etiquetas e campos guardam o que o seu sistema sabe do contato: quem comprou, de que cidade é, qual plano escolheu. Neste guia, você acha (ou cria) a etiqueta, põe e tira do contato, preenche e limpa um campo personalizado e muda o valor de um campo do bot, que vale para a conta toda.

**Antes de começar**

- A chave de API na variável de ambiente `NEXTAGS_API_KEY`. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/).
- O ID do contato. Veja [Encontrar um contato pelo e-mail ou telefone](https://docs.nextags.com.br/guias/buscar-contato-por-campo/).
- O campo personalizado criado na conta (neste guia, `cidade`, do tipo Texto). Veja [Criar campos personalizados](https://help.nextags.com.br/tutoriais/fluxos/campos-personalizados/).
- Para o último passo: um campo do bot e o ID dele (neste guia, `3101`). Veja [Campos do bot](https://help.nextags.com.br/tutoriais/fluxos/campos-do-bot/).

## Passo a passo

### Passo 1: Ache a etiqueta pelo nome

Use [Buscar etiqueta pelo nome](https://docs.nextags.com.br/referencia/etiquetas/buscar-etiqueta-pelo-nome/), com o nome no caminho. Nome com espaço ou acento vai codificado para URL (`Cliente%20VIP`).

**Buscar etiqueta pelo nome**

```bash
curl "https://app.nextagsai.com.br/api/accounts/tags/name/cliente-vip" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/tags/name/cliente-vip', {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/accounts/tags/name/cliente-vip",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/accounts/tags/name/cliente-vip');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

```json
{"id": 2001, "name": "cliente-vip"}
```

O contrato não diz o que volta quando o nome não existe. Se a resposta não trouxer um `id`, crie a etiqueta no passo 2. Para ver todas, use [Listar etiquetas](https://docs.nextags.com.br/referencia/etiquetas/listar-etiquetas/).

### Passo 2: Crie a etiqueta, se ela não existir

Use [Criar etiqueta](https://docs.nextags.com.br/referencia/etiquetas/criar-etiqueta/). Esta chamada recebe formulário, com o nome em `name`:

**Criar etiqueta**

```bash
curl -X POST "https://app.nextagsai.com.br/api/accounts/tags" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  --data-urlencode 'name=cliente-vip'
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/tags', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
  body: new URLSearchParams({
    name: 'cliente-vip',
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/accounts/tags",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    data={
        "name": "cliente-vip",
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/accounts/tags');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
    CURLOPT_POSTFIELDS => http_build_query([
        'name' => 'cliente-vip',
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

A resposta traz o ID da etiqueta nova:

```json
{"id": 2001}
```

Guarde o ID. Crie só depois de procurar: o contrato não diz se a API recusa um nome repetido.

### Passo 3: Ponha a etiqueta no contato

Use [Adicionar etiqueta ao contato](https://docs.nextags.com.br/referencia/etiquetas/adicionar-etiqueta-ao-contato/), com o ID do contato e o da etiqueta no caminho. A chamada não tem corpo.

**Adicionar etiqueta ao contato**

```bash
curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/tags/2001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/tags/2001', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts/123456789/tags/2001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/tags/2001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

A resposta é `{"success": true}`.

### Passo 4: Tire a etiqueta do contato

Use [Remover etiqueta do contato](https://docs.nextags.com.br/referencia/etiquetas/remover-etiqueta-do-contato/), no mesmo endereço, com `DELETE`:

**Remover etiqueta do contato**

```bash
curl -X DELETE "https://app.nextagsai.com.br/api/contacts/123456789/tags/2001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/tags/2001', {
  method: 'DELETE',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.delete(
    "https://app.nextagsai.com.br/api/contacts/123456789/tags/2001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/tags/2001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

A resposta é `{"success": true}`. Apagar a etiqueta da conta inteira é outra chamada, [Apagar etiqueta](https://docs.nextags.com.br/referencia/etiquetas/apagar-etiqueta/): use com cuidado.

### Passo 5: Ache o campo pelo nome

Use [Buscar campo pelo nome](https://docs.nextags.com.br/referencia/campos-personalizados/buscar-campo-pelo-nome/). A resposta traz o ID e o tipo do campo:

**Buscar campo pelo nome**

```bash
curl "https://app.nextagsai.com.br/api/accounts/custom_fields/name/cidade" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/custom_fields/name/cidade', {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/accounts/custom_fields/name/cidade",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/accounts/custom_fields/name/cidade');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

```json
{"id": 3001, "name": "cidade", "type": 0, "description": "Cidade do contato"}
```

O `type` diz o formato do valor: `0` texto, `1` número, `2` data, `3` data e hora, `4` sim/não. Veja a tabela completa em [Campos personalizados, campos do bot e variáveis](https://docs.nextags.com.br/comecar/campos-e-variaveis/).

### Passo 6: Preencha o campo do contato

Use [Preencher campo do contato](https://docs.nextags.com.br/referencia/campos-personalizados/preencher-campo-do-contato/). Esta chamada recebe formulário, com o valor em `value`:

**Preencher campo do contato**

```bash
curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  --data-urlencode 'value=São Paulo'
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
  body: new URLSearchParams({
    value: 'São Paulo',
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    data={
        "value": "São Paulo",
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
    CURLOPT_POSTFIELDS => http_build_query([
        'value' => 'São Paulo',
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

A resposta é `{"success": true}`. O valor segue o tipo do campo:

| Tipo do campo | Exemplo de `value` |
|---|---|
| Texto, Texto longo | `São Paulo` |
| Número | `42` |
| Data | `1794279600` (Unix em segundos: 10/11/2026, 0h em Brasília) |
| Data e hora | `1794331800` (10/11/2026, 14h30 em Brasília) |
| Verdadeiro/Falso | `1` ou `0` |

### Passo 7: Limpe o campo do contato

Use [Limpar campo do contato](https://docs.nextags.com.br/referencia/campos-personalizados/limpar-campo-do-contato/), no mesmo endereço, com `DELETE`:

**Limpar campo do contato**

```bash
curl -X DELETE "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001', {
  method: 'DELETE',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.delete(
    "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

A resposta é `{"success": true}`.

### Passo 8: Mude o valor de um campo do bot

O campo do bot tem um valor só, que vale para a conta toda, como um link de promoção usado em vários fluxos. Use [Preencher campo do bot](https://docs.nextags.com.br/referencia/campos-do-bot/preencher-campo-do-bot/), também com formulário e o valor em `value`:

**Preencher campo do bot**

```bash
curl -X POST "https://app.nextagsai.com.br/api/accounts/bot_fields/3101" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  --data-urlencode 'value=https://seusistema.exemplo.com.br/promocao-de-novembro'
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/bot_fields/3101', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
  body: new URLSearchParams({
    value: 'https://seusistema.exemplo.com.br/promocao-de-novembro',
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/accounts/bot_fields/3101",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    data={
        "value": "https://seusistema.exemplo.com.br/promocao-de-novembro",
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/accounts/bot_fields/3101');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
    CURLOPT_POSTFIELDS => http_build_query([
        'value' => 'https://seusistema.exemplo.com.br/promocao-de-novembro',
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

A resposta é `{"success": true}`. Para ler o valor, use [Consultar campo do bot](https://docs.nextags.com.br/referencia/campos-do-bot/consultar-campo-do-bot/) (`GET` no mesmo endereço); para limpar, [Limpar campo do bot](https://docs.nextags.com.br/referencia/campos-do-bot/limpar-campo-do-bot/) (`DELETE`).

## Pronto: como conferir

Consulte o campo do contato:

**Consultar campo do contato**

```bash
curl "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001', {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

```json
{"id": 3001, "name": "cidade", "type": 0, "value": "São Paulo"}
```

- Para todas as etiquetas do contato, use [Listar etiquetas do contato](https://docs.nextags.com.br/referencia/etiquetas/listar-etiquetas-do-contato/); para todos os campos, [Listar campos do contato](https://docs.nextags.com.br/referencia/campos-personalizados/listar-campos-do-contato/).
- Na NexTags, o painel do contato, na **Caixa de Entrada**, mostra as etiquetas e os campos. Veja [Etiquetas e campos personalizados na conversa](https://help.nextags.com.br/tutoriais/caixa-de-entrada/etiquetas-e-campos-na-conversa/).

> **Pelo nome, sem buscar o ID:**
> Para pôr etiquetas e preencher campos pelo nome, numa chamada só, use as ações `add_tag`, `remove_tag`, `set_field_value` e `unset_field_value` em [Enviar conteúdo](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/). Veja [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/).

## Se não funcionou

### 401 com "No valid API key provided."

A chave não chegou ou não vale. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/).

### O campo ficou vazio ou com outro valor

O valor não combina com o tipo do campo, ou foi enviado como JSON. Mande formulário com `value`, data em Unix timestamp em segundos e sim/não como `1` ou `0`.

### A data aparece um dia antes

O painel mostra a data no fuso de quem está vendo. Mande a meia-noite no horário de Brasília (3h em UTC), não a meia-noite em UTC.

### A busca pelo nome não acha a etiqueta ou o campo

O nome precisa ser igual ao da conta, com maiúsculas, acentos e espaços, e codificado na URL. Confira em [Listar etiquetas](https://docs.nextags.com.br/referencia/etiquetas/listar-etiquetas/) ou [Listar campos personalizados](https://docs.nextags.com.br/referencia/campos-personalizados/listar-campos-personalizados/).

### 400 ou 404 com um ID

O ID do contato, da etiqueta ou do campo está errado ou é de outra conta. Veja [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/).

### Faça com a IA

Cole este pedido no ChatGPT ou no Claude:

```text
Leia https://docs.nextags.com.br/guias/etiquetas-e-campos.md e https://docs.nextags.com.br/comecar/campos-e-variaveis.md.

Quando [o evento no seu sistema, por exemplo: o cliente muda de plano], quero pôr a etiqueta [nome] e preencher os campos [nomes e tipos] do contato na NexTags. Escreva, em [linguagem], o código que acha os IDs pelo nome uma vez, guarda numa configuração e depois atualiza o contato pelos IDs, com o valor de cada campo no formato do tipo dele. A chave vem da variável de ambiente NEXTAGS_API_KEY.
```