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_icpy una persona lo aprueba conupdate_talent_icp. Se cierra conclose_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_sourcingarranca una corrida que busca, enriquece y puntúa página por página en segundo plano, hasta juntartargetSizepersonas calificadas o evaluarprofileCapperfiles. 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).
/actions/write_sourcing_criteriaBody
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| jobPostId | string (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ódigo | HTTP | Cuándo |
|---|---|---|
ALREADY_WRITTEN | 409 | La vacante ya tiene criterios de sourcing. |
TOO_MANY_CRITERIA | 400 | La propuesta superó los 10 criterios. |
JOB_POST_INCOMPLETE | 409 | A la vacante le falta descripción o país. missing dice cuál; se completa con update_job_post. |
CRITERIA_FROZEN | 409 | Hay una corrida abierta en la vacante. Espera a que cierre o ciérrala con cancel_sourcing. |
USAGE_WINDOW / TEAM_WINDOW | 402 | Se alcanzó el límite de uso de las últimas cinco horas (propio o del equipo). |
USAGE_EXHAUSTED / TEAM_USAGE_EXHAUSTED | 402 | Se terminó el uso del mes (propio o del equipo). |
NOT_FOUND | 404 | La 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.
/actions/write_talent_icpBody
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| jobPostId | string (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ódigo | HTTP | Cuándo |
|---|---|---|
ALREADY_WRITTEN | 409 | La vacante ya tiene un perfil ideal activo. |
JOB_POST_INCOMPLETE | 409 | A la vacante le falta descripción o país. missing dice cuál. |
USAGE_WINDOW / TEAM_WINDOW | 402 | Se alcanzó el límite de uso de las últimas cinco horas. |
USAGE_EXHAUSTED / TEAM_USAGE_EXHAUSTED | 402 | Se terminó el uso del mes. |
NOT_FOUND | 404 | La 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
nullvací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 deNEEDS_REVIEWpara querun_sourcinglo pueda usar. Si no estaba esperando revisión, contestaNOTHING_TO_CHANGE.approveSearchIds: aprueba búsquedas propuestas (las que tienen estadoNEEDS_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.
/actions/update_talent_icpBody
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| talentIcpId | string (uuid) | Sí | El perfil ideal. |
| name | string | Opcional | Nombre. De 1 a 200 caracteres. |
| country | string | null | Opcional | País. Máximo 100 caracteres. |
| city | string | null | Opcional | Ciudad. Máximo 100 caracteres. |
| worksAt | string | null | Opcional | Dónde trabaja hoy el perfil buscado (tipo de empresa, empresas). Máximo 300 caracteres. |
| titleVariants | string[] | Opcional | Variantes del cargo. Hasta 30, de 1 a 120 caracteres. |
| seniority | string | null | Opcional | Seniority. Máximo 60 caracteres. |
| minYearsExperience | integer | null | Opcional | Años mínimos de experiencia, de 0 a 60. |
| languages | string[] | Opcional | Idiomas. Hasta 20, de 1 a 60 caracteres. |
| skills | string[] | Opcional | Skills. Hasta 50, de 1 a 80 caracteres. |
| antiProfile | string | null | Opcional | A quién NO se busca. Máximo 2000 caracteres. |
| description | string | null | Opcional | Descripción. Máximo 4000 caracteres. |
| approve | true | Opcional | Solo acepta true: aprueba el perfil propuesto. |
| approveSearchIds | string[] (uuid) | Opcional | Bú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ódigo | HTTP | Cuándo |
|---|---|---|
INVALID | 400 | No mandaste ningún campo, ni approve, ni approveSearchIds. |
NOTHING_TO_CHANGE | 409 | approve: true sobre un perfil que no estaba esperando revisión. |
ICP_CLOSED | 409 | El perfil ideal está cerrado: no vuelve a correr, así que no se edita ni se aprueba. |
NOT_FOUND | 404 | El perfil no existe, o un id de approveSearchIds no es una búsqueda propuesta de este perfil. |
LIMIT_REACHED | 409 | El perfil ya corre tantas búsquedas como se permite. suggestions sugiere revisarlas con list_sourcing_searches. |
create_sourcing_search
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.
/actions/create_sourcing_searchBody
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| talentIcpId | string (uuid) | Sí | El perfil ideal (de get_talent_icp). |
| name | string | Opcional | Nombre de la búsqueda. De 1 a 200 caracteres. |
| query | object | Sí | 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ódigo | HTTP | Cuándo |
|---|---|---|
INVALID | 400 | query no trae ningún filtro, un filtro no es válido o mandaste una ciudad sin país. details nombra el campo. |
LIMIT_REACHED | 409 | El perfil ya corre tantas búsquedas como se permite. |
ICP_CLOSED | 409 | El perfil ideal está cerrado: no vuelve a correr. |
NOT_FOUND | 404 | El 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.
/actions/close_talent_icpBody
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| talentIcpId | string (uuid) | Sí | El perfil ideal. |
| closeReason | string | Sí | 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ódigo | HTTP | Cuándo |
|---|---|---|
NOTHING_TO_CHANGE | 409 | El perfil ya estaba cerrado. |
NOT_FOUND | 404 | El 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.
/actions/run_sourcingBody
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| jobPostId | string (uuid) | Sí | La vacante. |
| targetSize | integer | Opcional | Personas calificadas buscadas, de 1 a 2000. Default 150. No puede superar profileCap. |
| profileCap | integer | Opcional | Perfiles 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ódigo | HTTP | Cuándo |
|---|---|---|
INVALID | 400 | targetSize supera profileCap, o un valor está fuera de rango. |
JOB_POST_DRAFT | 409 | La vacante sigue en borrador: primero se activa desde su asistente de creación en la app. |
NO_SOURCING_CRITERIA | 409 | La vacante no tiene criterios de sourcing: no hay contra qué puntuar. Ver write_sourcing_criteria. |
NO_ICP | 409 | La vacante no tiene perfil ideal. Ver write_talent_icp. |
ICP_NEEDS_REVIEW | 409 | El perfil ideal es una propuesta que nadie aprobó. Ver update_talent_icp. |
NO_DEFINITIONS | 409 | No hay ninguna búsqueda activa. Se crean o aprueban desde la pantalla de sourcing (o con approveSearchIds). |
RUN_IN_PROGRESS | 409 | Ya hay una corrida abierta. Síguela, o ciérrala con cancel_sourcing. |
NOTHING_CHANGED | 409 | Nada cambió desde la última corrida. |
USAGE_WINDOW | 402 | Se alcanzó el límite de uso de las últimas cinco horas. |
USAGE_EXHAUSTED | 402 | Se terminó el uso de IA del mes. |
NOT_FOUND | 404 | La 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.
/actions/continue_sourcingBody
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| jobPostId | string (uuid) | Sí | La vacante. |
| longlistId | string (uuid) | Sí | La corrida (el longlistId de openRun o de run_sourcing). |
| autoStep | boolean | Opcional | Default 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;pausedReasondice por qué) oDONE(la longlist cerró;stopReasondice por qué).pausedReason/stopReason:COMPLETE(llegó al objetivo),PROFILE_CAP(llegó al tope de perfiles),LOW_PERFORMANCE,DROUGHToCANCELLED.lastPage: lo que hizo esta página: perfiles traídos, perfiles puntuados y su rendimiento.nullsi no se buscó nada.nextcambia según el estado: conPAUSEDsugierecontinue_sourcingycancel_sourcing; conDONE,get_longlist.
Errores
| Código | HTTP | Cuándo |
|---|---|---|
RUN_ALREADY_CLOSED | 409 | La corrida ya cerró. |
NO_SOURCING_CRITERIA | 409 | La vacante se quedó sin criterios de sourcing. |
NO_ICP | 409 | La vacante se quedó sin perfil ideal. |
USAGE_EXHAUSTED | 402 | Se terminó el uso de IA del mes. |
USAGE_WINDOW | 402 | Se alcanzó el límite de uso de las últimas cinco horas. |
NOT_FOUND | 404 | La 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.
/actions/cancel_sourcingBody
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| jobPostId | string (uuid) | Sí | La vacante. |
| longlistId | string (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ódigo | HTTP | Cuándo |
|---|---|---|
RUN_ALREADY_CLOSED | 409 | La corrida ya cerró. |
NOT_FOUND | 404 | La 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.
/actions/build_longlistBody
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| talentIcpId | string (uuid) | Sí | El perfil ideal. |
| targetSize | integer | Opcional | Tamaño máximo de la longlist, de 1 a 500. Default 150. |
| name | string | Opcional | Nombre 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ódigo | HTTP | Cuándo |
|---|---|---|
NOTHING_SCORED | 409 | Todavía no se puntuó a nadie. suggestions sugiere run_sourcing. |
NOT_FOUND | 404 | El perfil ideal no existe en el workspace. |