Documentação da API

Referência do endpoint de integração de eleitores — LideraAI

Visão Geral

A API de integração permite que sistemas externos (CRMs, landing pages, formulários) cadastrem eleitores diretamente na sua campanha no LideraAI. Para habilitar, acesse Configurações → Integração API dentro da plataforma e gere uma chave de API.

Base URL

https://lideraai.app

Autenticação

Bearer token

Formato

JSON

POST/api/v1/voters

Cadastra um novo eleitor na campanha associada à chave de API fornecida.

Autenticação

Inclua a chave de API (gerada em Configurações → Integração API) em um dos headers abaixo:

Authorization: Bearer sua_api_key

ou alternativamente

X-API-Key: sua_api_key

Corpo da requisição (JSON)

Campo	Tipo	Obrigatório	Descrição
`full_name`	string	Sim	Nome completo do eleitor.
`phone_number`	string	Não	Telefone com DDD (ex: 11999998888). Obrigatório dependendo das configurações da campanha.
`email`	string	Não	E-mail do eleitor.
`cpf`	string	Não	CPF do eleitor (somente números ou formatado).
`neighborhood`	string	Não	Bairro.
`city`	string	Não	Cidade.
`state`	string	Não	UF (2 letras, ex: SP).
`street_address`	string	Não	Logradouro.
`address_number`	string	Não	Número do endereço.
`address_complement`	string	Não	Complemento.
`address_cep`	string	Não	CEP.
`date_of_birth`	string	Não	Data de nascimento no formato YYYY-MM-DD.
`gender`	string	Não	Gênero: masculino, feminino, outro ou nao_informado.
`occupation`	string	Não	Ocupação/profissão.
`education_level`	string	Não	Escolaridade: fundamental, medio, superior, pos_graduacao ou nao_informado.
`income_range`	string	Não	Faixa de renda (texto livre, ex: "1 a 3 salários mínimos").
`interests`	string[]	Não	Lista de interesses do eleitor (array de strings).
`social_instagram`	string	Não	Usuário ou URL do Instagram.
`social_facebook`	string	Não	Usuário ou URL do Facebook.
`social_other`	string	Não	Outro perfil social (URL ou texto livre).
`notes`	string	Não	Observações sobre o eleitor.
`demand`	string	Não	Demanda/pedido do eleitor.
`referral_source`	string	Não	Origem do cadastro (ex: landing-page, whatsapp, evento).
`marketing_consent`	boolean	Não	Consentimento para comunicações de marketing. Padrão: false.
`custom_fields`	object	Não	Campos personalizados adicionais em formato JSON.

Resposta de sucesso HTTP 201

{
  "success": true,
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "full_name": "Maria da Silva",
    "phone_number": "11999998888",
    "email": "maria@email.com",
    "cpf": null,
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "created_at": "2026-05-13T12:00:00Z"
  }
}

Erros comuns

400

Requisição inválida

Campo obrigatório ausente ou valor fora do conjunto permitido.

401

Não autenticado

API key ausente ou inválida.

403

Acesso negado

A integração via API está desabilitada para esta campanha.

409

Conflito

Já existe um eleitor com o mesmo CPF ou telefone nesta campanha (se duplicidade não permitida).

500

Erro interno

Erro no servidor. Tente novamente em alguns instantes.

Exemplos de uso

curl -X POST https://lideraai.app/api/v1/voters \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Maria da Silva",
    "phone_number": "11999998888",
    "email": "maria@email.com",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "referral_source": "landing-page"
  }'

Boas práticas

Nunca exponha a chave de API em código front-end público. Use sempre um servidor intermediário.
Trate os erros 409 (duplicidade) para evitar cadastros duplos de eleitores já registrados.
Valide e formate o número de telefone antes de enviar (preferencialmente com DDD, ex: 11999998888).
Rotacione a chave de API periodicamente em Configurações → Integração API.