TalentScope 3D™

Conecta tu sistema con TalentScope

Usa esta guía para crear evaluaciones desde tu ATS, HRIS u otra aplicación y consultar su avance o resultado. Si prefieres empezar sin código, puedes probar tu clave directamente desde el Portal Cliente.

Probar conexión en TalentScope

Dirección base

https://talentscope3d.com/api/v1

Cómo autenticarte

Envía tu clave en:

Authorization: Bearer TU_API_KEY

Si tu infraestructura no conserva ese encabezado, también puedes usar X-API-Key.

Formato

Envía y recibe JSON mediante HTTPS. Realiza las llamadas desde tu servidor o desde la consola de pruebas de TalentScope.

Comprueba tu conexión

Empieza por GET /ping. Si la clave es válida, TalentScope confirmará la organización asociada.

curl -H "Authorization: Bearer TU_API_KEY" \
  https://talentscope3d.com/api/v1/ping

Consulta tus créditos

Antes de crear evaluaciones puedes revisar el saldo disponible. La clave necesita el permiso credits:read.

curl -H "Authorization: Bearer TU_API_KEY" \
  https://talentscope3d.com/api/v1/credits

Valida una evaluación sin crearla

Usa POST /evaluations/validate para comprobar los datos, la campaña y la disponibilidad de créditos. Esta llamada no consume crédito ni envía una invitación.

curl -X POST \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  https://talentscope3d.com/api/v1/evaluations/validate \
  -d '{
    "candidate_name":"Laura López",
    "candidate_email":"laura@empresa.com",
    "target_role":"Director Comercial",
    "level":"directivo",
    "campaign_id":24,
    "external_id":"ATS-2026-000184"
  }'

Consejo: campaign_id y external_id son opcionales. Usa external_id si quieres conservar el identificador de tu ATS o HRIS.

Crea la evaluación

Cuando la validación sea correcta, envía el mismo contenido a POST /evaluations. TalentScope consumirá un crédito y enviará la invitación usando el flujo habitual de la plataforma.

Evita duplicados: envía un Idempotency-Key único para cada evaluación que quieras crear. Si tu sistema repite accidentalmente la misma petición con esa misma clave, TalentScope no creará otra evaluación.

curl -X POST \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Idempotency-Key: ats-2026-000184-v1" \
  -H "Content-Type: application/json" \
  https://talentscope3d.com/api/v1/evaluations \
  -d '{
    "candidate_name":"Laura López",
    "candidate_email":"laura@empresa.com",
    "target_role":"Director Comercial",
    "level":"directivo",
    "campaign_id":24,
    "external_id":"ATS-2026-000184"
  }'

Consulta el avance

La respuesta de creación incluye un evaluation_id. Úsalo para consultar el estado de la evaluación.

curl -H "Authorization: Bearer TU_API_KEY" \
  https://talentscope3d.com/api/v1/evaluations/EV-20261003-ABCDE12345

Consulta el resultado disponible

Cuando el resultado esté disponible, consúltalo con GET /results/{evaluation_id}. La respuesta contiene la información entregable de TalentScope y las evidencias complementarias permitidas para esa evaluación.

curl -H "Authorization: Bearer TU_API_KEY" \
  https://talentscope3d.com/api/v1/results/EV-20261003-ABCDE12345

Este endpoint no devuelve reactivos, respuestas de evaluación ni información interna del motor.

Campañas

Si tu integración necesita consultar campañas, usa una clave con el permiso campaigns:read.

curl -H "Authorization: Bearer TU_API_KEY" \
  "https://talentscope3d.com/api/v1/campaigns?page=1&per_page=25&view=active"

Para una campaña específica: GET /campaigns/{id}.

Permisos de una clave

Al crear una clave en el Portal Cliente eliges exactamente qué puede hacer ese sistema.

Permiso	Permite
`evaluations:create`	Validar y crear evaluaciones
`evaluations:read`	Consultar el estado de evaluaciones
`results:read`	Consultar resultados disponibles
`campaigns:read`	Consultar campañas
`credits:read`	Consultar créditos disponibles

Frecuencia recomendada

Tu integración puede trabajar con estos límites. Si necesitas consultar el avance de una evaluación, espera entre 30 y 60 segundos entre consultas.

Operación	Límite
Solicitudes por API key	30 por minuto
Creación de evaluaciones	5 por minuto y 50 por hora
Registros de campañas por página	Hasta 25
Tamaño máximo del JSON	32 KB

Si alcanzas un límite recibirás 429 Too Many Requests junto con Retry-After. Para consultar avances, usa intervalos de 30–60 segundos cuando sea necesario.

Decision Partners™

Si tu organización ya tiene una atribución de Decision Partner™, no necesitas enviar ningún campo adicional. Las evaluaciones creadas por API permanecen dentro de tu organización y conservan la atribución vigente.

Errores y soporte

Cuando una solicitud no pueda completarse recibirás un código, un mensaje y un request_id.

{
  "error": {
    "code": "insufficient_credits",
    "message": "La organización no tiene créditos disponibles.",
    "request_id": "..."
  }
}

Conserva el request_id si necesitas ayuda. No envíes tu API key por correo, chat o capturas.

Versión de la API

Las rutas actuales comienzan con /api/v1/. Si en el futuro existe un cambio incompatible, TalentScope publicará una nueva versión para que tu integración actual pueda seguir funcionando.