Reclee

Hacer sourcing de candidatos

Genera el ICP de talento y los criterios de una vacante, cotiza y arranca una corrida de sourcing, síguela hasta la longlist y haz búsquedas puntuales de talento.

El sourcing busca personas fuera de tu pool, las mide contra los criterios de la vacante y arma una longlist. Esta guía cubre la corrida completa (criterios, ICP, búsquedas aprobadas, cotización, arranque, seguimiento y longlist) y, al final, la búsqueda de talento puntual.

Esto consume uso y puede consumir créditos

Las corridas de sourcing y las búsquedas de talento llaman a un proveedor externo de datos y se cobran del uso de IA del mes; cuando el mes se agota, siguen con los créditos comprados del workspace. Las acciones que gastan devuelven cost con lo que gastó esa llamada, y billedLater: true cuando una parte se cobra después, mientras la corrida trabaja. Antes de arrancar, consulta GET /billing/usage-standing y lee Créditos y uso.

export RECLEE_API="https://app.reclee.com/api/v1"
export RECLEE_API_KEY="rcl_..."
export JOB_POST_ID="3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90"   # una vacante ACTIVE

La corrida de sourcing

Genera los criterios de sourcing

write_sourcing_criteria lee la vacante y escribe los criterios contra los que se mide a cada persona (hasta 10). Es una propuesta que la persona revisa en Reclee.

curl -s -X POST "$RECLEE_API/actions/write_sourcing_criteria" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90" }'
{
  "data": { "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90", "written": 6 },
  "links": [ … ],
  "next": { "missing": [], "suggestions": [ { "tool": "write_talent_icp", "input": { "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90" }, "readsFrom": ["PREVIOUS_STEPS"] } ] },
  "cost": { "aiUsagePct": 0.003, "teamUsagePct": 0, "credits": 0, "billedLater": false }
}

Los criterios se leen con GET /job-posts/{jobPostId}/criteria: un array de { id, title, description, position, required, weightPct }, ordenado por peso. required: true es un criterio eliminatorio.

Errores: 409 ALREADY_WRITTEN si la vacante ya tiene criterios, 409 JOB_POST_INCOMPLETE si le falta description o country, y 409 CRITERIA_FROZEN si hay una corrida abierta.

Genera el ICP de talento

write_talent_icp escribe el perfil ideal (títulos, seniority, skills, idiomas, dónde trabaja) y propone las búsquedas que lo van a encontrar. Las dos cosas nacen en NEEDS_REVIEW.

curl -s -X POST "$RECLEE_API/actions/write_talent_icp" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90" }'
{
  "data": {
    "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90",
    "talentIcpId": "4b6d8f0a-5c7e-4f9a-8b1d-3e5f7a9b1c29",
    "written": 1,
    "searchDefinitions": 3
  },
  "links": [ … ],
  "next": {
    "missing": [],
    "suggestions": [
      { "tool": "list_sourcing_searches", "input": { "talentIcpId": "4b6d8f0a-5c7e-4f9a-8b1d-3e5f7a9b1c29" } },
      { "tool": "update_talent_icp", "input": { "talentIcpId": "4b6d8f0a-5c7e-4f9a-8b1d-3e5f7a9b1c29" } }
    ]
  }
}

Guarda talentIcpId. searchDefinitions es cuántas búsquedas propuso. Si es 0, o si quieres sumar un ángulo que la propuesta no cubre, agrega una búsqueda con create_sourcing_search: queda activa enseguida, sin pasar por revisión.

Revisa y aprueba el ICP y sus búsquedas

Una corrida no arranca mientras el ICP esté en NEEDS_REVIEW, y solo corren las búsquedas aprobadas. Lee el ICP con GET /sourcing/talent-icps/{talentIcpId} y las búsquedas propuestas con:

