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: aCLIENTno se mueve a mano. La empresa pasa sola a cliente cuando uno de sus requests entra enIN_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 request | Efecto |
|---|---|
DRAFT | Ninguno. DRAFT y SENT se alternan a mano. |
SENT / IN_PROGRESS | La vacante pasa a ACTIVE. Con IN_PROGRESS, la empresa pasa a cliente. |
CLOSED / CANCELLED | La 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 sinhire. Traemissing: ["salary", "startDate"].400 PAY_TERMS_REQUIRED: ni la llamada ni la vacante dicen la moneda o el período; mándalos enhire.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.