Documentação da API

Referência completa dos endpoints de integração — LideraAI

Visão Geral

A API de integração permite que sistemas externos (CRMs, landing pages, formulários) consultem e cadastrem dados 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

Autenticação

Inclua a chave de API em um dos headers abaixo em todas as requisições:

Authorization: Bearer sua_api_key

ou alternativamente

X-API-Key: sua_api_key

Endpoints disponíveis

POST/api/v1/votersCadastra um novo eleitor GET/api/v1/votersLista eleitores da campanha PUT/api/v1/voters/:voter_idAtualiza campos de um eleitor POST/api/v1/leadershipsAdiciona uma liderança à campanha GET/api/v1/leadershipsLista lideranças com dados do usuário PUT/api/v1/leaderships/:user_idAtualiza campos de uma liderança GET/api/v1/tags/votersLista tags de eleitores da campanha GET/api/v1/tags/leadersLista tags de líderes da campanha

Busca por Telefone — Normalização Automática

O parâmetro search nos endpoints GET detecta automaticamente quando a busca é por telefone (valor contém apenas dígitos e caracteres de formatação: +, -, (, ) e espaços). Nesses casos, a busca usa normalização automática: remove a máscara de ambos os lados, trata o código de país (+55) e compara apenas os dígitos.

Todos os formatos abaixo encontram o mesmo número ✓

11999998888(11) 9 9999-8888

+55 (11) 9 9999-888811999998888

(11) 9999-8888+55 11 9 9999-8888

99998888(11) 9 9999-8888

Como funciona

Detecta busca por telefone automaticamente (sem parâmetro extra)
Remove máscara de ambos os lados (banco e busca)
Ignora código de país +55 quando necessário
Busca parcial funciona pelos últimos dígitos (ex: últimos 8 dígitos do número)

POST/api/v1/voters

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

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.
`tag_ids`	string[]	Não	IDs das tags a associar ao eleitor no momento do cadastro. Use GET /api/v1/tags/voters para obter os IDs disponíveis.

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"
  },
  "tags_assigned": 2
}

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",
    "tag_ids": ["uuid-tag-saude", "uuid-tag-educacao"]
  }'

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). Apenas para POST.

500

Erro interno

Erro no servidor. Tente novamente em alguns instantes.

GET/api/v1/voters

Lista os eleitores da campanha com suporte a paginação e filtros.

Parâmetros de query

Parâmetro	Tipo	Padrão	Descrição
`page`	integer	1	Número da página.
`limit`	integer	100	Registros por página. Máximo: 500.
`search`	string	—	Busca por nome, telefone ou e-mail (parcial, case-insensitive).
`city`	string	—	Filtra por cidade (parcial).
`state`	string	—	Filtra por UF (exato, ex: SP).
`neighborhood`	string	—	Filtra por bairro (parcial).
`gender`	string	—	Filtra por gênero: masculino, feminino, outro ou nao_informado.
`tag_ids`	string	—	Filtra eleitores que possuem pelo menos uma das tags. Aceita um ID ou múltiplos separados por vírgula (ex: id1,id2).
`include_deactivated`	boolean	false	Se true, inclui eleitores desativados.

Campos retornados por eleitor

O campo custom_fields é um objeto JSON com os valores dos campos personalizados criados para a entidade voter nas configurações da campanha. O campo tags é um array com as tags atribuídas ao eleitor.

idcampaign_idcaptured_by_leader_idfull_namephone_numberemailcpfneighborhoodcitystatestreet_addressaddress_numberaddress_complementaddress_cepdate_of_birthgenderoccupationeducation_levelincome_rangeinterestssocial_instagramsocial_facebooksocial_othernotesdemandreferral_sourcemarketing_consentcustom_fieldsvoter_card_numbervoter_card_sectionvoter_card_sessionelectoral_place_iddeactivated_atcreated_atupdated_attags[] → { id, assigned_at, tag: { id, name, color } }

Resposta de sucesso HTTP 200

