Reclee

Publicar una vacante

Crea una vacante como borrador, complétala, genera sus criterios, ajusta sus etapas, publícala y compártela.

Esta guía lleva una vacante desde cero hasta publicada: la creas como borrador, completas lo que next dice que falta, generas los criterios de evaluación y de screening, ajustas las etapas del pipeline, la publicas y creas el link para el cliente.

Todos los ejemplos usan estas variables:

export RECLEE_API="https://app.reclee.com/api/v1"
export RECLEE_API_KEY="rcl_..."   # tu API key (Configuración → Developers)

Crea el borrador

create_job_post crea la vacante en estado DRAFT. Solo title es obligatorio, pero cuanto más completes ahora, menos pasos quedan. Un salario (salaryMin o salaryMax) necesita su salaryPeriod.

curl -s -X POST "$RECLEE_API/actions/create_job_post" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b7e9c52-2f61-4a8d-9e3c-5a1f7d2b6c40" \
  -d '{
    "title": "Senior Backend Engineer",
    "description": "Buscamos una persona para liderar el diseño de nuestra plataforma de pagos.",
    "country": "AR",
    "employmentType": "FULL_TIME",
    "salaryMin": 4000,
    "salaryMax": 5500,
    "currencyCode": "USD",
    "salaryPeriod": "MONTHLY",
    "requirements": ["5+ años con Node.js o Go", "Experiencia con PostgreSQL"]
  }'

La respuesta trae solo el id en data; lo demás está en next:

{
  "data": { "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90" },
  "links": [
    {
      "kind": "job_post",
      "id": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90",
      "label": "Senior Backend Engineer",
      "href": "https://app.reclee.com/..."
    }
  ],
  "next": {
    "missing": ["seniority", "workplaceType"],
    "suggestions": [
      { "tool": "update_job_post", "input": { "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90" } },
      { "tool": "write_talent_icp", "input": { "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90" }, "readsFrom": ["PREVIOUS_STEPS"] },
      { "tool": "write_sourcing_criteria", "input": { "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90" }, "readsFrom": ["PREVIOUS_STEPS"] },
      { "tool": "write_screening_criteria", "input": { "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90" }, "readsFrom": ["PREVIOUS_STEPS"] }
    ]
  }
}

Guarda data.jobPostId: es el id que usan todos los pasos siguientes. Si pasas requestId (un request del CRM), los campos que no mandes se toman del request; ver CRM: del lead al placement.

Lee next.missing y completa la vacante

next.missing es la lista exacta de lo que falta para poder publicar. Para publicar se necesitan description, seniority, employmentType, workplaceType y country, y además city cuando workplaceType es HYBRID u ON_SITE. El salario, los criterios y las etapas no son obligatorios.

Completa lo que falta con update_job_post:

