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/applicantsURL 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
- Crea un Zap y elige Webhooks by Zapier > Catch Hook como disparador. Copia la URL del hook.
- En TalentAxis, agrega esa URL como webhook, elige tus eventos y presiona Send test para que Zapier reciba un ejemplo.
- 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.
- Envía el resultado a cualquier app que uses, como nómina, tu HRIS, Google Sheets o Slack.
Make
- Crea un escenario y agrega un módulo Custom webhook. Copia su URL.
- En TalentAxis, agrega esa URL como webhook, elige tus eventos y presiona Send test para que Make aprenda la estructura de los datos.
- 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.
- 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...