curl -s "$RECLEE_API/sourcing/search-definitions?talentIcpId=4b6d8f0a-5c7e-4f9a-8b1d-3e5f7a9b1c29" \
  -H "Authorization: Bearer $RECLEE_API_KEY"
{
  "rows": [
    { "id": "5c7e9a1b-6d8f-4a0b-9c2e-4f6a8b0c2d3a", "talentIcpId": "4b6d8f0a-5c7e-4f9a-8b1d-3e5f7a9b1c29", "name": "Backend senior en fintech", "status": "NEEDS_REVIEW", "replacesId": null, "createdAt": "2026-10-22T15:00:00.000Z", "updatedAt": null }
  ],
  "total": 3,
  "page": 1,
  "pageSize": 50
}

(Extracto.) Cuando la persona las revisó, aprueba todo junto con update_talent_icp. En la misma llamada puedes corregir campos del ICP (titleVariants, skills, seniority…); una lista reemplaza la lista entera.

curl -s -X POST "$RECLEE_API/actions/update_talent_icp" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "talentIcpId": "4b6d8f0a-5c7e-4f9a-8b1d-3e5f7a9b1c29",
    "approve": true,
    "approveSearchIds": ["5c7e9a1b-6d8f-4a0b-9c2e-4f6a8b0c2d3a"]
  }'
{
  "data": { "talentIcpId": "4b6d8f0a-5c7e-4f9a-8b1d-3e5f7a9b1c29", "status": "ACTIVE", "version": 1, "approvedSearches": 1 },
  "links": [ … ],
  "next": { "missing": [], "suggestions": [ { "tool": "run_sourcing", "input": { "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90" } } ] }
}

Cuando next sugiere run_sourcing, todo está listo. Errores: 409 NOTHING_TO_CHANGE si el ICP no esperaba aprobación, 404 NOT_FOUND si un id no es una búsqueda propuesta de este ICP, 409 LIMIT_REACHED si el ICP ya tiene el máximo de búsquedas vivas.

Cotiza y verifica que se pueda arrancar

Dos lecturas que no gastan nada:

# Qué parte del uso del mes consumiría una corrida de hasta 500 perfiles
curl -s "$RECLEE_API/sourcing/runs/quote?profileCap=500" \
  -H "Authorization: Bearer $RECLEE_API_KEY"

# Si la vacante puede arrancar una corrida ahora
curl -s "$RECLEE_API/sourcing/runs/startable?jobPostId=$JOB_POST_ID" \
  -H "Authorization: Bearer $RECLEE_API_KEY"
{ "metered": true, "monthShare": 0.18, "leftShare": 0.42, "exceedsLeft": false, "creditCovers": true }

monthShare es la fracción del uso del mes (0 a 1, puede pasar de 1) que costaría la corrida; leftShare, lo que te queda. exceedsLeft: true avisa que no alcanza con lo que queda del mes, y creditCovers dice si los créditos comprados cubren la diferencia. Con metered: false las fracciones vienen en null.

startable devuelve { talentIcpId, icpName, definitions: [{ id, name }] } o la negativa que frenaría el arranque, en este orden: JOB_POST_DRAFT, NO_CRITERIA, NO_ICP, ICP_NEEDS_REVIEW, RUN_IN_PROGRESS, NO_DEFINITIONS, NOTHING_CHANGED (todas 409).

Arranca la corrida

run_sourcing abre la corrida. targetSize es cuántas personas calificadas buscas (default 150) y profileCap el máximo de perfiles a evaluar (default 500); targetSize no puede superar profileCap. Llamarla es la decisión de gastar: confirma con la persona antes.

curl -s -X POST "$RECLEE_API/actions/run_sourcing" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6d8f0b2c-7e9a-4b1c-8d3f-5a7b9c1d3e4b" \
  -d '{ "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90", "targetSize": 50, "profileCap": 300 }'
{
  "data": { "longlistId": "7e9a1c3d-8f0b-4c2d-9e4a-6b8c0d2e4f5c", "targetSize": 50, "profileCap": 300, "searchDefinitions": 1 },
  "links": [ { "kind": "longlist", "id": "7e9a1c3d-8f0b-4c2d-9e4a-6b8c0d2e4f5c", "label": "…", "href": "https://app.reclee.com/..." } ],
  "next": { "missing": [], "suggestions": [ { "tool": "get_talent_icp", "input": { "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90" } } ] },
  "cost": { "aiUsagePct": 0, "teamUsagePct": 0, "credits": 0, "billedLater": true }
}

