API de vidas do Pump Saúde | Pump para desenvolvedores Pular para o conteúdo

Para empresas · API v1

API de vidas do Pump Saúde

Inclua e desative colaboradores direto do sistema de RH da sua empresa. A Pump libera o acesso e acompanha cada vida até ela poder usar o serviço. Avisar o colaborador fica com a sua empresa.

Atualizado em 10/11/2026

O que é

Cada colaborador com acesso ao Pump Saúde é uma vida. Com a API, o seu sistema avisa a Pump quando alguém entra ou sai do time, sem planilha e sem e-mail.

  • Entrou no time: inclua a vida. A Pump libera o acesso e a sua empresa avisa a pessoa que ela já pode usar o Pump Saúde pelo app.
  • Saiu do time: desative a vida. A Pump encerra o acesso em seguida.
  • Quer conferir: consulte o status de uma vida ou a lista inteira.

Como pedir a chave

Por enquanto, a chave é entregue pelo nosso time comercial. Fale com a gente informando o CNPJ da empresa e o e-mail de quem vai fazer a integração.

A chave aparece uma única vez, quando é criada. A Pump guarda só uma impressão dela e não consegue recuperá-la: se perder, peça uma nova e revogue a antiga.

Guarde a chave como uma senha: só no servidor, nunca no navegador, no app ou no código versionado. Sua empresa pode ter mais de uma chave ativa, pra trocar sem parar a integração.

Falar com o comercial

Autenticação

Mande a chave no header X-Api-Key em toda requisição. Só aceitamos HTTPS.

Endereço base
https://api.pump.com.br
Header
X-Api-Key
Formato
application/json
Exemplo
curl "https://api.pump.com.br/partners/v1/beneficiaries" \
  -H "X-Api-Key: $PUMP_API_KEY"

Dados da vida

Só cpf, name e birthDate são obrigatórios. Pra usar uma consulta, a pessoa precisa de e-mail, telefone e endereço: o que faltar, o app pede no primeiro acesso. Mandar já na inclusão deixa esse começo mais rápido.

  • cpf texto Obrigatório

    CPF, com ou sem máscara. Ex.: 123.456.789-09 ou 12345678909.

  • name texto Obrigatório

    Nome completo, até 200 caracteres.

  • birthDate data Obrigatório

    Data de nascimento no formato AAAA-MM-DD.

  • email texto Opcional

    E-mail da pessoa, até 200 caracteres.

  • phone texto Opcional

    Celular com DDD, sem +55. Pode vir com máscara: a Pump devolve só os números.

  • address objeto Opcional

    Endereço residencial. Se mandar, street, number, neighborhood, city, state (sigla com 2 letras) e zipCode (8 dígitos, com ou sem máscara) são obrigatórios. complement é opcional.

Na resposta

Toda resposta com uma vida traz os campos enviados e mais estes. Campo sem valor não aparece na resposta: trate a ausência como nulo.

  • id texto

    Identificador da vida na Pump. Guarde junto do colaborador: é ele que vai na URL.

  • cpf texto

    CPF só com números.

  • status texto

    Em que pé está o acesso. Veja Status das vidas.

  • error objeto

    Aparece quando a última tentativa da Pump falhou: code, message (em português) e occurredAt.

  • activatedAt data e hora

    Quando o acesso foi liberado pela última vez.

  • deactivatedAt data e hora

    Quando o acesso foi encerrado pela última vez.

  • createdAt data e hora

    Quando a vida foi incluída, em UTC.

  • updatedAt data e hora

    Última mudança de dados ou de status, em UTC.

Rotas

POST /partners/v1/beneficiaries

Incluir uma vida

Inclui uma pessoa na sua empresa e pede a liberação do acesso. Responde 202 sem esperar a liberação, com a vida e o status atual, e o header Location com a URL da vida.

  • Mandar o mesmo CPF de novo não duplica. Se a vida já está ativa, em liberação ou cadastrada (standby), só e-mail, telefone e endereço são atualizados: nome e data de nascimento ficam como estavam.
  • Se a vida estava desativada ou com falha na liberação, a Pump tenta liberar de novo e grava o nome e a data de nascimento enviados. É assim que se reativa alguém.
