Reclee

CRM: del lead al placement

Registra una empresa y sus contactos, anota la actividad, avánzala en el embudo comercial, crea el request, vincúlalo a una vacante y registra la contratación.

Esta guía sigue a un cliente desde que es un lead hasta que se cierra un placement: creas la empresa y sus contactos, anotas la actividad comercial, la mueves por el embudo, registras el request (el pedido de búsqueda), creas la vacante vinculada y contratas al candidato.

export RECLEE_API="https://app.reclee.com/api/v1"
export RECLEE_API_KEY="rcl_..."

Sobre `next` en el CRM

Las acciones del CRM devuelven data y links, pero no next: el orden de esta guía es el que conecta un paso con el siguiente.

Crea la empresa (lead)

create_lead crea la empresa en la primera etapa del embudo. Solo name es obligatorio. Las condiciones comerciales por defecto (defaultFeeType, defaultFeePct, defaultCurrencyCode, defaultGuaranteeDays) las heredan después sus requests y placements; si no las mandas, se toman las del workspace.

curl -s -X POST "$RECLEE_API/actions/create_lead" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8a0c2e4f-9b1d-4f3a-8c5e-7d9f1b3d5f6a" \
  -d '{
    "name": "Lumina Pagos",
    "website": "https://luminapagos.example",
    "country": "AR",
    "source": "REFERRAL",
    "defaultFeeType": "PERCENTAGE",
    "defaultFeePct": 18,
    "defaultCurrencyCode": "USD"
  }'
{
  "data": { "leadId": "9b1d3f5a-0c2e-4a4b-9d6f-8e0a2c4e6a7b" },
  "links": [ { "kind": "lead", "id": "9b1d3f5a-0c2e-4a4b-9d6f-8e0a2c4e6a7b", "label": "Lumina Pagos", "href": "https://app.reclee.com/..." } ]
}

La empresa ya existe

Si ya hay una empresa con el mismo sitio web o el mismo nombre, la acción contesta 409 LEAD_EXISTS. Para obtener su id, búscala con GET /crm/leads?search=Lumina, o crea la empresa con POST /crm/leads, cuyo 409 trae existing: { id, name }.

Agrega los contactos

create_contact agrega una persona de la empresa. El primer contacto queda como principal; isPrimary: true en otro le pasa ese rol.

curl -s -X POST "$RECLEE_API/actions/create_contact" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leadId": "9b1d3f5a-0c2e-4a4b-9d6f-8e0a2c4e6a7b",
    "firstName": "Carla",
    "lastName": "Méndez",
    "title": "Head of Engineering",
    "email": "carla.mendez@luminapagos.example",
    "isDecisionMaker": true
  }'
{ "data": { "contactId": "0c2e4a6b-1d3f-4b5c-8e7a-9f1b3d5f7b8c" }, "links": [ … ] }

Anota la actividad

log_lead_activity registra una llamada, un email, una reunión o una nota (kind: CALL, EMAIL, MEETING, NOTE). contactId tiene que ser de la misma empresa y occurredAt es ahora si no lo mandas.

curl -s -X POST "$RECLEE_API/actions/log_lead_activity" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leadId": "9b1d3f5a-0c2e-4a4b-9d6f-8e0a2c4e6a7b",
    "kind": "CALL",
    "contactId": "0c2e4a6b-1d3f-4b5c-8e7a-9f1b3d5f7b8c",
    "body": "Necesitan dos backend senior antes de fin de año. Pidieron propuesta."
  }'
{ "data": { "activityId": "1d3f5b7c-2e4a-4c6d-9f8b-0a2c4e6a8c9d" }, "links": [ … ] }

La historia de la empresa se lee paginada con GET /crm/leads/{leadId}/activity; los cambios de etapa aparecen ahí solos, con kind: "MOVE".

Avanza la empresa en el embudo

El embudo comercial tiene cuatro etapas fijas. Léelas con GET /crm/stages:

curl -s "$RECLEE_API/crm/stages" -H "Authorization: Bearer $RECLEE_API_KEY"
[
  { "id": "2e4a6c8d-3f5b-4d7e-8a9c-1b3d5f7a9d0e", "key": "PROSPECTING", "label": "Prospect", "position": 1, "outcome": "OPEN", "isLocked": false },
  { "id": "3f5b7d9e-4a6c-4e8f-9b0d-2c4e6a8b0e1f", "key": "QUALIFIED", "label": "Qualified", "position": 2, "outcome": "OPEN", "isLocked": false },
  { "id": "4a6c8e0f-5b7d-4f9a-8c1e-3d5f7b9c1f2a", "key": "MEETING", "label": "Meeting", "position": 3, "outcome": "OPEN", "isLocked": false },
  { "id": "5b7d9f1a-6c8e-4a0b-9d2f-4e6a8c0d2a3b", "key": "CLIENT", "label": "Client", "position": 4, "outcome": "WON", "isLocked": true }
]

