Español
Acceso candidatos Acceso empresas

API para desarrolladores

Integra AssessFit con tu ATS, Zapier o herramientas internas: crea vacantes, invita candidatos, obtén resultados y recibe webhooks firmados en cuanto un candidato termina.

Autenticación

Genera una clave de API en Employer Dashboard → Settings → API & integrations y envíala en cada solicitud:

curl https://assessfit.com/api/v1/jobs \
  -H "X-Api-Key: tp_live_…"

Las claves son por espacio de trabajo. Rotar una clave invalida de inmediato la anterior. Las solicitudes se limitan a 300/min por IP.

Endpoints

GET/api/v1/jobs

Lista las vacantes con sus conteos de invitaciones y finalizaciones.

POST/api/v1/jobs

Crea una vacante e invita candidatos en una sola llamada. Los correos de invitación se envían automáticamente; cada invitación consume un crédito.

curl -X POST https://assessfit.com/api/v1/jobs \
  -H "X-Api-Key: tp_live_…" -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Accountant",
    "roleKey": "accountant",
    "tests": ["attention", "financial", "numerical", "conscientiousness"],
    "cameraRequired": true,
    "shareResults": false,
    "candidates": [
      { "name": "Ana Putri", "email": "ana@example.com" }
    ]
  }'

Claves de rol: accountant, engineer, sales, support, marketing, analyst, custom. ¿Se puede omitir tests? No: pasa las claves de las pruebas que quieras; consulta la biblioteca en el panel.

GET/api/v1/jobs/:id

Detalle completo de la vacante: cada invitación con sus marcas de tiempo del embudo (tracking.sent/opened/loggedIn), el linkde invitación personal, y el objeto result una vez completada.

POST/api/v1/jobs/:id/invites

Agrega candidatos a una vacante existente: {"candidates":[{"name":"…","email":"…"}]}. Devuelve las invitaciones creadas con sus enlaces.

GET/api/v1/invites/:id/result

Obtén el resultado completo de un candidato: puntuación global, por prueba, de integridad, veredicto y alertas, y análisis de tiempos. Devuelve 404 hasta que el candidato termina.

Webhooks

Configura una URL de webhook en Settings. AssessFit envía eventos JSON por POST con una firma HMAC-SHA256 calculada sobre el cuerpo crudo usando tu clave de API como secreto:

POST https://your-app.example.com/hooks/assessfit
X-AssessFit-Event: candidate.completed
X-AssessFit-Signature: sha256=3f5a…

{
  "event": "candidate.completed",
  "createdAt": "2026-07-22T09:14:03.000Z",
  "data": {
    "inviteId": "inv_…",
    "jobId": "job_…",
    "jobTitle": "Senior Accountant",
    "candidate": { "name": "Ana Putri", "email": "ana@example.com" },
    "overall": 84,
    "scores": { "attention": 83, "numerical": 100 },
    "integrity": { "score": 100, "verdict": "clean" }
  }
}

Verifica la firma antes de confiar en un payload:

// Node.js
const crypto = require("crypto");
function verify(rawBody, signatureHeader, apiKey) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", apiKey).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}

La entrega se reintenta 3 veces (de inmediato, +2 s, +8 s). Cada intento es visible en Settings → Recent webhook deliveries, y puedes disparar un evento webhook.test cuando quieras con el botón "Send Test Event". Eventos: candidate.completed, webhook.test.

Recetas de integración