{
  "success": true,
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "full_name": "Maria da Silva",
      "phone_number": "11999998888",
      "email": "maria@email.com",
      "cpf": null,
      "city": "São Paulo",
      "state": "SP",
      "gender": "feminino",
      "captured_by_leader_id": "abc123...",
      "custom_fields": {
        "profissao": "Médica",
        "bairro_preferido": "Centro"
      },
      "tags": [
        {
          "id": "tag-assign-uuid",
          "assigned_at": "2026-05-13T12:00:00Z",
          "tag": { "id": "tag-uuid", "name": "Saúde", "color": "#3B82F6" }
        }
      ],
      "created_at": "2026-05-13T12:00:00Z",
      ...
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 342,
    "total_pages": 4
  }
}

Exemplos de uso

# Buscar primeira página
curl https://lideraai.app/api/v1/voters?page=1&limit=50 \
  -H "Authorization: Bearer sua_api_key"

# Buscar com filtros
curl "https://lideraai.app/api/v1/voters?city=São Paulo&state=SP&search=Maria" \
  -H "Authorization: Bearer sua_api_key"

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). Apenas para POST.

500

Erro interno

Erro no servidor. Tente novamente em alguns instantes.

PUT/api/v1/voters/:voter_id

Atualiza campos de um eleitor existente. Apenas os campos presentes no corpo são modificados — campos omitidos permanecem inalterados. Para tags, enviar tag_ids substitui todas as tags existentes.

Parâmetro de rota

:voter_id — UUID do eleitor a ser atualizado.

Campos do corpo (JSON)

Todos os campos são opcionais. Envie apenas os que deseja alterar.

Campo	Tipo	Descrição
`full_name`	string	Nome completo do eleitor.
`phone_number`	string	Telefone com DDD.
`email`	string	E-mail do eleitor.
`cpf`	string	CPF do eleitor.
`neighborhood`	string	Bairro.
`city`	string	Cidade.
`state`	string	UF (2 letras, ex: SP).
`street_address`	string	Logradouro.
`address_number`	string	Número do endereço.
`address_complement`	string	Complemento.
`address_cep`	string	CEP.
`date_of_birth`	string	Data de nascimento (YYYY-MM-DD).
`gender`	string	masculino, feminino, outro ou nao_informado.
`occupation`	string	Ocupação/profissão.
`education_level`	string	fundamental, medio, superior, pos_graduacao ou nao_informado.
`income_range`	string	Faixa de renda (texto livre).
`interests`	string[]	Lista de interesses (array de strings).
`social_instagram`	string	Usuário ou URL do Instagram.
`social_facebook`	string	Usuário ou URL do Facebook.
`social_other`	string	Outro perfil social.
`notes`	string	Observações.
`demand`	string	Demanda/pedido do eleitor.
`referral_source`	string	Origem do cadastro.
`marketing_consent`	boolean	Consentimento para comunicações.
`custom_fields`	object	Campos personalizados em JSON.
`tag_ids`	string[]	IDs das tags. Substitui todas as tags existentes. Array vazio remove todas as tags. Omitir preserva as tags atuais.

Resposta de sucesso HTTP 200

{
  "success": true,
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "full_name": "Maria da Silva",
    "phone_number": "11999998888",
    "email": "maria@email.com",
    "city": "São Paulo",
    "state": "SP",
    "custom_fields": { "profissao": "Médica" },
    "tags": [
      {
        "id": "assign-uuid",
        "assigned_at": "2026-06-16T10:00:00Z",
        "tag": { "id": "tag-uuid", "name": "Saúde", "color": "#3B82F6" }
      }
    ],
    "updated_at": "2026-06-16T10:00:00Z"
  }
}

Exemplos de uso

curl -X PUT https://lideraai.app/api/v1/voters/3fa85f64-5717 \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "city": "Campinas",
    "state": "SP",
    "notes": "Interesse em saúde pública",
    "tag_ids": ["uuid-tag-saude"]
  }'

Erros comuns

400

