Evaluar a una persona candidata

Actualizado 29 de septiembre de 2026

Una evaluación es una entrevista con IA construida a partir de una de tus plantillas de evaluación. La persona candidata la hace cuando le viene bien, y los resultados vuelven a Orbit. Quien trabaja en selección envía evaluaciones desde Orbit. Esta página es para enviarlas desde tu propio sistema, por ejemplo cuando un cambio de etapa en tu ATS debería invitar a la persona candidata sin que nadie abra Orbit.

Qué necesitas

• Una clave con el permiso Screening, creada en Orbit → Configuración → Claves de API. Es un permiso aparte: una clave que lee o gestiona empleos responde 403 aquí, y una clave de Screening no puede leer empleos.
• Un aviso gestionado. Evaluar forma parte de gestionar un aviso, y alguien de selección lo activa en Orbit. En un aviso que no está gestionado, la petición responde 409 con ad_not_managed.
• Tres ids: el jobId del puesto, el id de la persona candidata en ese puesto y el templateId de una de tus plantillas de evaluación activas.

export ORBIT_SCREENING_KEY="…una clave con el permiso Screening…"

Invitar a la persona candidata

curl -X POST https://api.wipperoz.com/v1/jobs/job_01J8Z3K9Q0EXAMPLE/candidates/app_01J9B2C3D4EXAMPLE/screening \
  -H "Authorization: Bearer $ORBIT_SCREENING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tpl_01J9C3D4E5EXAMPLE",
    "completeBy": "2026-10-02T00:00:00.000Z",
    "message": "Gracias por postularte. Te llevará unos quince minutos.",
    "language": "es"
  }'

• templateId es el único campo obligatorio. Tiene que ser una de las plantillas de evaluación activas de tu cuenta.
• completeBy es la fecha límite, como fecha ISO 8601. Sin ella, la persona candidata tiene siete días.
• message es una nota que la persona candidata lee en la invitación, de hasta 1.000 caracteres.
• language es en, es, fr o pt, y en por defecto. Es el idioma del correo de invitación cuando se llega a la persona candidata por correo.

Un campo que la ruta no conoce responde 400, como en todas las escrituras de esta API.

{
  "screening": {
    "screeningId": "8d3f6a2e-4b1c-4f0a-9e7d-2c5b8a1f0e3d",
    "jobId": "job_01J8Z3K9Q0EXAMPLE",
    "candidateId": "app_01J9B2C3D4EXAMPLE",
    "templateId": "tpl_01J9C3D4E5EXAMPLE",
    "status": "invited",
    "deliveryPath": "token",
    "completeBy": "2026-10-02T00:00:00.000Z",
    "requestedAt": "2026-09-25T01:10:00.000Z"
  },
  "billing": "overage",
  "priceCents": 300,
  "currency": "AUD"
}

• deliveryPath dice cómo se llegó a la persona candidata, igual que lo hace Orbit: interview es una solicitud de entrevista en su CV Virtual, y token es un correo con un enlace de un solo uso. Su dirección de correo nunca se devuelve.
• billing es included cuando la evaluación usó una de las incluidas en el aviso, y overage cuando es una adicional.
• priceCents es el precio por evaluación de la plantilla, fijado en este momento, en unidades menores y sin GST. Una evaluación adicional se factura a ese precio solo si la persona candidata la completa: si nunca la hace, no cuesta nada.

De dónde salen los ids

• jobId es el id que recibió el puesto al crearlo, o el que GET /v1/jobs devuelve a una clave que lee empleos.
• El id de la persona candidata es el que Orbit usa para ella en ese puesto. Es la última parte de la dirección de su página en Orbit: …/jobs/{jobId}/candidates/{candidateId}.

Una evaluación a la vez

Una persona candidata tiene una evaluación por puesto a la vez. Mientras hay una abierta, una segunda petición se rechaza, y el rechazo trae la evaluación abierta en error.screening, para que tu sistema retome esa en lugar de enviar otra invitación.

Eso también hace seguro un reintento tras un tiempo de espera agotado. Si la primera petición llegó, el reintento se rechaza con la evaluación que creó, y la persona candidata recibe una sola invitación.

Cuándo se rechaza

Una petición rechazada no envía nada y no deja nada reservado.

Un 429 aquí tiene que ver con la persona candidata, no con tu clave, así que reintentar antes no ayuda. La ruta no está sujeta al límite de peticiones por minuto y no envía cabeceras X-RateLimit-*: lo que la acota es una evaluación abierta por persona candidata y puesto, y el límite mensual de evaluaciones adicionales.

Referencia