Reclee

Sourcing

Acciones para preparar el sourcing de una vacante, correr la búsqueda automática que arma su longlist y controlarla mientras avanza.

El sourcing es la búsqueda automática de candidatos para una vacante. Reclee busca personas con el proveedor de datos, las evalúa contra los criterios de la vacante y arma una longlist: la lista de personas calificadas, ordenada de mejor a peor.

Lo arman tres piezas, todas por vacante:

  • El perfil ideal (ICP): el avatar que orienta dónde buscar (países, variantes de cargo, skills, idiomas, el antiperfil) y las búsquedas que salen de él. Lo propone la IA con write_talent_icp y una persona lo aprueba con update_talent_icp. Se cierra con close_talent_icp.
  • Los criterios de sourcing: contra qué se puntúa a cada persona encontrada. El orden es el peso (el primero cuenta el triple que el último) y uno obligatorio es eliminatorio. Los propone la IA con write_sourcing_criteria.
  • La corrida: run_sourcing arranca una corrida que busca, enriquece y puntúa página por página en segundo plano, hasta juntar targetSize personas calificadas o evaluar profileCap perfiles. Si se estanca (sequía, bajo rendimiento) o llega al tope de perfiles, se pausa y espera una decisión: seguir (continue_sourcing) o cerrar con lo que hay (cancel_sourcing). Al cerrar, la longlist queda congelada.

Con las búsquedas ya puntuadas, build_longlist arma una longlist sin buscar ni gastar nada más.

Seguir el progreso. Una corrida avanza sola; para ver dónde está, lee el ICP de la vacante con la tool get_talent_icp (su campo openRun trae longlistId, status, el motivo de pausa y cuántas personas calificaron contra el objetivo) o, por REST, GET /sourcing/runs?talentIcpId=… (el estado de la corrida abierta, o null), GET /sourcing/longlists/{longlistId} (el resumen de la longlist) y GET /sourcing/runs/{longlistId}/page (la página en curso con cada persona ya puntuada).

Cómo se llama una acción

POST https://app.reclee.com/api/v1/actions/<nombre> con body JSON y Authorization: Bearer rcl_…. Las acciones que gastan (GENERATE y PROVIDER) devuelven cost con lo consumido: aiUsagePct y teamUsagePct (fracción de 0 a 1), credits y billedLater. Manda un Idempotency-Key para reintentar sin gastar dos veces (Idempotencia). El sourcing se cobra contra el uso de IA del plan; cuando el uso del mes se termina, se paga con créditos comprados si el workspace tiene. Los errores comunes están en Errores; los límites de uso, en Créditos y uso.

write_sourcing_criteria

Familia: GENERATE · Consume uso de IA: una generación con un modelo.

Lee la vacante y escribe sus criterios de sourcing, contra los que se puntúa cada perfil encontrado (hasta 10). Se guardan en el momento, como una propuesta que una persona revisa en la pantalla de sourcing de la app; la respuesta dice cuántos escribió, no su contenido.

Solo escribe cuando la vacante no tiene ningún criterio de sourcing: si ya tiene, contesta ALREADY_WRITTEN, porque guardar una lista reemplaza el conjunto entero. Necesita que la vacante tenga descripción y país. Mientras haya una corrida abierta, los criterios están congelados (la corrida puntúa con los que tenía).

POST/actions/write_sourcing_criteria

Body

CampoTipoRequeridoDescripción
jobPostIdstring (uuid)SíLa vacante.

Ejemplo

curl -X POST https://app.reclee.com/api/v1/actions/write_sourcing_criteria \
  -H "Authorization: Bearer rcl_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3e8c0a71-criteria-2e4a" \
  -d '{ "jobPostId": "2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90" }'

Respuesta

next sugiere lo que la vacante todavía no tiene (por ejemplo, su perfil ideal). Extracto:

{
  "data": { "jobPostId": "2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90", "written": 7 },
  "links": [
    {
      "kind": "job_post",
      "id": "2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90",
      "label": "Senior Backend Engineer (Go)",
      "href": "https://app.reclee.com/job-posts/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90/sourcing?tab=definitions"
    }
  ],
  "next": {
    "missing": [],
    "suggestions": [
      {
        "tool": "write_talent_icp",
        "input": { "jobPostId": "2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90" },
        "readsFrom": ["PREVIOUS_STEPS"]
      }
    ]
  },
  "cost": { "aiUsagePct": 0.002, "teamUsagePct": 0, "credits": 0, "billedLater": false }
}