Requisição inválida

Nenhum campo válido fornecido ou valor de enum inválido.

401

Não autenticado

API key ausente ou inválida.

403

Acesso negado

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

404

Não encontrado

Nenhum eleitor com este voter_id foi encontrado nesta campanha.

500

Erro interno

Erro no servidor. Tente novamente em alguns instantes.

POST/api/v1/leaderships

Adiciona um usuário existente como liderança na campanha. O usuário deve ter uma conta ativa no LideraAI — identifique-o pelo user_id ou pelo email.

Campos do corpo (JSON)

É obrigatório informar user_id ou email. Os demais campos são opcionais.

Campo	Tipo	Obrigatório	Descrição
`user_id`	string	Sim*	UUID do usuário a ser adicionado como liderança. Use user_id ou email.
`email`	string	Sim*	E-mail do usuário (alternativa ao user_id). O usuário deve ter conta ativa no LideraAI.
`supervisor_id`	string	Não	UUID do supervisor desta liderança.
`self_estimated_votes`	integer	Não	Estimativa de votos declarada pelo líder.
`campaign_estimated_votes`	integer	Não	Estimativa de votos pela campanha.
`confirmed_votes`	integer	Não	Votos confirmados.
`operation_city`	string	Não	Cidade de atuação.
`operation_state`	string	Não	UF de atuação (ex: SP).
`operation_areas`	string[]	Não	Bairros ou zonas de atuação.
`custom_fields`	object	Não	Campos personalizados em JSON.
`social_media_links`	object	Não	Links de redes sociais.
`supporter_goal`	integer	Não	Meta de apoiadores.
`can_register_sub_leaders`	boolean	Não	Permite cadastrar sub-líderes.
`tag_ids`	string[]	Não	IDs das tags a associar à liderança no momento do cadastro.

Resposta de sucesso HTTP 201

{
  "success": true,
  "data": {
    "user_id": "abc123...",
    "supervisor_id": null,
    "campaign_id": "xyz789...",
    "confirmed_votes": 0,
    "operation_city": "São Paulo",
    "operation_state": "SP",
    "custom_fields": {},
    "created_at": "2026-06-16T10:00:00Z",
    "user": {
      "id": "abc123...",
      "full_name": "João Silva",
      "email": "joao@email.com"
    }
  },
  "tags_assigned": 1
}

Exemplos de uso

# Usando e-mail do usuário
curl -X POST https://lideraai.app/api/v1/leaderships \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "joao@email.com",
    "operation_city": "São Paulo",
    "operation_state": "SP",
    "supporter_goal": 200,
    "tag_ids": ["uuid-tag-coordenador"]
  }'

Erros comuns

400

Requisição inválida

Nem user_id nem email foram fornecidos.

401

Não autenticado

API key ausente ou inválida.

403

Acesso negado

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

404

Usuário não encontrado

Nenhum usuário com o e-mail ou user_id informado existe no LideraAI. O usuário precisa criar a conta antes.

409

Conflito

Este usuário já é uma liderança nesta campanha.

500

Erro interno

Erro no servidor. Tente novamente em alguns instantes.

GET/api/v1/leaderships

Lista as lideranças da campanha incluindo os dados completos do usuário associado a cada liderança.

Parâmetros de query

Parâmetro	Tipo	Padrão	Descrição
`page`	integer	1	Número da página.
`limit`	integer	100	Registros por página. Máximo: 500.
`search`	string	—	Busca por nome, e-mail ou telefone do usuário (parcial).
`city`	string	—	Filtra por cidade de atuação (parcial).
`state`	string	—	Filtra por estado de atuação (exato, ex: SP).
`tag_ids`	string	—	Filtra líderes que possuem pelo menos uma das tags. Aceita um ID ou múltiplos separados por vírgula (ex: id1,id2).
`include_deactivated`	boolean	false	Se true, inclui líderes com usuário desativado.

Campos retornados por liderança

