TalentAxis para desarrolladores

API y webhooks

Conecta TalentAxis con tu nómina, tu sistema de RR. HH. o tus sistemas internos. Lee y escribe candidatos con la API y recibe un webhook firmado cuando se crea un candidato, cambia de estado o tiene una entrevista.

Autenticación

Las claves de API las crea un Propietario o Administrador en Configuración > API y webhooks. El secreto se muestra una sola vez, al crear la clave. Cópialo en ese momento; si lo pierdes, regenera la clave.

Envía el ID de la clave y el secreto con autenticación HTTP Basic en cada solicitud:

Authorization: Basic base64(key_id:secret)

curl -u "$KEY_ID:$SECRET" https://hireapi.talentaxis.ai/api/v2/public/applicants

URL base: https://hireapi.talentaxis.ai/api/v2

Endpoints

Todas las rutas parten de la URL base indicada arriba.

  • GET /public/applicantsLista candidatos, filtrados por vacante, estado o última actualización, de 50 en 50.
  • GET /public/applicants/{id}Obtiene un candidato con su estado, tipo de etapa, respuestas y origen.
  • POST /public/applicantsCrea un candidato.
  • PATCH /public/applicants/{external_id}Actualiza un candidato por tu ID externo.
  • POST /public/applicants/move-statusMueve candidatos a otro estado del proceso de selección.
  • GET /public/account-locationsLista tus ubicaciones.
  • GET /public/job-hiring-flows/job-idsLista tus vacantes con sus procesos de selección.

Webhooks

Agrega un endpoint https en Configuración > API y webhooks y elige los eventos que quieres recibir. TalentAxis envía un POST con JSON por cada evento.

Eventos

  • applicant.createdSe creó un candidato.
  • applicant.status_changedUn candidato pasó a un nuevo estado del proceso.
  • interview.scheduledSe programó una entrevista.
  • interview.rescheduledSe reprogramó una entrevista.
  • interview.cancelledSe canceló una entrevista.

Contenido

{
  "id": "evt_...",
  "type": "applicant.status_changed",
  "created_at": "2026-11-19T15:04:05Z",
  "company_account_id": "...",
  "data": {
    "applicant_id": "...",
    "job_id": "...",
    "hiring_status_id": "...",
    "hiring_status_name": "Interview",
    "stage_type": "OFFER"
  }
}

Todos los eventos usan el mismo sobre. El contenido incluye solo IDs y estado, nunca nombre, teléfono, correo ni respuestas. Para obtener los detalles, llama a GET /public/applicants/<applicant_id>.

Verificación de firmas

Cada entrega incluye un encabezado TalentAxis-Signature con el formato t=<marca de tiempo unix>,v1=<hex>. El valor es un HMAC-SHA256 de la cadena <marca de tiempo>.<cuerpo sin procesar>, con el secreto de firma de tu endpoint como clave (se muestra una sola vez, al crear el endpoint). Calcúlalo sobre el cuerpo sin procesar, compara en tiempo constante y rechaza la solicitud si t tiene más de 5 minutos.

Node.js

import crypto from "node:crypto";

// rawBody: the request body exactly as received (Buffer or string)
export function verify(header, rawBody, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // older than 5 minutes
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const given = Buffer.from(parts.v1 ?? "", "hex");
  const wanted = Buffer.from(expected, "hex");
  return given.length === wanted.length && crypto.timingSafeEqual(given, wanted);
}

Python

import hashlib, hmac, time

def verify(header: str, raw_body: bytes, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", 0))
    if not t or abs(time.time() - t) > 300:  # older than 5 minutes
        return False
    signed = f"{t}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Conecta con Zapier o Make

No necesitas escribir código. Cualquier herramienta sin código que pueda recibir un webhook y hacer una solicitud HTTP puede usar TalentAxis. Primero crea una clave de API y agrega un webhook en Configuración > API y webhooks, como se describe arriba.

Zapier

  1. Crea un Zap y elige Webhooks by Zapier > Catch Hook como disparador. Copia la URL del hook.
  2. En TalentAxis, agrega esa URL como webhook, elige tus eventos y presiona Send test para que Zapier reciba un ejemplo.
  3. Agrega un paso Webhooks by Zapier > GET. Usa la URL https://hireapi.talentaxis.ai/api/v2/public/applicants/<applicant_id>, con el applicant_id del disparador. Configura la autenticación Basic con el ID y el secreto de tu clave.
  4. Envía el resultado a cualquier app que uses, como nómina, tu HRIS, Google Sheets o Slack.

Make

  1. Crea un escenario y agrega un módulo Custom webhook. Copia su URL.
  2. En TalentAxis, agrega esa URL como webhook, elige tus eventos y presiona Send test para que Make aprenda la estructura de los datos.
  3. Agrega un módulo HTTP > Make a request. Usa la URL https://hireapi.talentaxis.ai/api/v2/public/applicants/<applicant_id>, método GET, y configura la autenticación Basic con el ID y el secreto de tu clave.
  4. Conecta el resultado con el siguiente módulo, como una hoja de cálculo, un mensaje de chat o tu sistema de RR. HH.

Los webhooks llevan solo IDs y estado, por diseño. Por eso el segundo paso obtiene al candidato con tu clave. Para mayor seguridad, puedes verificar el encabezado TalentAxis-Signature en un paso de código, como se muestra arriba en Verificación de firmas.

Reintentos

Responde con cualquier código 2xx en menos de 5 segundos. Si no, reintentamos después de 1 minuto, 5 minutos, 30 minutos, 2 horas y 6 horas. Tras 20 eventos fallidos consecutivos, el endpoint se desactiva automáticamente; corrígelo y vuelve a activarlo en Configuración > API y webhooks. Usa el encabezado TalentAxis-Event-Id para ignorar duplicados.

Versiones

La API tiene la versión en la ruta (/api/v2/). Anunciamos los cambios incompatibles con anticipación y agregamos campos sin una versión nueva, así que ignora los campos que no conozcas.

Referencia de la API

La referencia completa, generada a partir del esquema en vivo.

Cargando la referencia de la API...

Abrir la referencia de la API (esquema OpenAPI)