> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talkover.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Subir lista de contatos

> Sobe um arquivo CSV como nova lista de contatos da campanha

# Subir lista de contatos

Sobe um arquivo CSV como nova lista de contatos da campanha — o mesmo que **Adicionar lista** no painel. O arquivo é validado na hora e importado em segundo plano; use o `file_data_id` retornado para acompanhar a importação em [Consultar progresso da importação](https://docs.talkover.ai/api-reference/endpoints/get-campaign-list-progress).

## Endpoint

```
POST /api/v1/campaigns/{campaign_id}/files
```

## Parâmetros de caminho

**campaign\_id** `string` *required*

UUID da campanha.

## Cabeçalhos da requisição

**Authorization** `string` *required*

Token Bearer. Formato: `Bearer talq_your_environment_token_here`

**Content-Type** `string` *required*

`multipart/form-data`

## Corpo da requisição

**file** `file` *required*

Arquivo CSV (`.csv` ou `.txt`). Até **20.000 linhas** e **25 MB**.

## Formato do arquivo

* O arquivo precisa de uma coluna **`to`** com os telefones. No painel, o mapeamento de colunas renomeia a sua coluna de telefone para `to`; pela API nada é renomeado, então envie o cabeçalho como `to`.
* Toda outra coluna vira variável do contato, com o cabeçalho exatamente como escrito: uma coluna `Nome` é `{Nome}` no prompt do agente.
* Uma coluna opcional `source` marca a origem de cada contato (padrão `CSV`). Uma coluna opcional `allow_duplicates` deixa a linha entrar mesmo com o número já pendente na campanha.
* Números na lista de não ligar da campanha, números já pendentes e números ainda em período de espera são pulados na importação.
* **Ambientes de cobrança** precisam de uma coluna de telefone (`to`, `phone` ou `phone_1`, `phone_2`…) e de uma coluna de documento (`document`, `cpf`, `cnpj`…).

## Exemplos

```bash theme={null}
curl -X POST "https://app.talkover.ai/api/v1/campaigns/campaign-uuid/files" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -F "file=@mailing-2026-11-04.csv"
```

## Resposta

`202 Accepted` — a lista foi guardada e a importação está na fila.

```json theme={null}
{
  "success": true,
  "data": {
    "file_data_id": "list-uuid",
    "status": "processing",
    "row_count": 18342,
    "warnings": []
  },
  "message": "File uploaded successfully. Processing in background."
}
```

`warnings` lista colunas com valores vazios (em branco, `-`, `N/A`…). Nunca bloqueiam o envio.

## Respostas de erro

### 422 — Arquivo inválido

O arquivo foi recusado e nada foi importado: sem coluna `to`, mais de 20.000 linhas, arquivo vazio, não é CSV ou acima de 25 MB.

```json theme={null}
{
  "success": false,
  "message": "CSV file must contain a 'to' column with phone numbers",
  "errors": ["CSV file must contain a 'to' column with phone numbers"]
}
```

### 404 — Campanha não encontrada

A campanha não existe ou pertence a outro ambiente.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.