curl
curl -X POST "https://api.pump.com.br/partners/v1/beneficiaries" \
  -H "X-Api-Key: $PUMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cpf": "12345678909",
    "name": "Maria Souza",
    "birthDate": "1990-04-12",
    "email": "maria.souza@empresa.com.br",
    "phone": "11987654321",
    "address": {
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Sala 12",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01310100"
    }
  }'
Requisição
{
  "cpf": "12345678909",
  "name": "Maria Souza",
  "birthDate": "1990-04-12",
  "email": "maria.souza@empresa.com.br",
  "phone": "11987654321",
  "address": {
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "Sala 12",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "01310100"
  }
}
Resposta · 202 Accepted
{
  "id": "8f3c2a1e-5b7d-4c9a-9e21-6d4f0b8a7c35",
  "cpf": "12345678909",
  "name": "Maria Souza",
  "birthDate": "1990-04-12",
  "email": "maria.souza@empresa.com.br",
  "phone": "11987654321",
  "address": {
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "Sala 12",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "01310100"
  },
  "status": "pending_activation",
  "createdAt": "2026-11-12T14:03:21Z",
  "updatedAt": "2026-11-12T14:03:21Z"
}
POST /partners/v1/beneficiaries/batch

Incluir várias vidas

Inclui até 1000 pessoas numa chamada. Cada vida é tratada sozinha: uma inválida não impede as outras.

  • Os itens voltam na mesma ordem do envio. Use o index pra cruzar com a sua lista. O campo result de cada item está em Status das vidas.
  • O mesmo CPF repetido na mesma chamada é tratado uma vez só.
  • Uma data de nascimento fora do formato AAAA-MM-DD recusa só aquele item, com invalid_birth_date.
  • Corrija só os itens rejeitados e mande de novo. Reenviar os aceitos não duplica.
curl
curl -X POST "https://api.pump.com.br/partners/v1/beneficiaries/batch" \
  -H "X-Api-Key: $PUMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "cpf": "12345678909", "name": "Maria Souza", "birthDate": "1990-04-12" },
      { "cpf": "98765432100", "name": "João Lima", "birthDate": "1985-09-30" },
      { "cpf": "11111111111", "name": "Ana Prado", "birthDate": "1992-01-15" }
    ]
  }'
Requisição
{
  "items": [
    { "cpf": "12345678909", "name": "Maria Souza", "birthDate": "1990-04-12" },
    { "cpf": "98765432100", "name": "João Lima", "birthDate": "1985-09-30" },
    { "cpf": "11111111111", "name": "Ana Prado", "birthDate": "1992-01-15" }
  ]
}
Resposta · 202 Accepted
{
  "accepted": 2,
  "rejected": 1,
  "items": [
    {
      "index": 0,
      "cpf": "12345678909",
      "result": "created",
      "status": "pending_activation",
      "beneficiary": {
        "id": "8f3c2a1e-5b7d-4c9a-9e21-6d4f0b8a7c35",
        "cpf": "12345678909",
        "name": "Maria Souza",
        "birthDate": "1990-04-12",
        "status": "pending_activation",
        "createdAt": "2026-11-12T14:03:21Z",
        "updatedAt": "2026-11-12T14:03:21Z"
      }
    },
    {
      "index": 1,
      "cpf": "98765432100",
      "result": "unchanged",
      "status": "active",
      "beneficiary": {
        "id": "2b9e7d40-1c3f-4a8e-b6d2-9f0a5e4c3b71",
        "cpf": "98765432100",
        "name": "João Lima",
        "birthDate": "1985-09-30",
        "status": "active",
        "activatedAt": "2026-10-02T11:20:15Z",
        "createdAt": "2026-10-02T11:18:40Z",
        "updatedAt": "2026-11-12T14:03:21Z"
      }
    },
    {
      "index": 2,
      "cpf": "11111111111",
      "result": "rejected",
      "problem": {
        "type": "invalid_cpf",
        "title": "CPF inválido",
        "status": 422,
        "detail": "O CPF informado não é válido."
      }
    }
  ]
}
GET /partners/v1/beneficiaries/{id}

Consultar uma vida

Devolve a vida e o status atual, pelo id que a Pump devolveu na inclusão.

Parâmetros

  • idobrigatório Na URL. O id da vida.
  • Um id que não é de uma vida da sua empresa devolve 404.