Errores

CódigoHTTPCuándo
ALREADY_WRITTEN409La vacante ya tiene criterios de sourcing.
TOO_MANY_CRITERIA400La propuesta superó los 10 criterios.
JOB_POST_INCOMPLETE409A la vacante le falta descripción o país. missing dice cuál; se completa con update_job_post.
CRITERIA_FROZEN409Hay una corrida abierta en la vacante. Espera a que cierre o ciérrala con cancel_sourcing.
USAGE_WINDOW / TEAM_WINDOW402Se alcanzó el límite de uso de las últimas cinco horas (propio o del equipo).
USAGE_EXHAUSTED / TEAM_USAGE_EXHAUSTED402Se terminó el uso del mes (propio o del equipo).
NOT_FOUND404La vacante no existe en el workspace.

write_talent_icp

Familia: GENERATE · Consume uso de IA: una generación para el perfil y otra para sus búsquedas.

Lee la vacante y propone su perfil ideal (países, variantes de cargo, skills, idiomas, antiperfil) junto con las búsquedas que salen de él. Ambos quedan como propuestas esperando revisión: hasta que se aprueben, run_sourcing contesta ICP_NEEDS_REVIEW. Para aprobarlas, léelas (tool get_talent_icp y list_sourcing_searches, o GET /sourcing/talent-icps/{talentIcpId}), muéstralas a una persona y aprueba con update_talent_icp (approve y approveSearchIds), o que lo haga alguien desde la pantalla de sourcing.

Solo escribe cuando la vacante no tiene ningún perfil ideal activo; si tiene uno, contesta ALREADY_WRITTEN. El perfil ideal no puntúa a nadie: eso lo hacen los criterios de sourcing. Si falla la propuesta de búsquedas, o no queda tiempo para proponerlas, el perfil queda propuesto igual y searchDefinitions es 0: agrégalas con create_sourcing_search.

POST/actions/write_talent_icp

Body

CampoTipoRequeridoDescripción
jobPostIdstring (uuid)SíLa vacante.

Ejemplo

curl -X POST https://app.reclee.com/api/v1/actions/write_talent_icp \
  -H "Authorization: Bearer rcl_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b2f4d11-icp-2e4a" \
  -d '{ "jobPostId": "2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90" }'

Respuesta

Extracto:

{
  "data": {
    "jobPostId": "2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90",
    "talentIcpId": "0d2f4b6a-8c1e-4a3d-b5f7-9a1c3e5b7d8f",
    "written": 1,
    "searchDefinitions": 3
  },
  "links": [
    {
      "kind": "job_post",
      "id": "2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90",
      "label": "Senior Backend Engineer (Go)",
      "href": "https://app.reclee.com/job-posts/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90/sourcing?tab=definitions"
    }
  ],
  "next": {
    "missing": [],
    "suggestions": [
      { "tool": "list_sourcing_searches", "input": { "talentIcpId": "0d2f4b6a-8c1e-4a3d-b5f7-9a1c3e5b7d8f" } },
      { "tool": "update_talent_icp", "input": { "talentIcpId": "0d2f4b6a-8c1e-4a3d-b5f7-9a1c3e5b7d8f" } }
    ]
  },
  "cost": { "aiUsagePct": 0.003, "teamUsagePct": 0, "credits": 0, "billedLater": false }
}

Errores

CódigoHTTPCuándo
ALREADY_WRITTEN409La vacante ya tiene un perfil ideal activo.
JOB_POST_INCOMPLETE409A la vacante le falta descripción o país. missing dice cuál.
USAGE_WINDOW / TEAM_WINDOW402Se alcanzó el límite de uso de las últimas cinco horas.
USAGE_EXHAUSTED / TEAM_USAGE_EXHAUSTED402Se terminó el uso del mes.
NOT_FOUND404La vacante no existe en el workspace.

update_talent_icp

Familia: DO · No consume créditos.