longlistId es el id de la corrida y de su longlist: lo usan todos los pasos siguientes. El cost de esta llamada es casi cero porque abrir no busca nada; las páginas se cobran a medida que la corrida avanza (billedLater: true).

Errores: las mismas negativas de startable (con NO_SOURCING_CRITERIA en lugar de NO_CRITERIA), y 402 USAGE_WINDOW o USAGE_EXHAUSTED si no queda uso.

Sigue la corrida

La corrida avanza sola en el servidor, una página de perfiles cada pocos minutos. No tienes que empujarla: solo consultar su estado. Dos lecturas:

  • GET /sourcing/runs?talentIcpId=…: el estado en vivo de la corrida abierta del ICP (o null si no hay ninguna abierta).
  • GET /sourcing/longlists/{longlistId}: el resumen, que sigue existiendo cuando la corrida cierra.
curl -s "$RECLEE_API/sourcing/runs?talentIcpId=4b6d8f0a-5c7e-4f9a-8b1d-3e5f7a9b1c29" \
  -H "Authorization: Bearer $RECLEE_API_KEY"
{
  "longlistId": "7e9a1c3d-8f0b-4c2d-9e4a-6b8c0d2e4f5c",
  "status": "RUNNING",
  "stopReason": null,
  "pausedReason": null,
  "targetSize": 50,
  "profileCap": 300,
  "pagesRun": 3,
  "profilesEvaluated": 60,
  "qualified": 14,
  "stepping": true,
  "startedAt": "2026-10-22T15:10:00.000Z"
}

(Extracto.) status es RUNNING mientras hay trabajo, PAUSED cuando la corrida se detuvo esperando una decisión y DONE cuando cerró. Un ciclo de consulta razonable, cada un minuto:

while true; do
  STATUS=$(curl -s "$RECLEE_API/sourcing/longlists/7e9a1c3d-8f0b-4c2d-9e4a-6b8c0d2e4f5c" \
    -H "Authorization: Bearer $RECLEE_API_KEY" | jq -r '.status')
  echo "$STATUS"
  [ "$STATUS" != "OPEN" ] && break
  sleep 60
done

El resumen tiene status OPEN, CLOSED_COMPLETE o CLOSED_PARTIAL, y stopReason COMPLETE, PROFILE_CAP, LOW_PERFORMANCE, DROUGHT o CANCELLED.

Una corrida en pausa sigue OPEN

Cuando las búsquedas rinden poco, se secan o se llega a profileCap, la corrida pasa a PAUSED (en GET /sourcing/runs) y deja de avanzar sola, aunque el resumen siga OPEN. Ahí decide la persona: continue_sourcing con { jobPostId, longlistId } compra una página más y devuelve la corrida al servidor, y cancel_sourcing la cierra con lo que ya encontró (si todavía no puntuó a nadie o está evaluando una página, deja de traer páginas y contesta frozen: false: cancélala de nuevo más tarde para congelarla). Si el mes se queda sin uso, la corrida también se detiene.

Lee la longlist

Cuando la corrida cierra, Reclee congela la longlist y los calificados entran solos a la primera etapa del pipeline de la vacante. Las entradas se leen paginadas, en el orden en que se rankearon:

curl -s "$RECLEE_API/sourcing/longlists/7e9a1c3d-8f0b-4c2d-9e4a-6b8c0d2e4f5c/entries?page=1&pageSize=50" \
  -H "Authorization: Bearer $RECLEE_API_KEY"
{
  "rows": [
    {
      "rank": 1,
      "profileId": "8f0b2d4e-9a1c-4d3e-8f5b-7c9d1e3f5a6d",
      "firstName": "Tomás",
      "lastName": "Bianchi",
      "headline": "Staff Backend Engineer · Payments",
      "linkedinUrl": "https://www.linkedin.com/in/tomas-bianchi",
      "scorePct": 86,
      "coveragePct": 92,
      "company": "Kuanta",
      "city": "Córdoba",
      "verdict": "QUALIFIED",
      "disqualifiedReason": null
    }
  ],
  "total": 52,
  "page": 1,
  "pageSize": 50
}