curl
curl "https://api.pump.com.br/partners/v1/beneficiaries/8f3c2a1e-5b7d-4c9a-9e21-6d4f0b8a7c35" \
  -H "X-Api-Key: $PUMP_API_KEY"
Resposta · 200 OK
{
  "id": "8f3c2a1e-5b7d-4c9a-9e21-6d4f0b8a7c35",
  "cpf": "12345678909",
  "name": "Maria Souza",
  "birthDate": "1990-04-12",
  "email": "maria.souza@empresa.com.br",
  "phone": "11987654321",
  "status": "active",
  "activatedAt": "2026-11-12T14:05:02Z",
  "createdAt": "2026-11-12T14:03:21Z",
  "updatedAt": "2026-11-12T14:05:02Z"
}
POST /partners/v1/beneficiaries/lookup

Buscar uma vida pelo CPF

Faz o mesmo que a consulta, mas pelo CPF. O CPF vai no corpo, nunca na URL.

  • CPF sem vida na sua empresa devolve 404.
curl
curl -X POST "https://api.pump.com.br/partners/v1/beneficiaries/lookup" \
  -H "X-Api-Key: $PUMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cpf": "12345678909"
  }'
Requisição
{
  "cpf": "12345678909"
}
Resposta · 200 OK
{
  "id": "8f3c2a1e-5b7d-4c9a-9e21-6d4f0b8a7c35",
  "cpf": "12345678909",
  "name": "Maria Souza",
  "birthDate": "1990-04-12",
  "email": "maria.souza@empresa.com.br",
  "phone": "11987654321",
  "status": "active",
  "activatedAt": "2026-11-12T14:05:02Z",
  "createdAt": "2026-11-12T14:03:21Z",
  "updatedAt": "2026-11-12T14:05:02Z"
}
GET /partners/v1/beneficiaries

Listar vidas

Lista as vidas da sua empresa, da mais recente pra mais antiga, em páginas.

Parâmetros

  • statusopcional Filtra por um status. Ex.: activation_failed.
  • limitopcional Quantas vidas por página, de 1 a 100. Padrão 100.
  • cursoropcional O nextCursor da página anterior. Sem ele, vem a primeira página.
  • Quando nextCursor vier null, a lista acabou. Ele é o único campo que aparece mesmo vazio.
curl
curl "https://api.pump.com.br/partners/v1/beneficiaries?status=active&limit=50" \
  -H "X-Api-Key: $PUMP_API_KEY"
Resposta · 200 OK
{
  "items": [
    {
      "id": "8f3c2a1e-5b7d-4c9a-9e21-6d4f0b8a7c35",
      "cpf": "12345678909",
      "name": "Maria Souza",
      "birthDate": "1990-04-12",
      "email": "maria.souza@empresa.com.br",
      "phone": "11987654321",
      "status": "active",
      "activatedAt": "2026-11-12T14:05:02Z",
      "createdAt": "2026-11-12T14:03:21Z",
      "updatedAt": "2026-11-12T14:05:02Z"
    }
  ],
  "nextCursor": "eyJpZCI6IjhmM2MyYTFlIn0"
}
DELETE /partners/v1/beneficiaries/{id}

Desativar uma vida

Pede o encerramento do acesso. Responde 202 sem esperar: o status passa por pending_deactivation até chegar a inactive.

Parâmetros

  • idobrigatório Na URL. O id da vida.
  • Desativar uma vida que já está inativa não muda nada.
  • Pra voltar a cobrir a pessoa, inclua de novo com o mesmo CPF.
curl
curl -X DELETE "https://api.pump.com.br/partners/v1/beneficiaries/8f3c2a1e-5b7d-4c9a-9e21-6d4f0b8a7c35" \
  -H "X-Api-Key: $PUMP_API_KEY"
Resposta · 202 Accepted
{
  "id": "8f3c2a1e-5b7d-4c9a-9e21-6d4f0b8a7c35",
  "cpf": "12345678909",
  "name": "Maria Souza",
  "birthDate": "1990-04-12",
  "email": "maria.souza@empresa.com.br",
  "phone": "11987654321",
  "status": "pending_deactivation",
  "activatedAt": "2026-11-12T14:05:02Z",
  "createdAt": "2026-11-12T14:03:21Z",
  "updatedAt": "2026-11-20T09:12:44Z"
}
POST /partners/v1/beneficiaries/deactivate

Desativar uma vida pelo CPF