Edita un perfil ideal ya escrito y aprueba lo que Reclee propuso para él. En una misma llamada puedes combinar las tres cosas:

  • Editar campos: una lista reemplaza la lista entera y null vacía un texto. Editar sube la versión del perfil: la próxima corrida lo cuenta como un cambio de configuración.
  • approve: true: saca al perfil de NEEDS_REVIEW para que run_sourcing lo pueda usar. Si no estaba esperando revisión, contesta NOTHING_TO_CHANGE.
  • approveSearchIds: aprueba búsquedas propuestas (las que tienen estado NEEDS_REVIEW). Cada una empieza a correr en la próxima corrida; una que reemplaza a otra pausa a la anterior.

Hace falta al menos un campo, approve o approveSearchIds. next dice qué sigue esperando revisión, o sugiere run_sourcing cuando ya no queda nada.

POST/actions/update_talent_icp

Body

CampoTipoRequeridoDescripción
talentIcpIdstring (uuid)SíEl perfil ideal.
namestringOpcionalNombre. De 1 a 200 caracteres.
countrystring | nullOpcionalPaís. Máximo 100 caracteres.
citystring | nullOpcionalCiudad. Máximo 100 caracteres.
worksAtstring | nullOpcionalDónde trabaja hoy el perfil buscado (tipo de empresa, empresas). Máximo 300 caracteres.
titleVariantsstring[]OpcionalVariantes del cargo. Hasta 30, de 1 a 120 caracteres.
senioritystring | nullOpcionalSeniority. Máximo 60 caracteres.
minYearsExperienceinteger | nullOpcionalAños mínimos de experiencia, de 0 a 60.
languagesstring[]OpcionalIdiomas. Hasta 20, de 1 a 60 caracteres.
skillsstring[]OpcionalSkills. Hasta 50, de 1 a 80 caracteres.
antiProfilestring | nullOpcionalA quién NO se busca. Máximo 2000 caracteres.
descriptionstring | nullOpcionalDescripción. Máximo 4000 caracteres.
approvetrueOpcionalSolo acepta true: aprueba el perfil propuesto.
approveSearchIdsstring[] (uuid)OpcionalBúsquedas propuestas a aprobar. De 1 a 50.

Ejemplo

Ajusta las skills y aprueba el perfil y dos de sus búsquedas:

curl -X POST https://app.reclee.com/api/v1/actions/update_talent_icp \
  -H "Authorization: Bearer rcl_..." \
  -H "Content-Type: application/json" \
  -d '{
    "talentIcpId": "0d2f4b6a-8c1e-4a3d-b5f7-9a1c3e5b7d8f",
    "skills": ["Go", "Kubernetes", "PostgreSQL", "gRPC"],
    "approve": true,
    "approveSearchIds": [
      "a1b3c5d7-e9f1-4a2c-8b4d-6e8f0a2c4e6b",
      "c2d4e6f8-0a1b-4c3d-9e5f-7a9b1c3d5e7f"
    ]
  }'

Respuesta

status es el estado del perfil (ACTIVE, NEEDS_REVIEW o DISCARDED) y version, su versión actual.

{
  "data": {
    "talentIcpId": "0d2f4b6a-8c1e-4a3d-b5f7-9a1c3e5b7d8f",
    "status": "ACTIVE",
    "version": 2,
    "approvedSearches": 2
  },
  "links": [ "…el perfil ideal…" ],
  "next": {
    "missing": [],
    "suggestions": [
      { "tool": "run_sourcing", "input": { "jobPostId": "2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90" } }
    ]
  }
}

Errores

CódigoHTTPCuándo
INVALID400No mandaste ningún campo, ni approve, ni approveSearchIds.
NOTHING_TO_CHANGE409approve: true sobre un perfil que no estaba esperando revisión.
ICP_CLOSED409El perfil ideal está cerrado: no vuelve a correr, así que no se edita ni se aprueba.
NOT_FOUND404El perfil no existe, o un id de approveSearchIds no es una búsqueda propuesta de este perfil.
LIMIT_REACHED409El perfil ya corre tantas búsquedas como se permite. suggestions sugiere revisarlas con list_sourcing_searches.

Familia: DO · No consume créditos: agregarla no busca ni gasta nada.

Agrega una búsqueda al perfil ideal (ICP) de una vacante: los filtros que una corrida de sourcing usa para encontrar personas. Queda activa en cuanto se guarda: la próxima corrida (run_sourcing) ya la usa, y una corrida abierta la toma cuando la sigues (continue_sourcing).