Cada item retorna os campos da liderança mais um objeto user com os dados completos do usuário. O campo custom_fields é um objeto JSON com os valores dos campos personalizados criados para a entidade leadership. O campo tags é um array com as tags atribuídas ao líder.

Liderança

user_idsupervisor_idcampaign_idself_estimated_votescampaign_estimated_votesconfirmed_votespointscapture_link_slugoperation_location_typeoperation_location_nameoperation_location_detailsoperation_cityoperation_stateoperation_areascustom_fieldsdobradinha_id (deprecated)dobradinha_ids[]leader_category_idsocial_media_linkstotal_followerscan_register_sub_leaderssupporter_goalcreated_attags[] → { id, created_at, tag: { id, name, color, icon } }

user (objeto aninhado)

idfull_nameemailphone_numberprofile_picture_urlneighborhoodcitystaterolecustom_role_iddate_of_birthstreet_addressaddress_cepaddress_numberaddress_complementnotesdeactivated_atcpfprofessioncommission_percentagelast_loginvoter_card_numbervoting_location_idvoting_location_city_codeelectoral_sectioncreated_atupdated_at

Resposta de sucesso HTTP 200

{
  "success": true,
  "data": [
    {
      "user_id": "abc123...",
      "supervisor_id": null,
      "campaign_id": "xyz789...",
      "confirmed_votes": 120,
      "points": 850,
      "capture_link_slug": "joao-silva",
      "operation_city": "São Paulo",
      "operation_state": "SP",
      "custom_fields": {
        "cargo_partido": "Tesoureiro",
        "regiao": "Zona Norte"
      },
      "tags": [
        {
          "id": "assign-uuid",
          "created_at": "2026-01-20T08:00:00Z",
          "tag": { "id": "tag-uuid", "name": "Coordenador", "color": "#10B981", "icon": "star" }
        }
      ],
      "created_at": "2026-01-15T10:00:00Z",
      "user": {
        "id": "abc123...",
        "full_name": "João Silva",
        "email": "joao@email.com",
        "phone_number": "11988887777",
        "city": "São Paulo",
        "state": "SP",
        "role": "leader",
        "cpf": "123.456.789-00",
        "profession": "Advogado",
        "created_at": "2026-01-15T10:00:00Z",
        ...
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 47,
    "total_pages": 1
  }
}

Exemplos de uso

# Listar todas as lideranças
curl https://lideraai.app/api/v1/leaderships \
  -H "Authorization: Bearer sua_api_key"

# Buscar por nome com filtro de estado
curl "https://lideraai.app/api/v1/leaderships?search=João&state=SP" \
  -H "Authorization: Bearer sua_api_key"

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). Apenas para POST.

500

Erro interno

Erro no servidor. Tente novamente em alguns instantes.

PUT/api/v1/leaderships/:user_id

Atualiza campos de uma liderança existente. Apenas os campos presentes no corpo da requisição são modificados — campos omitidos permanecem inalterados.

Parâmetro de rota

:user_id — UUID do usuário/líder a ser atualizado.

Campos do corpo (JSON)

Todos os campos são opcionais. Envie apenas os que deseja alterar.

Campo	Tipo	Descrição
`supervisor_id`	string \| null	UUID do supervisor. null remove o vínculo.
`self_estimated_votes`	integer	Estimativa de votos declarada pelo próprio líder.
`campaign_estimated_votes`	integer	Estimativa de votos atribuída pela campanha a este líder.
`confirmed_votes`	integer	Número de votos confirmados.
`points`	integer	Pontuação no sistema de gamificação.
`capture_link_slug`	string	Slug único do link de captura do líder.
`operation_location_type`	string	Tipo de área de atuação (bairro, cidade, zona, etc.).
`operation_location_name`	string	Nome do local/área de atuação.
`operation_location_details`	string	Detalhes complementares sobre a área de atuação.
`operation_city`	string	Cidade de atuação.
`operation_state`	string	UF de atuação (ex: SP).
`operation_areas`	string[]	Lista de bairros ou zonas de atuação.
`custom_fields`	object	Campos personalizados em formato JSON.
`dobradinha_id`	string \| null	(Deprecated) UUID de uma dobradinha. Usar dobradinha_ids.
`dobradinha_ids`	string[]	IDs das dobradinhas. Substitui todas as associações existentes. Array vazio remove todas. Omitir preserva as atuais.
`leader_category_id`	string \| null	UUID da categoria do líder.
`social_media_links`	object	Links de redes sociais (ex: { "instagram": "...", "facebook": "..." }).
`total_followers`	integer	Total de seguidores nas redes sociais.
`can_register_sub_leaders`	boolean	Se o líder pode cadastrar sub-líderes.
`supporter_goal`	integer	Meta de apoiadores definida para o líder.
`tag_ids`	string[]	IDs das tags. Substitui todas as tags existentes. Array vazio remove todas as tags. Omitir preserva as tags atuais.

Resposta de sucesso HTTP 200

{
  "success": true,
  "data": {
    "user_id": "abc123...",
    "supervisor_id": null,
    "campaign_id": "xyz789...",
    "self_estimated_votes": 200,
    "campaign_estimated_votes": 180,
    "confirmed_votes": 150,
    "points": 850,
    "capture_link_slug": "joao-silva",
    "operation_city": "São Paulo",
    "operation_state": "SP",
    "operation_areas": ["Zona Norte", "Vila Maria"],
    "custom_fields": { "cargo_partido": "Tesoureiro" },
    "social_media_links": { "instagram": "joaosilva" },
    "total_followers": 1500,
    "can_register_sub_leaders": true,
    "supporter_goal": 250,
    "created_at": "2026-01-15T10:00:00Z"
  }
}

Exemplos de uso

curl -X PUT https://lideraai.app/api/v1/leaderships/abc123 \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmed_votes": 150,
    "campaign_estimated_votes": 180,
    "operation_city": "São Paulo",
    "operation_state": "SP"
  }'

