Reclee

Pedidos y respuestas

Headers, cuerpos JSON, formatos de ids y fechas, tamaños máximos, archivos y la forma de una respuesta exitosa.

Esta página reúne las reglas de forma que valen para todas las rutas de /api/v1: qué mandar, en qué formato, y qué esperar de vuelta.

Headers del pedido

HeaderCuándoValor
AuthorizationSiempre (salvo GET /openapi.json)Bearer rcl_…
Content-TypeCuando mandas un cuerpoapplication/json (o multipart/form-data en las rutas de archivos)
Idempotency-KeyOpcional, en las acciones y en los POST que crean o gastan. Solo REST: el servidor MCP no lo acepta.De 1 a 255 caracteres ASCII visibles; un UUID es lo habitual. Ver Idempotencia.

No hace falta mandar Accept: toda respuesta es JSON, salvo las exportaciones a CSV.

El cuerpo

  • JSON, un objeto. Las rutas que leen un cuerpo aceptan Content-Type: application/json, cualquier tipo +json, text/plain o ningún Content-Type (como manda fetch un string). Un cuerpo que dice ser otra cosa, como un formulario, contesta 415 UNSUPPORTED_MEDIA_TYPE.
  • JSON mal formado contesta 400 INVALID_JSON.
  • Validación contra el esquema. Cada cuerpo se valida contra su esquema: un campo obligatorio ausente, un tipo equivocado o un valor fuera de rango contesta 400 INVALID con details, campo por campo. Ver Errores. No mandes campos que el esquema no lista: en las acciones (POST /actions/<tool>) un campo desconocido se rechaza con 400 INVALID y details nombra la clave sobrante.
  • Cuerpo opcional. En las acciones sin campos obligatorios puedes no mandar cuerpo: se lee como {}. Si mandas uno, tiene que pasar la validación.
  • null y ausente no son lo mismo. En una edición, un campo ausente no se toca y un campo en null se vacía (cuando el esquema lo permite).

La query

Los filtros y la paginación van en la query. En las rutas que aceptan filtros, la query se valida de forma estricta: un parámetro que la ruta no conoce contesta 400 INVALID en vez de ignorarse, para que un filtro mal escrito no te devuelva la lista entera como si nada.

curl "https://app.reclee.com/api/v1/job-posts?estado=ACTIVE" -H "Authorization: Bearer $RECLEE_API_KEY"
# 400 { "error": "INVALID", "details": { "errors": ["Unrecognized key: \"estado\""] } }

Los números de la query (page, pageSize, umbrales) se mandan como texto y se convierten.

Tamaño máximo

QuéLímiteSi se pasa
Cuerpo JSON de una ruta REST (incluidas las acciones)1 MB, salvo que la ruta diga otro413 PAYLOAD_TOO_LARGE
Cualquier pedido REST, incluido un archivo4,5 MB, el tope de la plataforma413 PAYLOAD_TOO_LARGE
Archivos de las rutas multipartEl de cada ruta (ver abajo)413 TOO_LARGE o 413 PAYLOAD_TOO_LARGE
Un mensaje al servidor MCP (POST /api/mcp)4 MB413 con un error JSON-RPC (-32000)

El tope de 1 MB se mira primero por el header Content-Length, antes de leer el cuerpo, y después sobre el cuerpo leído. Ningún campo de la API se acerca a ese límite. Los archivos grandes (CVs, adjuntos) no viajan por la API: se suben directo con una URL firmada (ver abajo).

Formatos

Tipo de datoFormatoEjemplo
IdsUUID en texto"3f8a2b6c-1d4e-4a7b-9c2d-8e5f6a7b8c9d"
Fecha y horaISO 8601 con zona horaria, en UTC"2026-10-06T13:12:44.512+00:00"
Fecha solaYYYY-MM-DD"2026-11-03" (targetStartDate, leftAt)
EnumsTexto en mayúsculas"ACTIVE", "MID_SENIOR_LEVEL"
PaísISO 3166-1 alfa-2, en mayúsculas (los filtros de búsqueda de talento lo piden en minúsculas)"AR"
MonedaISO 4217"USD"
Idiomaes o en"es"
MontosNúmero85000

