# API Listas de Contatos

As Listas de Contatos permitem gerenciar grupos de contatos para uso em campanhas. Você pode criar listas via importação de dados, consultar, atualizar, exportar e excluir listas existentes.

authorization: Pode ser obtido através da plataforma no link: App SmartTalks.ai

# Headers Obrigatórios

Header	Tipo	Obrigatório	Descrição
`authorization`	`Authorization Bearer Token`	✔️	A chave da sua API
`accept`	`application/json`	✔️

# Listar todas as listas

Para consultar as listas disponíveis na sua conta, faça uma requisição POST informando os filtros e opções de paginação desejados:

  POST https://voyager.smarttalks.ai/v1/lists

# Body

Parâmetro	Tipo	Descrição
`query`	`object`	Filtros MongoDB (ex: `{ "name": "Minha Lista" }`)
`options.skip`	`number`	Número de registros a pular (paginação)
`options.limit`	`number`	Número máximo de registros a retornar

curl -X POST https://voyager.smarttalks.ai/v1/lists \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'Authorization: "{{authorization}}"' \
  --data '{
    "query": {},
    "options": {
      "skip": 0,
      "limit": 10
    }
  }'

Exemplo de retorno:

{
  "count": 2,
  "items": [
    {
      "_id": "6943042e3a61bb2fbef9e2b6",
      "id": 81,
      "name": "HBC 12.05",
      "total": 9,
      "type": "csv",
      "status": true,
      "columns": ["Name", "Reserva", "Whatsapp", "Checkin", "Checkout"],
      "createdAt": "2026-05-12T21:15:36.259Z",
      "updatedAt": "2026-05-12T21:15:36.288Z"
    },
    {
      "_id": "6943042e3a61bb2fbef9e2b7",
      "id": 80,
      "name": "Demo Lista",
      "total": 150,
      "type": "csv",
      "status": true,
      "columns": ["Nome", "Telefone", "Email"],
      "createdAt": "2025-11-14T12:17:00.000Z",
      "updatedAt": "2025-11-14T12:17:00.000Z"
    }
  ]
}

# Buscar uma lista pelo _id

Para buscar uma lista específica pelo seu _id, faça uma requisição GET:

  GET https://voyager.smarttalks.ai/v1/lists/[ _id ]

Parâmetro	Tipo	Obrigatório	Descrição
`_id`	`ObjectID`	✔️	Identificador único da lista

curl -X GET https://voyager.smarttalks.ai/v1/lists/6943042e3a61bb2fbef9e2b6 \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'Authorization: "{{authorization}}"'

Exemplo de retorno:

{
  "_id": "6943042e3a61bb2fbef9e2b6",
  "id": 81,
  "name": "HBC 12.05",
  "total": 9,
  "type": "csv",
  "status": true,
  "columns": ["Name", "Reserva", "Whatsapp", "Checkin", "Checkout"],
  "data": [
    {
      "Name": "ANA CAROLINA",
      "Reserva": "35452564",
      "Whatsapp": "5511989645023",
      "Checkin": "12/05/2026",
      "Checkout": "17/05/2026"
    },
    {
      "Name": "DAIANA BARBOSA",
      "Reserva": "35458895",
      "Whatsapp": "5513988225426",
      "Checkin": "12/05/2026",
      "Checkout": "15/05/2026"
    }
  ],
  "denominations": [
    {
      "columnName": "Name",
      "crmLabel": "Name",
      "fieldId": "653186781185caae03fc3af2",
      "fieldType": 13
    },
    {
      "columnName": "Whatsapp",
      "crmLabel": "WhatsApp",
      "fieldId": "653186781185caae03fc3af4",
      "fieldType": 34
    }
  ],
  "createdAt": "2026-05-12T21:15:36.259Z",
  "updatedAt": "2026-05-12T21:15:36.288Z"
}

# Criar uma lista

Para criar uma nova lista de contatos, faça uma requisição PUT com os dados dos contatos:

  PUT https://voyager.smarttalks.ai/v1/lists

# Body — `payload`

Parâmetro	Tipo	Obrigatório	Descrição
`payload.name`	`string`	✔️	Nome da lista
`payload.data`	`object[]`	✔️	Array de objetos representando cada contato
`payload.denominations`	`object[]`		Mapeamento das colunas para campos do CRM
`payload.units`	`string[]`		IDs das unidades que terão acesso à lista
`payload.type`	`string`		Tipo da lista: `"csv"` (padrão) ou `"api"`