Antes de agregar una, lee las que el perfil ya tiene (tool list_sourcing_searches o GET /sourcing/search-definitions?talentIcpId=…) para no repetirlas. Para escribir un perfil ideal nuevo con sus búsquedas propuestas está write_talent_icp; para aprobar una búsqueda propuesta, update_talent_icp. La versión REST es POST /sourcing/search-definitions.

POST/actions/create_sourcing_search

Body

CampoTipoRequeridoDescripción
talentIcpIdstring (uuid)SíEl perfil ideal (de get_talent_icp).
namestringOpcionalNombre de la búsqueda. De 1 a 200 caracteres.
queryobjectSíLos filtros. Mismos campos y reglas que los filtros de búsqueda de talento: hace falta al menos uno y una ciudad necesita su país.

query acepta los campos de los filtros de búsqueda: title, headline, skills, geoCountryCode (ISO 3166-1 alfa-2), geoCity, experienceMinYears, speaksLanguage, industry, organizationSlugs, educationLevel, certifications, excludeTitles, excludeOrganizationSlugs y excludeIndustries. Cada lista admite hasta 20 valores.

Ejemplo

curl -X POST https://app.reclee.com/api/v1/actions/create_sourcing_search \
  -H "Authorization: Bearer rcl_..." \
  -H "Content-Type: application/json" \
  -d '{
    "talentIcpId": "0d2f4b6a-8c1e-4a3d-b5f7-9a1c3e5b7d8f",
    "name": "Backend Go en Uruguay",
    "query": {
      "title": "Backend Engineer",
      "skills": ["Go", "Kubernetes"],
      "geoCountryCode": "uy"
    }
  }'

Respuesta

{
  "data": { "searchId": "e3f5a7b9-1c2d-4e6f-8a0b-2c4d6e8f0a1b", "status": "READY" },
  "links": [ "…el perfil ideal…" ],
  "next": {
    "missing": [],
    "suggestions": [
      { "tool": "run_sourcing", "input": { "jobPostId": "2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90" } }
    ]
  }
}

searchId es el id de la búsqueda nueva (el mismo que GET /sourcing/search-definitions devuelve como id) y status es READY: lista para la próxima corrida.

Errores

CódigoHTTPCuándo
INVALID400query no trae ningún filtro, un filtro no es válido o mandaste una ciudad sin país. details nombra el campo.
LIMIT_REACHED409El perfil ya corre tantas búsquedas como se permite.
ICP_CLOSED409El perfil ideal está cerrado: no vuelve a correr.
NOT_FOUND404El perfil ideal no existe en el workspace.

close_talent_icp

Familia: DO · No consume créditos.

Cierra el perfil ideal de una vacante, con un motivo obligatorio. Deja de orientar corridas nuevas, y las longlists que salieron de él siguen apuntándole. Un perfil ideal no se borra por API: cerrarlo es la alternativa. Si con esto la vacante se queda sin ningún perfil ideal, next sugiere escribir uno nuevo con write_talent_icp.

POST/actions/close_talent_icp

Body

CampoTipoRequeridoDescripción
talentIcpIdstring (uuid)SíEl perfil ideal.
closeReasonstringSíPor qué se cierra. De 1 a 500 caracteres.

Ejemplo

curl -X POST https://app.reclee.com/api/v1/actions/close_talent_icp \
  -H "Authorization: Bearer rcl_..." \
  -H "Content-Type: application/json" \
  -d '{
    "talentIcpId": "0d2f4b6a-8c1e-4a3d-b5f7-9a1c3e5b7d8f",
    "closeReason": "El cliente cambió el perfil a frontend."
  }'

Respuesta

{
  "data": { "talentIcpId": "0d2f4b6a-8c1e-4a3d-b5f7-9a1c3e5b7d8f", "status": "DISCARDED" },
  "links": [ "…el perfil ideal…" ],
  "next": {
    "missing": ["talentIcp"],
    "suggestions": [
      {
        "tool": "write_talent_icp",
        "input": { "jobPostId": "2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90" },
        "readsFrom": ["PREVIOUS_STEPS"]
      }
    ]
  }
}

Errores

CódigoHTTPCuándo
NOTHING_TO_CHANGE409El perfil ya estaba cerrado.
NOT_FOUND404El perfil no existe en el workspace.

run_sourcing