Faz o mesmo que a desativação, mas pelo CPF, que vai no corpo. Útil quando o seu sistema não guardou o id.

  • CPF sem vida na sua empresa devolve 404.
curl
curl -X POST "https://api.pump.com.br/partners/v1/beneficiaries/deactivate" \
  -H "X-Api-Key: $PUMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cpf": "12345678909"
  }'
Requisição
{
  "cpf": "12345678909"
}
Resposta · 202 Accepted
{
  "id": "8f3c2a1e-5b7d-4c9a-9e21-6d4f0b8a7c35",
  "cpf": "12345678909",
  "name": "Maria Souza",
  "birthDate": "1990-04-12",
  "email": "maria.souza@empresa.com.br",
  "phone": "11987654321",
  "status": "pending_deactivation",
  "activatedAt": "2026-11-12T14:05:02Z",
  "createdAt": "2026-11-12T14:03:21Z",
  "updatedAt": "2026-11-20T09:12:44Z"
}

Status das vidas

Toda vida tem um status. Ele vem em todas as respostas e muda sozinho conforme a Pump avança.

  • pending_activation Liberando acesso

    A Pump recebeu a vida e está liberando o acesso. Costuma levar poucos minutos.

  • active Ativa

    Acesso liberado. A pessoa já pode usar o Pump Saúde no app.

  • standby Cadastrada

    A pessoa está no contrato e o acesso é liberado quando ela usar o serviço pela primeira vez no app. Pra sua empresa, ela já conta como coberta.

  • activation_failed Não liberada

    A Pump não conseguiu liberar o acesso. O campo error diz o motivo e a equipe da Pump vai analisar. Se quiser, reenvie a vida pra tentar de novo.

  • pending_deactivation Desativando

    A Pump recebeu o pedido de desativação e está encerrando o acesso. Logo vira inactive.

  • inactive Desativada

    Acesso encerrado.

O campo error

Aparece quando a última tentativa da Pump falhou. O code é fixo, pra você tratar no seu sistema, e o message explica em português.

  • activation_rejected

    A liberação foi recusada e não será tentada de novo sozinha. A equipe da Pump vai analisar.

  • activation_unconfirmed

    Não deu pra confirmar a liberação depois de várias tentativas. A equipe da Pump vai analisar.

  • deactivation_pending_retry

    O encerramento do acesso ainda não foi confirmado. A Pump segue tentando.

No lote, o campo result

Cada item da resposta do lote diz o que aconteceu com aquela vida.

  • created

    Vida nova. Liberação pedida.

  • reactivated

    A vida estava desativada ou com falha. Liberação pedida de novo, com o nome e a data de nascimento enviados.

  • unchanged

    A vida já estava ativa, em liberação ou cadastrada (standby). Só e-mail, telefone e endereço foram atualizados.

  • rejected

    A vida não foi incluída. O motivo vem em problem.

Erros

Os erros seguem o padrão Problem Details (RFC 9457), com o tipo application/problem+json. O campo type traz um código fixo pra você tratar no seu sistema e detail explica em português. Nos erros 422, errors diz o que corrigir em cada campo.