Cuando mandas una fecha y hora, usa ISO 8601 con zona (2026-11-03T15:00:00-03:00 o …Z).

Los porcentajes no tienen una escala única: los de uso (aiUsagePct, usedPct, teamUsagePct) van de 0 a 1, y los de match score (scorePct, coveragePct) de 0 a 100. Cada campo lo dice en su descripción.

Respuestas exitosas

  • 200 con el dato en JSON, sin envoltorio: un recurso es el objeto, una lista paginada es { rows, total, page, pageSize }, una acción es { data, links, next?, cost? }.
  • 204 sin cuerpo en algunos DELETE que desvinculan (sacar una etiqueta, un tag, un miembro del equipo de una vacante).
  • CSV en las exportaciones (GET /sourcing/longlists/{longlistId}/export, GET /talent/pool/export), con Content-Type: text/csv y Content-Disposition: attachment.
// GET /job-posts/3f8a2b6c-1d4e-4a7b-9c2d-8e5f6a7b8c9d (extracto)
{
  "id": "3f8a2b6c-1d4e-4a7b-9c2d-8e5f6a7b8c9d",
  "title": "Senior Backend Engineer",
  "status": "ACTIVE",
  "workplaceType": "REMOTE",
  "salaryMin": 4000,
  "salaryMax": 5500,
  "currencyCode": "USD",
  "salaryPeriod": "MONTHLY",
  "openings": 1,
  "createdAt": "2026-10-02T18:40:09.031+00:00"
}

Los errores, en cambio, siempre traen { "error": "CODE" }. Ver Errores.

Headers de la respuesta

HeaderCuándoPara qué
X-Request-IdSiempreIdentifica el pedido. Cítalo si reportas un problema.
Idempotent-Replayed: trueAl reintentar con la misma Idempotency-KeyLa respuesta es la guardada del primer pedido; no se volvió a ejecutar nada.
Retry-AfterEn los 429Segundos a esperar antes de reintentar.
AllowEn los 405Los métodos que la ruta sí acepta.

Archivos y multipart

Casi nada de la API recibe archivos. Hay dos mecanismos:

Subida directa con URL firmada (CVs y adjuntos). Mandas solo la lista de archivos (nombre, tamaño, tipo y el SHA-256 de sus bytes) y recibes una URL de subida por archivo, válida dos horas, a la que haces PUT de los bytes con su tipo como Content-Type. Así funcionan las acciones upload_cv (hasta 100 CVs PDF o DOCX de hasta 4 MB) y upload_attachment (un adjunto PDF, DOCX, XLSX, PNG, JPEG o WebP de hasta 10 MB). Un archivo que el workspace ya tiene vuelve con alreadyHere: true y no se sube ni se cobra de nuevo. Ver Importar CVs.

multipart/form-data en tres rutas de planillas, con el archivo en el campo file:

RutaQué haceArchivo
POST /talent/pool/sheet/columnsLee las columnas de una planilla para que digas qué es cada una.Hasta 4 MB
POST /talent/pool/sheetImporta personas al pool desde una planilla. Además de file, lleva mappings (un string JSON con qué columna es qué campo) y, opcionales, blocks, dedupeOff (strings JSON) y linkPublicProfile ("true").Hasta 4 MB
POST /crm/sheetLee una planilla CSV o XLSX del CRM como encabezados y filas, para después mandar las filas a crm/leads/import, crm/contacts/import o crm/requests/import.Hasta 2 MB
curl -X POST https://app.reclee.com/api/v1/talent/pool/sheet/columns \
  -H "Authorization: Bearer $RECLEE_API_KEY" \
  -F "file=@candidatos.xlsx"

CORS

Las rutas de /api/v1 no mandan headers CORS: un navegador no puede llamarlas desde otro origen. Es a propósito, porque la API se autentica con una key que no debe vivir en el navegador. Llama a la API desde tu servidor.

El servidor MCP (/api/mcp) y los endpoints de su autorización sí responden CORS abierto (Access-Control-Allow-Origin: *), porque hay clientes MCP que corren en el navegador; ninguno usa cookies.

En esta página