search

POST/talent-scout/search

Busca candidatos por prompt en lenguaje natural + filtros estructurados. Es el único endpoint de búsqueda: cubre tanto tu pool propio de talento como LinkedIn (vía proveedor externo) en la misma llamada.

Body

Campo	Tipo	Requerido	Descripción
prompt	string	Sí	Búsqueda en lenguaje natural, ej. "desarrollador backend senior con Node.js"
filtersJson	string	Sí	Objeto de filtros codificado como string JSON (no un objeto anidado) — usá "{}" si no hay filtros. Ver tabla de campos abajo.
page	integer	Sí	Número de página, empieza en 1. 20 candidatos por página.

Campos de `filtersJson`

Es el mismo objeto que usan los filtros manuales de la app — armalo como objeto JS/JSON normal y después hacele JSON.stringify(...) antes de mandarlo.

Campo	Tipo	Descripción
`skills`	`[{ name }]`	Lista de habilidades
`languages`	`[{ name, level }]`	`level`: `BASIC` / `CONVERSATIONAL` / `FLUENT` / `NATIVE`
`customTitles`	`[{ name }]`	Puestos/títulos de búsqueda
`firstName` / `lastName`	`string`	Nombre / apellido, si buscás a alguien puntual
`currentCompany`	`{ query, entityId }`	Empresa actual — `entityId` viene de resolve-entity
`pastCompany`	`{ query, entityId }`	Empresa anterior — mismo formato
`industry`	`{ query, entityId }`	Industria — mismo formato
`school`	`{ query, entityId }`	Universidad/instituto — mismo formato
`countries`	`[{ city, state, country, geoId }]`	`geoId` viene de resolve-location — un texto libre en `city`/`country` sin `geoId` se ignora como filtro
`localOnly`	`boolean`	Si es `true`, busca solo en tu pool propio (candidatos ya guardados) y nunca llama a LinkedIn — más rápido y no consume crédito

Si el prompt menciona una ubicación, empresa, industria o universidad, resolvela primero con resolve-location/resolve-entity y pasá el geoId/entityId resultante en filtersJson. Un nombre en texto libre sin resolver no filtra nada.

Ejemplo de request

curl -X POST "https://api.reclee.com/v1/talent-scout/search" \
  -H "Authorization: Bearer rk_live_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "desarrollador backend senior con Node.js",
    "filtersJson": "{\"countries\":[{\"geoId\":\"90009870\"}],\"skills\":[{\"name\":\"Node.js\"}]}",
    "page": 1
  }'

Respuesta — 200

Campo	Tipo	Descripción
`success`	`boolean`
`page` / `pageSize`	`integer`	`pageSize` siempre `20`
`hasNextPage`	`boolean`	Si hay más páginas disponibles
`totalCandidates` / `totalCandidatesFound`	`integer`	Total estimado (capado a 400 = 20 páginas)
`candidates`	`array`	Ver forma del candidato abajo
`creditsDeducted`	`number`	Créditos consumidos por esta llamada (ya en la unidad que se muestra en la app, no en unidades internas)
`companyCredits` / `companyExtraCredits`	`number`	Saldo restante después de la operación

Cada elemento de candidates trae un campo requiresEnrich: si es false el candidato ya viene con perfil completo (viene de tu propio pool); si es true, llamá a enrich antes de mostrar experiencia/educación.

Candidato de LinkedIn — recién encontrado, sin enriquecer

{
  "id": "linkedin-a1b2c3d4",
  "urn": "linkedin-a1b2c3d4",
  "requiresEnrich": true,
  "full_name": "Marina Estévez",
  "name_first": "Marina",
  "name_last": "Estévez",
  "job_title": "Senior Backend Engineer at Globant",
  "location_raw_address": "Buenos Aires, Argentina",
  "picture_url": "https://media.licdn.com/...",
  "linkedin_url": "https://linkedin.com/in/marinaestevez"
}

Candidato de tu pool — ya completo, requiresEnrich: false

{
  "id": "cmmmfunmz001kowj3i5xh108c",
  "urn": "cmmmfunmz001kowj3i5xh108c",
  "requiresEnrich": false,
  "source": "RECLEE_DB",
  "full_name": "Kevin Chen",
  "job_title": "Software Developer",
  "location": "Buenos Aires, Argentina",
  "currentCompany": "Hirefy",
  "skills": ["ReactJs", "TypeScript", "NodeJs"],
  "languages": [{ "language": "English", "proficiency": "NATIVE" }],
  "work_email": null,
  "personal_email": "kevin@example.com",
  "phone_number": "+54 9 11 5555 0100",
  "experience": [ /* historial completo */ ],
  "education": [ /* educación completa */ ]
}

Los candidatos de tu pool traen varios alias del mismo dato por compatibilidad (ej. work_email / email, company_name / currentCompany) — cualquiera de los dos sirve, el valor es el mismo.

Si falla

code	Cuándo
`INSUFFICIENT_CREDITS`	No hay crédito suficiente. Devuelve `requiredCredits` y `availableCredits`.

Body

Campos de filtersJson

Ejemplo de request

Respuesta — 200

Si falla

En esta página

Campos de `filtersJson`