Visão Geral

Bem-vindo à documentação da API pública do Recrutei. Nossa API foi desenhada para desenvolvedores que querem total controle sobre a exibição de suas vagas em portais externos, agregadores ou na própria página de carreiras da empresa.

Usando rotas REST simples e autenticadas, você pode obter os dados das vagas ativas da sua empresa em tempo real e renderizá-las de acordo com a identidade visual do seu site institucional.

Além das vagas, a API também expõe, em uma rota própria, o formulário de Banco de Talentos da sua empresa, para que a sua página de carreiras ofereça a candidatura espontânea a quem não encontrou uma vaga aberta.

Autenticação

A API exige autenticação por meio de um token de acesso seguro (Bearer Token). Cada requisição HTTP enviada para as rotas protegidas deve conter o header Authorization.

Mantenha seu Token Seguro

Nunca exponha o seu token no código público do frontend (como um repositório Git público ou no código do cliente final se não houver um proxy). Se necessário, utilize rotas de servidor (API routes ou um backend intermediário) para fazer a requisição.

Gerando seu Token de Acesso

Acesse o seu dashboard no Recrutei.
Vá para a página de Configurações.
Na seção de Tokens de API, crie um novo token fornecendo um nome descritivo (ex: "Integração Site de Carreiras").
Copie o token gerado. Ele só será exibido uma vez por questões de segurança.

GET/api/public/jobs

Listar Vagas

Este endpoint retorna uma lista contendo todas as vagas que estão ativas (`isActive: true`) e vinculadas à sua conta. A lista vem ordenada de forma decrescente pela data de publicação (`postedAt`).

Atributos do Retorno

Campo	Tipo	Descrição
id	String	Identificador único da vaga no formato CUID.
title	String	Título da vaga (ex: "Desenvolvedor Front-end").
location	String	Localidade de trabalho (ex: "Remoto" ou "São Paulo, SP").
area	String	Área da vaga (ex: "Tecnologia", "Design").
type	String	Tipo de contratação (ex: "CLT", "PJ", "Estágio").
description	String	Descrição completa da vaga em formato de texto/HTML.
applicationUrl	String	URL pública da página de candidatura da vaga.
postedAt	String (ISO)	Data e hora em que a vaga foi criada.

Chamada ExemplocURL

curl https://recrutei.app/api/public/jobs \
  -H "Authorization: Bearer SEU_TOKEN"

Resposta JSONJSON

{
  "data": [
    {
      "id": "clx...",
      "title": "Desenvolvedor(a) Front-end",
      "location": "Remoto",
      "area": "Tecnologia",
      "type": "CLT",
      "description": "...",
      "applicationUrl": "https://recrutei.app/forms/vaga-desenvolvedor",
      "postedAt": "2026-06-15T12:00:00.000Z"
    }
  ]
}

GET/api/public/jobs/{id}

Detalhes da Vaga

Este endpoint retorna os atributos detalhados de uma única vaga ativa com base em seu ID passado no path da requisição.

Parâmetros de Path

Parâmetro	Tipo	Obrigatório	Descrição
id	String	Sim	O identificador (id) único da vaga.

Chamada ExemplocURL

curl https://recrutei.app/api/public/jobs/{id} \
  -H "Authorization: Bearer SEU_TOKEN"

Resposta JSONJSON

{
  "data": {
    "id": "{id}",
    "title": "Desenvolvedor(a) Front-end",
    "location": "Remoto",
    "area": "Tecnologia",
    "type": "CLT",
    "description": "...",
    "applicationUrl": "https://recrutei.app/forms/vaga-desenvolvedor",
    "postedAt": "2026-06-15T12:00:00.000Z"
  }
}

GET/api/public/talent-pool

Banco de Talentos

Este endpoint retorna o formulário de Banco de Talentos da sua conta: a página de candidatura espontânea para quem não encontrou uma vaga aberta. Use o applicationUrl para um botão "Não encontrou sua vaga? Cadastre-se no nosso banco de talentos" na sua página de carreiras.

Cada conta tem um único Banco de Talentos. Quando ele ainda não foi criado ou está desativado, a rota responde 404.

Atributos do Retorno

Campo	Tipo	Descrição
title	String	Título do formulário (ex: "Banco de Talentos").
description	String \| null	Descrição do formulário, quando preenchida.
applicationUrl	String	URL pública da página de candidatura espontânea.

Chamada ExemplocURL

curl https://recrutei.app/api/public/talent-pool \
  -H "Authorization: Bearer SEU_TOKEN"

Resposta JSONJSON

{
  "data": {
    "title": "Banco de Talentos",
    "description": "Não encontrou a vaga ideal? Deixe seu currículo.",
    "applicationUrl": "https://recrutei.app/forms/banco-de-talentos"
  }
}

Tratamento de Erros

Todas as rotas de API retornam códigos de status HTTP padrão do setor para indicar o sucesso ou a falha de uma requisição.

Códigos HTTP Utilizados

Código	Descrição	Estrutura do Erro
200 OK	A requisição foi bem sucedida.	-
401 Unauthorized	O token de autenticação está ausente, é inválido ou expirou.	{ "error": "Token de acesso inválido ou ausente." }
404 Not Found	A vaga específica ou recurso não pôde ser encontrado.	{ "error": "Vaga não encontrada." }
404 Not Found	A conta não tem Banco de Talentos criado ou ele está desativado.	{ "error": "Banco de talentos não encontrado." }

Amostras de Código

Use o cabeçalho Authorization com seu Bearer Token gerado.

Exemplo Header HTTPHTTP

Authorization: Bearer SEU_TOKEN