Familia: PROVIDER · Consume uso de IA: cada página busca, enriquece y puntúa perfiles. El gasto se registra a medida que la corrida avanza.

Arranca la construcción de la longlist de una vacante: una corrida con su perfil ideal actual y todas sus búsquedas que no estén pausadas, que va por targetSize personas calificadas evaluando como máximo profileCap perfiles (al llegar al tope se pausa y pregunta). Sigue sola en segundo plano: la respuesta llega apenas la corrida abre.

Antes de abrir, la acción verifica toda la configuración y contesta con un error si falta algo (ver la tabla). Si la última corrida de la vacante la cerró una persona (CANCELLED), confirma con ella antes de arrancar otra. Si nada cambió desde la última corrida (ni el perfil ideal, ni los criterios, ni el umbral, ni las búsquedas), contesta NOTHING_CHANGED: correrla de nuevo traería a las mismas personas.

Cómo estimar antes. GET /sourcing/runs/quote?profileCap=500 no abre nada y devuelve metered (si el plan mide uso), monthShare (qué fracción del uso del mes podría consumir una corrida con ese tope, de 0 a 1), leftShare (qué fracción queda), exceedsLeft (si el tope supera lo que queda) y creditCovers. Como el gasto real se registra durante la corrida, el cost de esta respuesta viene con billedLater: true.

POST/actions/run_sourcing

Body

CampoTipoRequeridoDescripción
jobPostIdstring (uuid)SíLa vacante.
targetSizeintegerOpcionalPersonas calificadas buscadas, de 1 a 2000. Default 150. No puede superar profileCap.
profileCapintegerOpcionalPerfiles a evaluar como máximo, de 1 a 2000. Default 500.

Ejemplo

curl -X POST https://app.reclee.com/api/v1/actions/run_sourcing \
  -H "Authorization: Bearer rcl_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 41d0c6b2-run-2e4a-01" \
  -d '{
    "jobPostId": "2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90",
    "targetSize": 60,
    "profileCap": 300
  }'

Respuesta

{
  "data": {
    "longlistId": "6f8a0c2e-4b6d-4f8a-9c1e-3a5c7e9b1d2f",
    "targetSize": 60,
    "profileCap": 300,
    "searchDefinitions": 3
  },
  "links": [
    {
      "kind": "longlist",
      "id": "6f8a0c2e-4b6d-4f8a-9c1e-3a5c7e9b1d2f",
      "label": "Backend Go · LATAM",
      "href": "https://app.reclee.com/job-posts/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90/sourcing?tab=longlists&run=6f8a0c2e-4b6d-4f8a-9c1e-3a5c7e9b1d2f"
    }
  ],
  "next": {
    "missing": [],
    "suggestions": [
      { "tool": "get_talent_icp", "input": { "jobPostId": "2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90" } }
    ]
  },
  "cost": { "aiUsagePct": 0, "teamUsagePct": 0, "credits": 0, "billedLater": true }
}

searchDefinitions es cuántas búsquedas corre.

Seguir la corrida

Consulta periódicamente la tool get_talent_icp con { "jobPostId": "…" } y mira openRun: status RUNNING (avanza sola), PAUSED (espera una decisión: continue_sourcing o cancel_sourcing), y cuántas personas calificaron contra el objetivo. Cuando openRun vuelve null, la corrida cerró: la longlist se lee con GET /sourcing/longlists/{longlistId} o la tool get_longlist. Por REST también tienes GET /sourcing/runs?talentIcpId=… (estado completo de la corrida abierta: status, pausedReason, qualified, profilesEvaluated…).

Errores

Todos se contestan antes de abrir la corrida, sin gastar.

CódigoHTTPCuándo
INVALID400targetSize supera profileCap, o un valor está fuera de rango.
JOB_POST_DRAFT409La vacante sigue en borrador: primero se activa desde su asistente de creación en la app.
NO_SOURCING_CRITERIA409La vacante no tiene criterios de sourcing: no hay contra qué puntuar. Ver write_sourcing_criteria.
NO_ICP409La vacante no tiene perfil ideal. Ver write_talent_icp.
ICP_NEEDS_REVIEW409El perfil ideal es una propuesta que nadie aprobó. Ver update_talent_icp.
NO_DEFINITIONS409No hay ninguna búsqueda activa. Se crean o aprueban desde la pantalla de sourcing (o con approveSearchIds).
RUN_IN_PROGRESS409Ya hay una corrida abierta. Síguela, o ciérrala con cancel_sourcing.
NOTHING_CHANGED409Nada cambió desde la última corrida.
USAGE_WINDOW402Se alcanzó el límite de uso de las últimas cinco horas.
USAGE_EXHAUSTED402Se terminó el uso de IA del mes.
NOT_FOUND404La vacante no existe en el workspace.