curl -s -X POST "$RECLEE_API/actions/update_job_post" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90",
    "seniority": "MID_SENIOR_LEVEL",
    "workplaceType": "HYBRID",
    "city": "Buenos Aires"
  }'
{
  "data": { "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90", "careerSite": "ON_ACTIVATION" },
  "links": [ { "kind": "job_post", "id": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90", "label": "Senior Backend Engineer", "href": "https://app.reclee.com/..." } ],
  "next": { "missing": [], "suggestions": [] }
}

Con missing vacío, la vacante ya se puede publicar. careerSite dice dónde está la vacante en tu sitio de empleo: VISIBLE (se ve ahora, y cualquier edición es pública en el momento en que se guarda), ON_ACTIVATION (un borrador marcado para publicarse, que se hace público al activarlo) o HIDDEN.

Errores en este paso

  • 400 INVALID con details campo por campo: por ejemplo, un salario sin salaryPeriod o un salaryMin mayor que salaryMax.
  • 404 NOT_FOUND: el jobPostId no existe en tu workspace.

Genera los criterios de evaluación y de screening

Dos acciones de la familia GENERATE leen la vacante y escriben una propuesta que la persona revisa en Reclee:

curl -s -X POST "$RECLEE_API/actions/write_evaluation_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": [ { "kind": "job_post", "id": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90", "label": "Senior Backend Engineer", "href": "https://app.reclee.com/..." } ],
  "next": { "missing": [], "suggestions": [ { "tool": "write_screening_criteria", "input": { "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90" }, "readsFrom": ["PREVIOUS_STEPS"] } ] },
  "cost": { "aiUsagePct": 0.004, "teamUsagePct": 0, "credits": 0, "billedLater": false }
}

written es cuántos criterios escribió; el contenido no vuelve en la respuesta. Para leerlo:

curl -s "$RECLEE_API/job-posts/3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90/evaluation-criteria" \
  -H "Authorization: Bearer $RECLEE_API_KEY"
[
  { "id": "9d2b7e41-6c3a-4f58-8a1e-2b7c9d0e1f23", "name": "Diseño de sistemas distribuidos", "description": "…", "weightLevel": "HIGH", "position": 1 }
]

Después llama a write_screening_criteria con el mismo cuerpo y lee el resultado en GET /job-posts/{jobPostId}/screening-questions.

Errores en este paso

  • 409 JOB_POST_INCOMPLETE: la vacante no tiene description o country. Trae missing y sugiere update_job_post.
  • 409 ALREADY_WRITTEN: la vacante ya tiene criterios (o preguntas). Estas acciones solo escriben sobre una lista vacía; para editar una lista existente usa PUT /job-posts/{jobPostId}/evaluation-criteria o PUT /job-posts/{jobPostId}/screening-questions.
  • 402 USAGE_WINDOW, TEAM_WINDOW, USAGE_EXHAUSTED o TEAM_USAGE_EXHAUSTED: se agotó el uso de IA. Ver Créditos y uso.

Ajusta las etapas del pipeline

Toda vacante nace con cinco etapas. Su name es null hasta que alguien las renombra, así que identifícalas por templateKey: SOURCED, SCREENING, INTERVIEW, SHORTLIST y HIRED. Las dos primeras y las dos últimas están bloqueadas (isLocked: true): no se renombran. Los ids salen de GET /job-posts/{jobPostId}/pipeline:

curl -s "$RECLEE_API/job-posts/3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90/pipeline" \
  -H "Authorization: Bearer $RECLEE_API_KEY"
{
  "stages": [
    { "id": "a1c3e5f7-1b2d-4e6f-8a9b-0c1d2e3f4a51", "name": null, "templateKey": "SOURCED", "position": 1, "isLocked": true, "qualified": 0, "disqualified": 0, "withdrawn": 0 },
    { "id": "b2d4f6a8-2c3e-4f7a-9b0c-1d2e3f4a5b62", "name": null, "templateKey": "SCREENING", "position": 2, "isLocked": true, "qualified": 0, "disqualified": 0, "withdrawn": 0 },
    { "id": "c3e5a7b9-3d4f-4a8b-8c1d-2e3f4a5b6c73", "name": null, "templateKey": "INTERVIEW", "position": 3, "isLocked": false, "qualified": 0, "disqualified": 0, "withdrawn": 0 },
    { "id": "d4f6b8c0-4e5a-4b9c-9d2e-3f4a5b6c7d84", "name": null, "templateKey": "SHORTLIST", "position": 4, "isLocked": true, "qualified": 0, "disqualified": 0, "withdrawn": 0 },
    { "id": "e5a7c9d1-5f6b-4c0d-8e3f-4a5b6c7d8e95", "name": null, "templateKey": "HIRED", "position": 5, "isLocked": true, "qualified": 0, "disqualified": 0, "withdrawn": 0 }
  ],
  "candidates": [],
  "activeRun": null,
  "openGuaranteePlacementId": null
}

(Extracto.) set_pipeline_stages recibe el embudo completo, en orden. Aquí renombramos la etapa de entrevista y agregamos una nueva (sin id, con name) antes de la shortlist:

curl -s -X POST "$RECLEE_API/actions/set_pipeline_stages" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90",
    "stages": [
      { "id": "a1c3e5f7-1b2d-4e6f-8a9b-0c1d2e3f4a51" },
      { "id": "b2d4f6a8-2c3e-4f7a-9b0c-1d2e3f4a5b62" },
      { "id": "c3e5a7b9-3d4f-4a8b-8c1d-2e3f4a5b6c73", "name": "Entrevista técnica" },
      { "name": "Entrevista con el cliente" },
      { "id": "d4f6b8c0-4e5a-4b9c-9d2e-3f4a5b6c7d84" },
      { "id": "e5a7c9d1-5f6b-4c0d-8e3f-4a5b6c7d8e95" }
    ]
  }'
{
  "data": { "stages": ["SOURCED", "SCREENING", "Entrevista técnica", "Entrevista con el cliente", "SHORTLIST", "HIRED"] },
  "links": [ { "kind": "job_post", "id": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90", "label": "Senior Backend Engineer", "href": "https://app.reclee.com/..." } ]
}

Errores en este paso

  • 409 STAGE_REMOVAL_NOT_ALLOWED: dejaste afuera una etapa existente. La API nunca borra etapas; se borran desde la app.
  • 400 INVALID: intentaste renombrar una etapa bloqueada, o una etapa nueva no trae name. El embudo tiene entre 3 y 12 etapas.
  • 409 PIPELINE_CHANGED: alguien cambió el embudo mientras tanto. Vuelve a leer /pipeline y manda el array completo otra vez.

Publica la vacante

No hay acción para publicar: se publica con PUT /job-posts/{jobPostId}/status y status: "ACTIVE". Si falta algún campo obligatorio, la vacante sigue en borrador y la respuesta dice cuál.

curl -s -X PUT "$RECLEE_API/job-posts/3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90/status" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "ACTIVE" }'

La respuesta es la vacante completa, la misma forma que GET /job-posts/{jobPostId} (extracto):

{
  "id": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90",
  "title": "Senior Backend Engineer",
  "status": "ACTIVE",
  "seniority": "MID_SENIOR_LEVEL",
  "workplaceType": "HYBRID",
  "country": "AR",
  "city": "Buenos Aires",
  "openings": 1,
  "publishToCareerSite": true,
  "handle": "k3m9qa",
  "draftStep": "…"
}

Si falta algo, la respuesta es 422 con la lista:

{ "error": "PUBLISH_INCOMPLETE", "missing": ["city"] }

Mientras la vacante es borrador

Las acciones sobre candidatos (add_to_job_post, move_application_stage…) contestan 409 JOB_POST_DRAFT con missing. Publica primero.

Comparte la vacante con el cliente

create_job_post_share crea un link que el cliente abre sin cuenta. scope: "SHORTLIST" (el default) muestra los candidatos en shortlist con sus informes; FULL muestra todo el pipeline. showContact revela email y teléfono de los candidatos: déjalo en false salvo que la persona lo pida.

curl -s -X POST "$RECLEE_API/actions/create_job_post_share" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90",
    "scope": "SHORTLIST",
    "label": "Link para Lumina Pagos",
    "expiresAt": "2026-12-31T23:59:59Z"
  }'
{
  "data": {
    "shareId": "f6b8d0e2-6a7c-4d1e-9f4a-5b6c7d8e9fa6",
    "scope": "SHORTLIST",
    "showContact": false,
    "expiresAt": "2026-12-31T23:59:59+00:00",
    "sharePath": "/public-shortlist/…"
  },
  "links": [ … ],
  "next": { "missing": [], "suggestions": [ { "tool": "revoke_job_post_share", "input": { "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90", "shareId": "f6b8d0e2-6a7c-4d1e-9f4a-5b6c7d8e9fa6" } } ] }
}

sharePath es una ruta sobre https://app.reclee.com: la URL que mandas al cliente es https://app.reclee.com + sharePath. Los links de una vacante se listan con GET /job-posts/{jobPostId}/shares.

Un solo link de shortlist vivo

Una vacante tiene un único link SHORTLIST activo. Pedir otro contesta 409 SHORTLIST_LINK_ACTIVE y sugiere revoke_job_post_share con el shareId del link vivo. Un link revocado no se reactiva: se crea uno nuevo.

Comprueba que esté en el career site

Una vacante publicada aparece sola en tu career site si su publishToCareerSite es true (el valor por defecto). Esa opción, igual que showSalary y showClient, se decide en la pantalla de la vacante en la app: update_job_post no la cambia, y mandarla en PATCH /job-posts/{jobPostId} contesta 400.

Para ver qué publica tu career site, usa el slug de tu workspace (está en GET /careers/settings):

curl -s "$RECLEE_API/careers/job-posts?slug=lumina&limit=20" \
  -H "Authorization: Bearer $RECLEE_API_KEY"
{
  "jobPosts": [
    {
      "slug": "k3m9qa",
      "title": "Senior Backend Engineer",
      "paused": false,
      "city": "Buenos Aires",
      "country": "AR",
      "workplaceType": "HYBRID",
      "employmentType": "FULL_TIME",
      "seniority": "MID_SENIOR_LEVEL",
      "salary": null,
      "openedAt": "2026-10-22T14:05:00.000Z",
      "contentLocale": "es"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

(Extracto.) El slug de cada vacante es su handle; la página pública de la vacante vive en el subdominio de tu career site, en /jobs/<handle>.

Cerrar o reabrir

  • Cerrar: close_job_post o PUT /job-posts/{jobPostId}/status con status: "CLOSED". Si las contrataciones no cubren las vacantes abiertas (openings), pide closeReason (422 CLOSE_REASON_REQUIRED).
  • Reabrir: reopen_job_post. Un borrador contesta 409 DRAFT_CANNOT_REOPEN: nunca se publicó.
  • Borrar: solo un borrador sin candidatos ni corridas, con delete_draft_job_post. Cualquier otra vacante se cierra.

Siguientes pasos

En esta página