Exemplo · 422 Unprocessable Content
{
  "type": "invalid_cpf",
  "title": "CPF inválido",
  "status": 422,
  "detail": "O CPF informado não é válido.",
  "instance": "/partners/v1/beneficiaries",
  "errors": {
    "cpf": ["O CPF informado não é válido."]
  }
}
  • validation_failed 400 Bad Request

    Corpo ausente, JSON ilegível ou parâmetro da lista inválido.

    Confira o JSON e os parâmetros.

  • validation_failed 422 Unprocessable Content

    Campo com tipo ou formato errado.

    O campo errors diz o que corrigir em cada campo.

  • invalid_cpf 422 Unprocessable Content

    CPF com dígitos verificadores inválidos.

    Confira o CPF na sua base.

  • invalid_name 422 Unprocessable Content

    Nome vazio ou com mais de 200 caracteres.

    Mande o nome completo.

  • invalid_birth_date 422 Unprocessable Content

    Data de nascimento no futuro, antes de 1900 ou, num item do lote, fora do formato AAAA-MM-DD.

    Confira a data e o formato AAAA-MM-DD.

  • invalid_contact 422 Unprocessable Content

    E-mail, telefone ou endereço em formato inválido.

    Corrija o campo indicado em errors ou mande sem ele.

  • invalid_api_key 401 Unauthorized

    Chave ausente, inválida ou revogada.

    Confira o header X-Api-Key. Se perdeu a chave, peça uma nova.

  • company_suspended 403 Forbidden

    A empresa está suspensa na Pump.

    Fale com o comercial.

  • beneficiary_not_found 404 Not Found

    Nenhuma vida da sua empresa com esse id ou CPF.

    Confira o id, ou inclua a vida antes.

  • cpf_unavailable 409 Conflict

    Este CPF não pode ser incluído pela sua empresa.

    Fale com a Pump.

  • batch_too_large 413 Content Too Large

    Mais de 1000 vidas numa chamada.

    Divida em lotes de até 1000.

  • invalid_cursor 400 Bad Request

    Cursor de paginação inválido.

    Use o nextCursor exatamente como veio, ou comece sem cursor.

  • rate_limited 429 Too Many Requests

    A chave passou do limite de requisições.

    Espere os segundos do header Retry-After e tente de novo.

  • internal_error 500 Internal Server Error

    Erro inesperado do nosso lado.

    Tente de novo em instantes. Reenviar uma inclusão é seguro.

  • temporarily_unavailable 503 Service Unavailable

    Outra requisição alterou as mesmas vidas ao mesmo tempo. Pode vir na inclusão, no lote e na desativação.

    Tente de novo em instantes.

A API também pode responder 503 sem corpo quando estiver fora do ar por um momento. Tente de novo depois de alguns segundos.

Limites

Requisições por chave
600 por minuto
Vidas por chamada no lote
até 1000
Vidas por página na lista
até 100
Tamanho máximo do corpo
5 MB

Passou do limite? A resposta é 429 com o header Retry-After, em segundos. Precisa de mais? Fale com o comercial.

Boas práticas

  • CPF como texto

    A API aceita o CPF com ou sem máscara e devolve só os números. Guarde como texto, não como número, pra não perder os zeros à esquerda.

  • CPF nunca na URL

    URLs costumam ir parar em logs. Por isso as rotas de uma vida usam o id, e a busca e a desativação pelo CPF levam o CPF no corpo.

  • Guarde o id

    Salve o id que volta na inclusão junto do cadastro do colaborador. Com ele, consultar e desativar fica direto.

  • Reenviar é seguro

    Incluir não duplica a vida, e desativar uma vida inativa não muda nada. Se a conexão cair, vier um erro 5xx ou um 503 temporarily_unavailable, espere alguns segundos e mande de novo.

  • Use o lote pra cargas grandes

    Na primeira carga ou numa sincronização, mande lotes de até 1000 vidas em vez de uma chamada por pessoa. Uma chamada por vez, esperando a resposta antes da próxima.

  • Complete os dados

    E-mail, celular e endereço são opcionais, mas com eles o primeiro acesso fica mais rápido: o app só pede o que faltar.

  • Acompanhe pelo status

    Depois de incluir, consulte a vida ou a lista filtrada por status. Em activation_failed, o campo error diz o motivo e a equipe da Pump vai analisar. Reenviar a vida pede uma nova tentativa.

  • Avise quem entrou

    A Pump não manda aviso pro colaborador. Conte pra pessoa que ela tem o Pump Saúde e que o acesso é pelo app.

  • Desative no dia da saída

    Ligue a desativação ao desligamento no seu RH. Assim ninguém fica com acesso depois de sair.

Use com o seu agente de IA

Vai fazer a integração com a ajuda de um agente de IA? Baixe o skill da API e entregue pra ele. O skill ensina as rotas, como transformar a planilha do RH em lotes, como acompanhar cada vida até ficar ativa e o que fazer em cada erro.

Como instalar

  • Claude: envie o .zip em Configurações, na área de Skills.
  • Claude Code: descompacte dentro da pasta .claude/skills do projeto.
  • Outros agentes: descompacte no projeto e peça pra ele ler o SKILL.md antes de começar.

O skill não traz a chave. Guarde a sua numa variável de ambiente, como PUMP_API_KEY, e nunca cole a chave nem dados dos colaboradores no chat.

Histórico de mudanças

  1. 10/11/2026 v1
    • Primeira versão da API: incluir, incluir em lote, consultar, buscar pelo CPF, listar e desativar vidas.