Las negativas que tienen arreglo traen missing y suggestions con la acción que lo resuelve, ya con los ids:

{
  "error": "NO_ICP",
  "missing": ["talentIcp"],
  "suggestions": [
    {
      "tool": "write_talent_icp",
      "readsFrom": ["PREVIOUS_STEPS"],
      "input": { "jobPostId": "2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90" }
    }
  ]
}

continue_sourcing

Familia: PROVIDER · Consume uso de IA: una página más de la corrida (búsqueda, enriquecimiento y puntaje).

Hace avanzar una corrida abierta. Sobre una corrida pausada esperando una decisión (sequía, bajo rendimiento o el tope de perfiles), es la decisión de seguir buscando: compra una página más después de la pausa. Sobre una que está corriendo, trae la página siguiente ya.

La página se busca, enriquece y puntúa antes de contestar, lo que tarda unos dos minutos: configura el timeout de tu cliente HTTP en consecuencia. Con autoStep: true (default), después la corrida vuelve a avanzar sola; con false, trae solo esta página y queda esperando.

Cómo estimar antes. Como mucho, lo que queda del tope: GET /sourcing/runs/quote?profileCap=N con N = profileCap - profilesEvaluated de la corrida.

POST/actions/continue_sourcing

Body

CampoTipoRequeridoDescripción
jobPostIdstring (uuid)SíLa vacante.
longlistIdstring (uuid)SíLa corrida (el longlistId de openRun o de run_sourcing).
autoStepbooleanOpcionalDefault true: después de esta página, la corrida sigue sola. false: se queda esperando.

Ejemplo

curl -X POST https://app.reclee.com/api/v1/actions/continue_sourcing \
  -H "Authorization: Bearer rcl_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 41d0c6b2-continue-6f8a-03" \
  --max-time 300 \
  -d '{
    "jobPostId": "2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90",
    "longlistId": "6f8a0c2e-4b6d-4f8a-9c1e-3a5c7e9b1d2f",
    "autoStep": true
  }'

Respuesta

{
  "data": {
    "longlistId": "6f8a0c2e-4b6d-4f8a-9c1e-3a5c7e9b1d2f",
    "status": "RUNNING",
    "pausedReason": null,
    "stopReason": null,
    "qualified": 34,
    "targetSize": 60,
    "profilesEvaluated": 180,
    "profileCap": 300,
    "lastPage": { "profiles": 20, "scored": 18, "performancePct": 42.5 }
  },
  "links": [ "…la longlist…" ],
  "next": {
    "missing": [],
    "suggestions": [
      { "tool": "get_talent_icp", "input": { "jobPostId": "2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90" } }
    ]
  },
  "cost": { "aiUsagePct": 0.006, "teamUsagePct": 0, "credits": 0, "billedLater": true }
}
  • status: RUNNING (puede seguir), PAUSED (espera una decisión; pausedReason dice por qué) o DONE (la longlist cerró; stopReason dice por qué).
  • pausedReason / stopReason: COMPLETE (llegó al objetivo), PROFILE_CAP (llegó al tope de perfiles), LOW_PERFORMANCE, DROUGHT o CANCELLED.
  • lastPage: lo que hizo esta página: perfiles traídos, perfiles puntuados y su rendimiento. null si no se buscó nada.
  • next cambia según el estado: con PAUSED sugiere continue_sourcing y cancel_sourcing; con DONE, get_longlist.

Errores

CódigoHTTPCuándo
RUN_ALREADY_CLOSED409La corrida ya cerró.
NO_SOURCING_CRITERIA409La vacante se quedó sin criterios de sourcing.
NO_ICP409La vacante se quedó sin perfil ideal.
USAGE_EXHAUSTED402Se terminó el uso de IA del mes.
USAGE_WINDOW402Se alcanzó el límite de uso de las últimas cinco horas.
NOT_FOUND404La corrida no existe o no es de esa vacante.