Erros comuns

400

Requisição inválida

Nenhum campo válido para atualizar foi fornecido.

401

Não autenticado

API key ausente ou inválida.

403

Acesso negado

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

404

Não encontrado

Nenhuma liderança com este user_id foi encontrada nesta campanha.

500

Erro interno

Erro no servidor. Tente novamente em alguns instantes.

GET/api/v1/tags/voters

Lista todas as tags de eleitores configuradas na campanha. Use os IDs retornados no campo tag_ids ao cadastrar eleitores (POST /api/v1/voters) ou para filtrar pelo parâmetro tag_ids no GET de eleitores.

Parâmetros

Nenhum parâmetro de query. Retorna todas as tags da campanha autenticada.

Resposta de sucesso HTTP 200

{
  "success": true,
  "data": [
    { "id": "uuid-tag-1", "name": "Saúde", "color": "#3B82F6", "description": null },
    { "id": "uuid-tag-2", "name": "Educação", "color": "#10B981", "description": "Interesse em educação" }
  ]
}

Exemplos de uso

curl https://lideraai.app/api/v1/tags/voters \
  -H "Authorization: Bearer sua_api_key"

GET/api/v1/tags/leaders

Lista todas as tags de líderes ativas da campanha, ordenadas por order_index. Use os IDs retornados para filtrar o GET de lideranças pelo parâmetro tag_ids.

Parâmetros

Nenhum parâmetro de query. Retorna somente tags ativas (is_active = true) da campanha autenticada.

Resposta de sucesso HTTP 200

{
  "success": true,
  "data": [
    { "id": "uuid-tag-a", "name": "Coordenador", "color": "#10B981", "icon": "star" },
    { "id": "uuid-tag-b", "name": "Militante", "color": "#6366F1", "icon": "users" }
  ]
}

Exemplos de uso

curl https://lideraai.app/api/v1/tags/leaders \
  -H "Authorization: Bearer sua_api_key"

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.
Use paginação nos endpoints GET: o limite padrão é 100 registros, máximo 500 por requisição.
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.