# Estrutura de `denominations`

Campo	Tipo	Descrição
`columnName`	`string`	Nome da coluna no `data`
`crmLabel`	`string`	Rótulo do campo no CRM
`fieldId`	`ObjectID`	ID do campo CRM correspondente
`fieldType`	`number`	Tipo do campo CRM (`34` = WhatsApp, `13` = Nome)

curl -X PUT https://voyager.smarttalks.ai/v1/lists \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'Authorization: "{{authorization}}"' \
  --data '{
    "payload": {
      "name": "Campanha Junho 2026",
      "data": [
        {
          "Nome": "Ana Carolina",
          "Whatsapp": "5511989645023",
          "Cidade": "São Paulo"
        },
        {
          "Nome": "Daiana Barbosa",
          "Whatsapp": "5513988225426",
          "Cidade": "Santos"
        }
      ],
      "denominations": [
        {
          "columnName": "Nome",
          "crmLabel": "Name",
          "fieldId": "653186781185caae03fc3af2",
          "fieldType": 13
        },
        {
          "columnName": "Whatsapp",
          "crmLabel": "WhatsApp",
          "fieldId": "653186781185caae03fc3af4",
          "fieldType": 34
        }
      ],
      "units": [],
      "type": "csv"
    }
  }'

Exemplo de retorno:

{
  "_id": "6943042e3a61bb2fbef9e299",
  "id": 82,
  "name": "Campanha Junho 2026",
  "total": 2,
  "type": "csv",
  "status": true,
  "columns": ["Nome", "Whatsapp", "Cidade"],
  "data": [
    { "Nome": "Ana Carolina", "Whatsapp": "5511989645023", "Cidade": "São Paulo" }
  ],
  "denominations": [
    {
      "columnName": "Nome",
      "crmLabel": "Name",
      "fieldId": "653186781185caae03fc3af2",
      "fieldType": 13
    },
    {
      "columnName": "Whatsapp",
      "crmLabel": "WhatsApp",
      "fieldId": "653186781185caae03fc3af4",
      "fieldType": 34
    }
  ],
  "units": [],
  "createdAt": "2026-06-01T10:00:00.000Z",
  "updatedAt": "2026-06-01T10:00:00.000Z"
}

# Exportar uma lista

Para exportar os contatos de uma lista em arquivo, faça uma requisição GET informando o formato desejado. O arquivo será retornado diretamente no corpo da resposta.

  GET https://voyager.smarttalks.ai/v1/lists/[ _id ]/export?format=[ csv | xlsx ]

Parâmetro	Tipo	Obrigatório	Descrição
`_id`	`ObjectID`	✔️	Identificador único da lista
`format`	`string`		Formato de exportação: `csv` (padrão) ou `xlsx`

O retorno é o arquivo binário com o header Content-Disposition: attachment.

# Exportar como CSV
curl -X GET "https://voyager.smarttalks.ai/v1/lists/6943042e3a61bb2fbef9e2b6/export?format=csv" \
  -H 'Authorization: "{{authorization}}"' \
  --output "lista.csv"

# Exportar como Excel (XLSX)
curl -X GET "https://voyager.smarttalks.ai/v1/lists/6943042e3a61bb2fbef9e2b6/export?format=xlsx" \
  -H 'Authorization: "{{authorization}}"' \
  --output "lista.xlsx"

Exemplo de retorno (CSV):

Name,Reserva,Whatsapp,Checkin,Checkout
ANA CAROLINA,35452564,5511989645023,12/05/2026,17/05/2026
DAIANA BARBOSA,35458895,5513988225426,12/05/2026,15/05/2026
DANDARA LUNNYK,35418411,5513996816814,12/05/2026,15/05/2026

# Excluir uma lista

Para excluir uma lista, faça uma requisição DELETE informando o _id:

  DELETE https://voyager.smarttalks.ai/v1/lists/[ _id ]

Parâmetro	Tipo	Obrigatório	Descrição
`_id`	`ObjectID`	✔️	Identificador único da lista

A exclusão é lógica — a lista é marcada como inativa e não retorna mais nas consultas.

curl -X DELETE https://voyager.smarttalks.ai/v1/lists/6943042e3a61bb2fbef9e2b6 \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'Authorization: "{{authorization}}"'

Exemplo de retorno:

{
  "acknowledged": true,
  "modifiedCount": 1,
  "upsertedId": null,
  "upsertedCount": 0,
  "matchedCount": 1
}