(Extracto.) rank combina score y cobertura: respétalo en vez de reordenar por scorePct.

Pasa perfiles al pool o a la vacante

Para guardar personas en tu talent pool, save_to_pool con hasta 200 profileIds (data: { saved, already }). Para sumar a la vacante a alguien que quedó debajo del umbral, add_to_job_post:

curl -s -X POST "$RECLEE_API/actions/save_to_pool" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profileIds": ["8f0b2d4e-9a1c-4d3e-8f5b-7c9d1e3f5a6d"] }'

Para guardar toda la longlist en una lista, add_longlist_to_bookmark con { bookmarkId, jobPostId, longlistId }.

Búsqueda de talento puntual

Para encontrar personas sin armar una corrida, usa search_talent. Trae las primeras 20 personas que cumplen los filtros (title, skills, geoCountryCode en minúsculas, geoCity, experienceMinYears, speaksLanguage, industry…; listas de hasta 20). Cada página gasta uso: la búsqueda en sí y el enriquecimiento de las personas que tu workspace todavía no pagó.

Busca

curl -s -X POST "$RECLEE_API/actions/search_talent" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Backend Engineer",
    "skills": ["Go", "PostgreSQL"],
    "geoCountryCode": "ar",
    "experienceMinYears": 5
  }'
{
  "data": {
    "searchId": "9a1c3e5f-0b2d-4e4f-9a6c-8d0e2f4a6b7e",
    "name": "Search 4",
    "hasMore": true,
    "people": [
      {
        "profileId": "0b2d4f6a-1c3e-4f5a-8b7d-9e1f3a5b7c8f",
        "name": "Valentina Ruiz",
        "headline": "Senior Backend Engineer",
        "currentTitle": "Senior Backend Engineer",
        "currentCompany": "Nubo",
        "location": "Rosario, Argentina",
        "doNotContact": false,
        "inPool": false,
        "experience": [{ "title": "Senior Backend Engineer", "company": "Nubo", "from": 2022, "to": null }],
        "skills": ["Go", "PostgreSQL", "Kubernetes"]
      }
    ]
  },
  "links": [ … ],
  "cost": { "aiUsagePct": 0.011, "teamUsagePct": 0, "credits": 0, "billedLater": false }
}

(Extracto.) Si no estás seguro de los filtros, search_talent_preview muestra una vista previa más barata: cuesta una búsqueda, no enriquece a nadie y no guarda a nadie.

Trae más resultados

Con el searchId, load_more_talent trae la página siguiente. people trae solo las personas nuevas y peopleSoFar el total acumulado.

curl -s -X POST "$RECLEE_API/actions/load_more_talent" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "searchId": "9a1c3e5f-0b2d-4e4f-9a6c-8d0e2f4a6b7e" }'

Con hasMore: false, una llamada más contesta 409 NO_MORE_RESULTS sin gastar. Mientras una página está en curso, 409 PAGE_IN_FLIGHT. La búsqueda completa, con todas sus páginas, se lee gratis con GET /talent/searches/{searchId}.

Guarda y suma a la vacante

Las personas de una búsqueda llegan con inPool: false. Guárdalas con save_to_pool y después súmalas con add_to_job_post, como en Gestionar el pipeline.

Errores de gasto que vas a ver

CódigoStatusQué significa
USAGE_WINDOW / TEAM_WINDOW402Se alcanzó el límite de uso de las últimas cinco horas; vuelve más tarde (resetsAt).
USAGE_EXHAUSTED / TEAM_USAGE_EXHAUSTED402Se agotó el uso del mes y no hay créditos comprados que lo cubran.
INSUFFICIENT_CREDITS503El proveedor de datos no está disponible para tu cuenta en este momento; avísale a quien administra Reclee.
PROVIDER_UNAVAILABLE503El proveedor de datos no responde; reintenta más tarde.

Un 402 trae además limit, usedPct, unlockedBy y billingUrl. Ver Errores.

Siguientes pasos

En esta página