cancel_sourcing

Familia: DO · No consume créditos: siempre deja de gastar.

Detiene una corrida abierta. Cuando puede, congela su longlist con quienes ya calificaron (frozen: true): una corrida pausada por un veredicto (sequía, bajo rendimiento, tope de perfiles) cierra con ese veredicto; una que nada había pausado cierra como CANCELLED (detenida a mano).

Cuando todavía no se puede congelar (nadie fue puntuado, o se está evaluando una página en este momento), no se niega: hace que la corrida no empiece ninguna página nueva. La página en curso termina y la corrida queda abierta con lo que tiene (frozen: false) hasta que la vuelvas a cancelar para congelarla, o la sigas con continue_sourcing.

POST/actions/cancel_sourcing

Body

CampoTipoRequeridoDescripción
jobPostIdstring (uuid)SíLa vacante.
longlistIdstring (uuid)SíLa corrida abierta.

Ejemplo

curl -X POST https://app.reclee.com/api/v1/actions/cancel_sourcing \
  -H "Authorization: Bearer rcl_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jobPostId": "2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90",
    "longlistId": "6f8a0c2e-4b6d-4f8a-9c1e-3a5c7e9b1d2f"
  }'

Respuesta

{
  "data": { "frozen": true, "stopReason": "DROUGHT", "qualified": 34, "targetSize": 60 },
  "links": [
    {
      "kind": "longlist",
      "id": "6f8a0c2e-4b6d-4f8a-9c1e-3a5c7e9b1d2f",
      "label": "Backend Go · LATAM",
      "href": "https://app.reclee.com/job-posts/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90/sourcing?tab=longlists&list=6f8a0c2e-4b6d-4f8a-9c1e-3a5c7e9b1d2f"
    }
  ]
}

Si todavía no se podía congelar, data es { "frozen": false, "qualified": 0, "targetSize": 60 }: la corrida sigue abierta y no trae más páginas.

Errores

CódigoHTTPCuándo
RUN_ALREADY_CLOSED409La corrida ya cerró.
NOT_FOUND404La corrida no existe o no es de esa vacante.

build_longlist

Familia: DO · No consume créditos: no busca ni puntúa a nadie.

Arma una longlist con lo que las búsquedas de un perfil ideal ya puntuaron: las personas calificadas, de mejor a peor puntaje, cortadas en targetSize. Lo normal es dejar que una corrida cierre, que hace esto sola; esta acción es para búsquedas corridas por separado. Para cerrar una corrida abierta con lo que tiene, usa cancel_sourcing.

POST/actions/build_longlist

Body

CampoTipoRequeridoDescripción
talentIcpIdstring (uuid)SíEl perfil ideal.
targetSizeintegerOpcionalTamaño máximo de la longlist, de 1 a 500. Default 150.
namestringOpcionalNombre de la longlist. De 1 a 200 caracteres.

Ejemplo

curl -X POST https://app.reclee.com/api/v1/actions/build_longlist \
  -H "Authorization: Bearer rcl_..." \
  -H "Content-Type: application/json" \
  -d '{
    "talentIcpId": "0d2f4b6a-8c1e-4a3d-b5f7-9a1c3e5b7d8f",
    "targetSize": 50,
    "name": "Shortlist preliminar Andes Pay"
  }'

Respuesta

status es el estado de la longlist (OPEN, CLOSED_COMPLETE o CLOSED_PARTIAL).

{
  "data": {
    "longlistId": "8b0d2f4a-6c8e-4a1b-9d3f-5a7c9e1b3d5f",
    "status": "CLOSED_PARTIAL",
    "targetSize": 50,
    "profilesEvaluated": 212
  },
  "links": [ "…el perfil ideal y la longlist…" ],
  "next": {
    "missing": [],
    "suggestions": [
      {
        "tool": "get_longlist",
        "input": {
          "jobPostId": "2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a90",
          "longlistId": "8b0d2f4a-6c8e-4a1b-9d3f-5a7c9e1b3d5f"
        }
      }
    ]
  }
}

Errores

CódigoHTTPCuándo
NOTHING_SCORED409Todavía no se puntuó a nadie. suggestions sugiere run_sourcing.
NOT_FOUND404El perfil ideal no existe en el workspace.

En esta página