(Extracto.) move_lead_stage recibe el id de la etapa, no su key:

curl -s -X POST "$RECLEE_API/actions/move_lead_stage" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leadId": "9b1d3f5a-0c2e-4a4b-9d6f-8e0a2c4e6a7b",
    "stageId": "4a6c8e0f-5b7d-4f9a-8c1e-3d5f7b9c1f2a"
  }'
{ "data": { "leadId": "9b1d3f5a-0c2e-4a4b-9d6f-8e0a2c4e6a7b", "stageId": "4a6c8e0f-5b7d-4f9a-8c1e-3d5f7b9c1f2a" }, "links": [ … ] }

Errores en este paso

  • 409 STAGE_ONLY_ADVANCES: el embudo solo avanza, no retrocede.
  • 409 CLIENT_IS_DERIVED: a CLIENT no se mueve a mano. La empresa pasa sola a cliente cuando uno de sus requests entra en IN_PROGRESS (paso 6).

Crea el request

Un request es el pedido de búsqueda del cliente. create_request recibe el id de la empresa en clientId (es el mismo leadId). Si no mandas feeType, feePct ni feeAmount, hereda el fee de la empresa. El request nace en DRAFT.

curl -s -X POST "$RECLEE_API/actions/create_request" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "9b1d3f5a-0c2e-4a4b-9d6f-8e0a2c4e6a7b",
    "title": "Backend senior x2",
    "roleTitle": "Senior Backend Engineer",
    "positionsCount": 2,
    "salaryMin": 4000,
    "salaryMax": 5500,
    "currencyCode": "USD",
    "salaryPeriod": "MONTHLY",
    "hiringManagerId": "0c2e4a6b-1d3f-4b5c-8e7a-9f1b3d5f7b8c"
  }'
{
  "data": { "requestId": "6c8e0a2b-7d9f-4b1c-8e3a-5f7b9d1e3b4c" },
  "links": [ { "kind": "request", "id": "6c8e0a2b-7d9f-4b1c-8e3a-5f7b9d1e3b4c", "label": "Backend senior x2", "href": "https://app.reclee.com/..." } ]
}

hiringManagerId es un contacto de la misma empresa. Errores: 409 COMPANY_ARCHIVED si la empresa está archivada.

Crea la vacante vinculada y arranca el request

create_job_post con requestId crea la vacante ya vinculada: lo que no mandes se toma del request (openings de positionsCount, el rango salarial con su moneda y período, la descripción) y el país, de la empresa.

curl -s -X POST "$RECLEE_API/actions/create_job_post" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Backend Engineer",
    "requestId": "6c8e0a2b-7d9f-4b1c-8e3a-5f7b9d1e3b4c",
    "description": "Liderar el diseño de la plataforma de pagos de Lumina."
  }'
{
  "data": { "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90" },
  "links": [ … ],
  "next": { "missing": ["seniority", "employmentType", "workplaceType"], "suggestions": [ { "tool": "update_job_post", "input": { "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90" } } ] }
}

Si la vacante ya existía, vincúlala con link_request_to_job_post ({ jobPostId, requestId }). Un request respalda una sola vacante y una vacante tiene un solo request: 409 REQUEST_ALREADY_LINKED o 409 JOB_POST_ALREADY_LINKED.

Completa y publica la vacante como en Publicar una vacante. Después, avanza el request con set_request_status: SENT cuando mandaste la propuesta e IN_PROGRESS cuando el cliente la aceptó.

curl -s -X POST "$RECLEE_API/actions/set_request_status" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "requestId": "6c8e0a2b-7d9f-4b1c-8e3a-5f7b9d1e3b4c", "status": "IN_PROGRESS" }'
{ "data": { "requestId": "6c8e0a2b-7d9f-4b1c-8e3a-5f7b9d1e3b4c", "status": "IN_PROGRESS" }, "links": [ … ] }

Qué hace cada estado del request sobre la vacante vinculada (una vacante en borrador nunca se toca):

