> For the complete documentation index, see [llms.txt](https://docs.geeknums.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.geeknums.io/api-de-idade-e-genero-do-botim.md).

# API de Idade e Gênero do Botim

Verifique registros no Botim e enriqueça números registrados com gênero e idade.

## Parâmetros do produto

| Parâmetro                  | Valor                     |
| -------------------------- | ------------------------- |
| Tipo de tarefa             | `botim_gender`            |
| Tipo de entrada            | Telefone no formato E.164 |
| Mínimo de entradas válidas | 500                       |

{% hint style="info" %}
`estimated_amount` é calculado com o preço da conta e é a referência de cobrança da tarefa.
{% endhint %}

## Formato de entrada

Envie um arquivo `.txt` ou `.csv` com um telefone por linha. Recomenda-se E.164.

```
+14155552671+442071838750
```

{% stepper %}
{% step %}

## Criar uma tarefa

`POST https://api.checknumber.ai/v1/tasks`

```bash
curl --location 'https://api.checknumber.ai/v1/tasks' \--header 'X-API-Key: YOUR_API_KEY' \--form 'file=@"./numbers.txt"' \--form 'task_type="botim_gender"'
```

A API retorna um ID de tarefa. Guarde-o para consultar o status.
{% endstep %}

{% step %}

## Consultar o status

`POST https://api.checknumber.ai/v1/gettasks`

```bash
curl --location 'https://api.checknumber.ai/v1/gettasks' \--header 'X-API-Key: YOUR_API_KEY' \--form 'task_id="d4g8o46p2jvh04o9uolg"'
```

Consulte até `status` ser `exported`. `pending` e `processing` ainda não estão concluídos.
{% endstep %}
{% endstepper %}

## Resposta do envio

```json
{  "task_id": "d4g8o46p2jvh04o9uolg",  "status": "pending",  "total": 500,  "estimated_amount": {    "amount": "0.350000",    "currency": "USD"  },  "message": "Task created successfully"}
```

## Resposta em processamento

```json
{  "task_id": "d4g8o46p2jvh04o9uolg",  "status": "processing",  "total": 500,  "success": 250,  "failure": 0}
```

## Resposta exportada

```json
{  "task_id": "d4g8o46p2jvh04o9uolg",  "status": "exported",  "total": 500,  "success": 500,  "failure": 0,  "result_url": "https://example-link-to-results.zip",  "actual_amount": {    "amount": "0.350000",    "currency": "USD"  }}
```

## Campos de resultado

| Campo               | Descrição                                                        | Exemplo                 |
| ------------------- | ---------------------------------------------------------------- | ----------------------- |
| `number` / `Number` | Telefone de entrada. CSV usa `number`; XLSX usa `Number`.        | +14155552671            |
| `activated`         | Indica se uma conta foi detectada para o número.                 | yes / no                |
| `gender`            | Gênero detectado para uma conta Botim registrada.                | Male / Female / Unknown |
| `age`               | Idade ou faixa etária detectada para uma conta Botim registrada. | 25-34                   |

{% hint style="info" %}
Linhas sem conta retornam `activated=no`; campos de perfil ficam vazios quando não há dados.
{% endhint %}

## Tratamento do arquivo

Baixe o pacote por `result_url` somente após a exportação e preserve os nomes das colunas.

## Campos da resposta

| Campo              | Descrição                                        |
| ------------------ | ------------------------------------------------ |
| `created_at`       | Data de criação.                                 |
| `updated_at`       | Última atualização.                              |
| `task_id`          | ID exclusivo da tarefa.                          |
| `status`           | `pending`, `processing`, `exported` ou `failed`. |
| `total`            | Total de entradas válidas.                       |
| `success`          | Valores processados com sucesso.                 |
| `failure`          | Valores com falha.                               |
| `result_url`       | URL de download após exportar.                   |
| `actual_amount`    | Valor final, quando disponível.                  |
| `estimated_amount` | Valor estimado na criação.                       |

## Códigos de status

| Status | Descrição                                                       |
| ------ | --------------------------------------------------------------- |
| `200`  | Solicitação bem-sucedida.                                       |
| `202`  | Tarefa criada e cobrança estimada aplicada.                     |
| `400`  | Arquivo inválido, tipo não suportado ou entradas insuficientes. |
| `401`  | API Key ausente ou inválida.                                    |
| `402`  | Saldo insuficiente.                                             |
| `404`  | Tarefa não encontrada.                                          |
| `413`  | Arquivo muito grande.                                           |
| `500`  | Erro interno; tente novamente mais tarde.                       |

## Notas operacionais

* A tarefa é assíncrona; consulte com o ID retornado.
* Somente números válidos e normalizados contam para o mínimo.
* Tarefas com falha são reembolsadas automaticamente conforme o faturamento.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.geeknums.io/api-de-idade-e-genero-do-botim.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.