Estado del requestEfecto
DRAFTNinguno. DRAFT y SENT se alternan a mano.
SENT / IN_PROGRESSLa vacante pasa a ACTIVE. Con IN_PROGRESS, la empresa pasa a cliente.
CLOSED / CANCELLEDLa vacante se cierra. CANCELLED siempre pide closeReason; CLOSED lo pide si no se cubrieron las posiciones.

Errores: 409 REQUEST_ALREADY_ENDED (nada sale de CLOSED o CANCELLED), 409 REQUEST_ALREADY_STARTED (de IN_PROGRESS no se vuelve a DRAFT o SENT) y 409 REQUEST_NOT_STARTED (no se cierra un request que nunca estuvo en curso).

Contrata al candidato

Lleva al candidato por el pipeline como en Gestionar el pipeline. Se contrata desde la etapa anterior a la última (la shortlist), moviéndolo a la última con move_application_stage y los términos en hire: salary y startDate son obligatorios; moneda, período y fee se heredan de la vacante y del cliente si no los mandas.

curl -s -X POST "$RECLEE_API/actions/move_application_stage" \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d9f1b3c-8e0a-4c2d-9f4b-6a8c0e2f4c5d" \
  -d '{
    "applicationId": "8c0e2a4b-9d1f-4a3b-8c5e-7f9a1b3c5d74",
    "stageId": "e5a7c9d1-5f6b-4c0d-8e3f-4a5b6c7d8e95",
    "hire": { "salary": 5200, "startDate": "2026-12-01" }
  }'
{ "data": { "stage": "HIRED" }, "links": [ … ] }

Errores en este paso

  • 400 HIRE_TERMS_REQUIRED: moviste a la última etapa sin hire. Trae missing: ["salary", "startDate"].
  • 400 PAY_TERMS_REQUIRED: ni la llamada ni la vacante dicen la moneda o el período; mándalos en hire.
  • 409 SHORTLIST_FIRST: el candidato no está en la etapa anterior a la última.
  • 409 REPORT_REQUIRED: para entrar a la shortlist el candidato necesita un informe.
  • 409 ALREADY_HIRED: ya tiene placement. 409 HIRED_IS_FINAL: una contratación no se deshace moviendo de etapa.

La alternativa REST es POST /ats/applications/{applicationId}/hire con el mismo cuerpo de hire; responde la postulación.

Revisa el placement

La contratación crea un placement con el fee y la garantía. Léelos desde el request:

curl -s "$RECLEE_API/crm/requests/6c8e0a2b-7d9f-4b1c-8e3a-5f7b9d1e3b4c/placements" \
  -H "Authorization: Bearer $RECLEE_API_KEY"
[
  {
    "placement": {
      "id": "8e0a2c4d-9f1b-4d3e-8a5c-7b9d1f3a5d6e",
      "type": "HIRE",
      "salary": 5200,
      "currencyCode": "USD",
      "salaryPeriod": "MONTHLY",
      "feeType": "PERCENTAGE",
      "feePct": 18,
      "feeAmount": null,
      "startDate": "2026-12-01",
      "guaranteeDays": 90,
      "guaranteeEndsAt": "2027-03-01",
      "billingStatus": "PENDING"
    },
    "applicationId": "8c0e2a4b-9d1f-4a3b-8c5e-7f9a1b3c5d74",
    "profileId": "6a8c0e2f-7b9d-4e1f-8a3c-5d7e9f1a3b52",
    "jobPostId": "3f6c2a9e-8b1d-4c7a-9e2f-5d4b1a7c8e90",
    "personName": "Martina Ocampo",
    "awaitingReplacement": false
  }
]

(Extracto.) Para corregir el fee o marcar la facturación, PATCH /crm/requests/{requestId}/placements/{placementId} (por ejemplo { "billingStatus": "INVOICED" }).

Cuando las contrataciones de un request IN_PROGRESS llegan a positionsCount, el request pasa solo a CLOSED y cierra la vacante vinculada. Si la persona se va dentro de la garantía, activate_guarantee reabre la búsqueda y la próxima contratación es un reemplazo sin fee.

Archivar en vez de borrar

Una API key no borra nada del CRM: una empresa, un request o un contacto se archivan con archive_lead, archive_request o archive_contact (archived: true, o false para restaurar). Archivar una empresa archiva también sus requests abiertos. Un DELETE sobre esos recursos contesta 405 DELETE_NOT_ALLOWED con la acción que corresponde en suggestions. Ver Borrados.

Siguientes pasos

En esta página