Reclee

Búsqueda de talento

Acciones para buscar personas fuera del workspace con el proveedor de datos, traer su perfil completo y revelar sus contactos.

La búsqueda de talento encuentra personas fuera de tu workspace usando un proveedor externo de datos de personas: le pasas filtros (cargo, país, skills, idiomas, empresas…) y te devuelve páginas de perfiles. Es la contracara del talent pool, que solo contiene a quienes tu workspace ya conserva.

Todas las acciones de esta página son de la familia PROVIDER: llaman al proveedor y pueden consumir uso de IA o créditos del workspace. Hay dos formas de buscar:

  • search_talent y load_more_talent traen páginas de 20 personas ya enriquecidas (con experiencia y skills) y las dejan disponibles en Reclee. Cuesta una búsqueda más un enriquecimiento por cada persona que tu workspace nunca había pagado.
  • search_talent_preview devuelve la página tal como la describe el proveedor (nombre, titular, ubicación, LinkedIn), sin enriquecer ni guardar a nadie. Cuesta solo la búsqueda.

Una búsqueda solo muestra gente: nadie entra al pool hasta que lo guardas (save_to_pool), lo agregas a una lista (add_to_bookmark) o a una vacante (add_to_job_post). Para traer el perfil completo de alguien puntual (por id o por URL de LinkedIn) está enrich_profile, y para sus emails o teléfono, enrich_contact.

Lo que gasta cada llamada

Las respuestas exitosas de estas acciones traen un campo cost con lo que la llamada realmente consumió: aiUsagePct y teamUsagePct (fracción de 0 a 1 del uso del mes del plan y de la bolsa del equipo), credits (créditos descontados) y billedLater (parte del gasto se registra después). Si el gasto no se puede leer, cost no viene. Si el plan no mide uso, todo es 0. Las búsquedas y los enriquecimientos se cobran contra el uso de IA del plan; cuando el uso del mes se termina, se pagan con créditos comprados si el workspace tiene (spendingCredit en GET /billing/usage-standing). NO_CREDITS y PROVIDER_NO_CREDITS son exclusivos de enrich_contact, y INSUFFICIENT_CREDITS significa que el proveedor no está disponible, no que a tu workspace le falten créditos. El detalle está en Créditos y uso, y el margen disponible se consulta con GET /billing/usage-standing.

Cómo se llama una acción

POST https://app.reclee.com/api/v1/actions/<nombre> con body JSON y Authorization: Bearer rcl_…. Te recomendamos mandar siempre un Idempotency-Key en estas acciones: un reintento con la misma key devuelve la primera respuesta en lugar de gastar dos veces (Idempotencia). Los errores comunes están en Errores.

Filtros de búsqueda

search_talent y search_talent_preview comparten los mismos filtros. Hace falta al menos uno, y una ciudad nunca va sin su país. Los valores van en inglés, sea cual sea el idioma de quien pide la búsqueda.

CampoTipoRequeridoDescripción
titlestringOpcionalUN cargo como lo tienen las personas (no una lista ni 'A OR B'). Coincide parcialmente, así que un prefijo de seniority no lo rompe. Un compuesto que nadie tiene ('Streaming Data Engineer') no trae nada: pon el cargo común acá y la especialidad en headline. Mínimo 3 caracteres.
headlinestringOpcionalLa línea debajo del nombre: una o dos palabras, nunca una oración. Mínimo 3 caracteres.
skillsstring[]OpcionalSkills como las escriben las personas en su perfil; coincide con cualquiera. Hasta 20.
geoCountryCodestringOpcionalCódigo ISO de dos letras, en minúsculas, un solo país ('ar', 'mx').
geoCitystringOpcionalCiudad; coincidencia parcial y tolerante a errores de tipeo. Requiere geoCountryCode. Mínimo 3 caracteres.
experienceMinYearsintegerOpcionalAños totales de carrera, de 1 a 60. Deja afuera a quien nunca declaró fechas: úsalo solo si hace falta.
speaksLanguagestring[]OpcionalNombres de idioma en inglés ('English', 'Portuguese'), nunca códigos ISO. Hasta 20.
industrystring[]OpcionalIndustrias en inglés, escritas completas ('Information Technology', no 'IT'). Mínimo 3 caracteres cada una; hasta 20.
organizationSlugsstring[]OpcionalSlug de LinkedIn de la empresa, en minúsculas ('globant'). Hasta 20.
educationLevelenumOpcionalNivel mínimo: phd, master, bachelor o associate.
certificationsstring[]OpcionalCertificaciones. Hasta 20.
excludeTitlesstring[]OpcionalDeja afuera a quien haya tenido alguna vez ese cargo. Mínimo 3 caracteres cada uno; hasta 20.
excludeOrganizationSlugsstring[]OpcionalSlugs de empresas a excluir. Hasta 20.
excludeIndustriesstring[]OpcionalIndustrias a excluir, en inglés y completas. Mínimo 3 caracteres; hasta 20.

Una lista con más de 20 valores, o un valor por debajo de su mínimo de caracteres, se rechaza con 400 INVALID y details nombra el campo: nunca se recorta en silencio.

search_talent

Familia: PROVIDER · Consume uso de IA: una búsqueda más un enriquecimiento por cada persona de la página que tu workspace nunca pagó.

Busca personas fuera del workspace y trae la primera página de 20, ya enriquecida: cada persona viene con sus últimos puestos (experience) y sus skills, así que no hace falta llamar a enrich_profile para evaluarlas. El proveedor nunca dice cuántas personas hay en total; hasMore dice si hay otra página, que se trae con load_more_talent.

Para refinar una búsqueda que ya existe, pasa su searchId como replacesId: la nueva queda como la siguiente búsqueda, con el número que sigue. Un refinamiento es una búsqueda nueva completa, así que manda todos los filtros (lee los actuales con GET /talent/searches/{searchId} y cambia lo pedido), no solo el cambio.

Cómo estimar antes. Una página reserva una búsqueda más 20 enriquecimientos; las personas que tu workspace ya había pagado no se vuelven a cobrar, por eso el gasto real puede ser menor. Consulta el margen con GET /billing/usage-standing: si aiBlock no es null, la búsqueda se va a rechazar con ese código.

POST/actions/search_talent

Body

Los filtros de búsqueda, más:

CampoTipoRequeridoDescripción
replacesIdstring (uuid)OpcionalEl searchId de la búsqueda que este refinamiento reemplaza.

Ejemplo

curl -X POST https://app.reclee.com/api/v1/actions/search_talent \
  -H "Authorization: Bearer rcl_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b9e3f52-search-backend-ar" \
  -d '{
    "title": "Backend Engineer",
    "skills": ["Go", "Kubernetes"],
    "geoCountryCode": "ar",
    "geoCity": "Cordoba",
    "speaksLanguage": ["English"]
  }'

Respuesta

Extracto (una persona de las 20):

{
  "data": {
    "searchId": "4b6d8f0a-2c4e-4a6c-8e0b-3d5f7a9c1e2b",
    "name": "Search 1",
    "hasMore": true,
    "people": [
      {
        "profileId": "3f6c1a2e-8b4d-4e1f-9a7c-2d5e8f1b4c90",
        "name": "Lucía Ferreyra",
        "headline": "Backend Engineer · Go · Cloud",
        "currentTitle": "Senior Backend Engineer",
        "currentCompany": "Nubeluz",
        "location": "Córdoba, Argentina",
        "doNotContact": false,
        "inPool": false,
        "experience": [
          { "title": "Senior Backend Engineer", "company": "Nubeluz", "from": 2022, "to": null },
          { "title": "Backend Developer", "company": "Datalar", "from": 2019, "to": 2022 }
        ],
        "skills": ["Go", "Kubernetes", "PostgreSQL"]
      }
    ]
  },
  "shown": 20,
  "links": [
    {
      "kind": "talent_search",
      "id": "4b6d8f0a-2c4e-4a6c-8e0b-3d5f7a9c1e2b",
      "label": "Search 1",
      "href": "https://app.reclee.com/talent-pool"
    },
    {
      "kind": "profile",
      "id": "3f6c1a2e-8b4d-4e1f-9a7c-2d5e8f1b4c90",
      "label": "Lucía Ferreyra",
      "href": "https://app.reclee.com/talent-pool?talent=3f6c1a2e-8b4d-4e1f-9a7c-2d5e8f1b4c90"
    }
  ],
  "cost": { "aiUsagePct": 0.012, "teamUsagePct": 0, "credits": 0, "billedLater": false }
}
  • inPool: la persona ya está guardada en el pool de tu workspace.
  • doNotContact: tu workspace la marcó como «no contactar».
  • experience y skills: null cuando no hay nada leído para esa persona.

Errores

CódigoHTTPCuándo
INVALID400No se pudo armar ningún filtro, un filtro no es válido (por ejemplo, una lista de más de 20 valores) o mandaste una ciudad sin país. details nombra el campo.
NOT_FOUND404replacesId no es una búsqueda del workspace.
INSUFFICIENT_CREDITS503La búsqueda externa no está disponible en este momento. No depende de tu plan: avisa a soporte de Reclee.
USAGE_WINDOW402Se alcanzó el límite de uso de las últimas cinco horas; vuelve más tarde.
USAGE_EXHAUSTED402Se terminó el uso de IA del mes.

search_talent_preview

Familia: PROVIDER · Consume uso de IA: una búsqueda por página, sin enriquecimientos. Mucho más barata que search_talent. Solo existe por API y MCP (no en el asistente de la app).

Pide al proveedor una página de personas fuera del workspace y la devuelve tal como la describe el proveedor: nombre, titular, ubicación, URL de LinkedIn y el id del proveedor. No enriquece ni guarda a nadie: nadie entra al pool ni queda registrado en Reclee. Sirve para explorar un mercado barato y después traer solo a quienes te interesan con enrich_profile (pasándole sus linkedinUrls).

La paginación es por cursor: para la página siguiente, llama de nuevo con los mismos filtros y el nextCursor que devolvió la anterior. limit va de 20 a 50 (default 20).

POST/actions/search_talent_preview

Body

Los filtros de búsqueda, más:

CampoTipoRequeridoDescripción
limitintegerOpcionalPersonas por página, de 20 a 50. Default 20.
cursorstringOpcionalEl nextCursor de la página anterior. De 1 a 2000 caracteres.

Ejemplo

curl -X POST https://app.reclee.com/api/v1/actions/search_talent_preview \
  -H "Authorization: Bearer rcl_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Data Engineer",
    "geoCountryCode": "mx",
    "skills": ["Spark", "Airflow"],
    "limit": 50
  }'

Respuesta

Extracto:

{
  "data": {
    "people": [
      {
        "providerPersonId": "pp_8f3a21c9",
        "name": "Andrés Villalobos",
        "headline": "Data Engineer at Ruta Verde",
        "location": "Guadalajara, Mexico",
        "linkedinUrl": "https://www.linkedin.com/in/andres-villalobos-data"
      }
    ],
    "nextCursor": "eyJwYWdlIjoyfQ",
    "hasMore": true
  },
  "shown": 50,
  "links": [],
  "cost": { "aiUsagePct": 0.001, "teamUsagePct": 0, "credits": 0, "billedLater": false }
}

nextCursor es null cuando no hay más páginas.

Errores

CódigoHTTPCuándo
INVALID400No se pudo armar ningún filtro, un filtro no es válido (por ejemplo, una lista de más de 20 valores) o mandaste una ciudad sin país. details nombra el campo.
RATE_LIMITED429El proveedor pidió esperar. Respeta retryAfterSeconds / Retry-After.
PROVIDER_UNAVAILABLE503El proveedor no puede contestar ahora.
INSUFFICIENT_CREDITS503La búsqueda externa no está disponible en este momento. Avisa a soporte de Reclee.
USAGE_WINDOW402Se alcanzó el límite de uso de las últimas cinco horas.
USAGE_EXHAUSTED402Se terminó el uso de IA del mes.

load_more_talent

Familia: PROVIDER · Consume uso de IA: igual que una página de search_talent.

Trae las siguientes 20 personas de una búsqueda de talento, enriquecidas como la primera página. Como siempre, entran al pool solo cuando se guardan, se agregan a una lista o a una vacante. El searchId sale de search_talent o de GET /talent/searches/{searchId}.

fetched cuenta solo a las personas nuevas para esta búsqueda. Una página puede no traer a nadie nuevo (fetched: 0) y seguir con hasMore: true, porque todas las personas de esa página ya habían llegado en una anterior: eso no significa que la búsqueda se agotó. peopleSoFar es cuántas personas acumula la búsqueda.

POST/actions/load_more_talent

Body

CampoTipoRequeridoDescripción
searchIdstring (uuid)SíLa búsqueda.

Ejemplo

curl -X POST https://app.reclee.com/api/v1/actions/load_more_talent \
  -H "Authorization: Bearer rcl_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b9e3f52-search-backend-ar-p2" \
  -d '{ "searchId": "4b6d8f0a-2c4e-4a6c-8e0b-3d5f7a9c1e2b" }'

Respuesta

Extracto:

{
  "data": {
    "searchId": "4b6d8f0a-2c4e-4a6c-8e0b-3d5f7a9c1e2b",
    "name": "Search 1",
    "fetched": 18,
    "peopleSoFar": 38,
    "hasMore": true,
    "people": [
      {
        "profileId": "7a2d9e4b-1c3f-4b8a-8e6d-5f0a2b7c9d13",
        "name": "Martín Quiroga",
        "headline": "Golang Developer",
        "currentTitle": "Backend Developer",
        "currentCompany": "Andes Pay",
        "location": "Córdoba, Argentina",
        "doNotContact": false,
        "inPool": true,
        "experience": null,
        "skills": null
      }
    ]
  },
  "links": [ "…la búsqueda y una por persona…" ],
  "cost": { "aiUsagePct": 0.011, "teamUsagePct": 0, "credits": 0, "billedLater": false }
}

Errores

CódigoHTTPCuándo
NO_MORE_RESULTS409El proveedor no tiene nada después de la última página. Se contesta antes de gastar.
PAGE_IN_FLIGHT409Todavía está llegando una página de esta misma búsqueda. Espera unos segundos y reintenta.
NOT_FOUND404La búsqueda no existe en el workspace.
INSUFFICIENT_CREDITS503La búsqueda externa no está disponible en este momento. Avisa a soporte de Reclee.
USAGE_WINDOW402Se alcanzó el límite de uso de las últimas cinco horas.
USAGE_EXHAUSTED402Se terminó el uso de IA del mes.

enrich_profile

Familia: PROVIDER · Consume uso de IA: un enriquecimiento por cada persona que realmente se trae.

Trae del proveedor el registro completo de LinkedIn (experiencia, estudios, skills, idiomas) de hasta 50 personas y lo guarda en su perfil. Para emails o teléfono está enrich_contact.

Puedes pedir personas de dos formas, combinables (50 en total entre las dos):

  • profileIds: personas que Reclee ya conoce (del pool o de una búsqueda).
  • linkedinUrls: URLs de perfiles de LinkedIn (o solo el handle) de personas que tu workspace quizás no tiene. Quien no estaba en el workspace entra al pool por su LinkedIn.

Las personas que mostró una búsqueda se enriquecen donde están y entran al pool recién cuando se guardan (save_to_pool).

Solo se trae a quien lo necesita: alguien nunca enriquecido, que cambió en el proveedor desde la última vez, o con datos de más de 30 días cuando el proveedor no informa fecha. El resto está al día y se saltea sin cobrar. Las personas que entraron por CV, planilla o a mano, y las líneas sin handle de LinkedIn, no tienen perfil público para traer y también se saltean.

Con refresh: true se vuelve a leer de LinkedIn también a quienes están al día. Úsalo solo cuando alguien pide expresamente volver a leer a una persona, porque cada una se cobra; quien no tiene LinkedIn se sigue salteando.

Cómo estimar antes. Para personas que ya tienes por id, POST /talent/profiles/enrich/plan con { "profileIds": [...] } devuelve, sin gastar nada, total, stale (las que se pagarían), fresh (al día) y withoutProviderKey (sin perfil público). Lo que se cobra es como máximo un enriquecimiento por cada stale más uno por cada URL nueva: una URL que el proveedor ya tiene al día, o que no encuentra, cuesta menos.

POST/actions/enrich_profile

Body

CampoTipoRequeridoDescripción
profileIdsstring[] (uuid)OpcionalPersonas por id. Hasta 50.
linkedinUrlsstring[]OpcionalURLs de LinkedIn o handles. Hasta 50, de 1 a 300 caracteres cada una.
refreshbooleanOpcionaltrue vuelve a leer también a quienes están al día (cada uno se cobra). Default false.

Hace falta al menos una persona, y no más de 50 entre los dos campos.

Ejemplo

curl -X POST https://app.reclee.com/api/v1/actions/enrich_profile \
  -H "Authorization: Bearer rcl_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5a1d77e0-enrich-0091" \
  -d '{
    "profileIds": ["7a2d9e4b-1c3f-4b8a-8e6d-5f0a2b7c9d13"],
    "linkedinUrls": [
      "https://www.linkedin.com/in/andres-villalobos-data",
      "https://www.linkedin.com/company/ruta-verde"
    ]
  }'

Respuesta

{
  "data": {
    "people": 3,
    "enriched": 1,
    "addedToPool": 1,
    "upToDate": 0,
    "notFound": 0,
    "withoutProviderKey": 1,
    "doNotContact": [],
    "linkedin": [
      {
        "linkedinUrl": "https://www.linkedin.com/in/andres-villalobos-data",
        "profileId": "b8d0f2a4-6c8e-4a0b-9d2f-4b6d8f0a2c4e",
        "kind": "added"
      },
      {
        "linkedinUrl": "https://www.linkedin.com/company/ruta-verde",
        "profileId": null,
        "kind": "invalid"
      }
    ]
  },
  "links": [ "…una por persona…" ],
  "cost": { "aiUsagePct": 0.004, "teamUsagePct": 0, "credits": 0, "billedLater": false }
}
  • people: cuántas personas se pidieron.
  • enriched: cuántas se actualizaron con datos nuevos del proveedor.
  • addedToPool: cuántas entraron al pool por su LinkedIn.
  • upToDate: cuántas estaban al día y no se cobraron.
  • notFound: cuántas no encontró el proveedor.
  • withoutProviderKey: cuántas no tienen perfil público para traer (o líneas sin handle).
  • doNotContact: nombres de las personas que tu workspace marcó como «no contactar». Tenlo en cuenta antes de escribirles.
  • linkedin: solo si mandaste linkedinUrls. Una entrada por URL, en el mismo orden y con la URL tal como la mandaste, con el profileId donde quedó y kind: added (entró al pool), refreshed (se actualizó), exists (ya estaba al día), stale, failed (el proveedor no la encontró) o invalid (la línea no tiene un handle de LinkedIn).

Errores

CódigoHTTPCuándo
INVALID400Ninguna persona, o más de 50 entre los dos campos.
NOTHING_TO_ENRICH409Ninguna de las personas necesita enriquecerse. Se contesta antes de gastar. Para leerlas de nuevo igual, repite con refresh: true.
INSUFFICIENT_CREDITS503El proveedor no está disponible en este momento. Avisa a soporte de Reclee.
USAGE_WINDOW402Se alcanzó el límite de uso de las últimas cinco horas.
USAGE_EXHAUSTED402Se terminó el uso de IA del mes.

enrich_contact

Familia: PROVIDER · Consume créditos: cada dato encontrado se cobra en créditos según el plan; un dato que no se encuentra no se cobra.

Busca el email laboral, el email personal y/o el teléfono de personas que ya están en el talent pool, de 1 a 50 por llamada. Pide solo los tipos que necesitas.

Nunca devuelve los datos en sí: la respuesta dice qué se encontró, y los valores quedan en la ficha de la persona. Para leerlos por API, usa POST /talent/contacts/states con { "profileIds": [...] }, que devuelve el estado y el valor de cada dato sin comprar nada.

Es asíncrona. Para una sola persona, los emails suelen volver en la misma llamada; un teléfono, o varias personas, quedan buscándose y aparecen en cada ficha cuando llegan. Se saltea lo que ya se conoce, lo que se buscó hace poco, lo que ya se está buscando y a quien no tiene LinkedIn. Nunca busca a quien está marcado «No contactar» en tu workspace: con una sola persona marcada contesta 409 DO_NOT_CONTACT; con varias, las marcadas vuelven en skipped ({ profileId, reason: "DO_NOT_CONTACT" }), no cuentan en people y el resto se busca. Si todas las pedidas están marcadas, contesta DO_NOT_CONTACT.

Cómo estimar antes. POST /talent/contacts/reveal/estimate con el mismo { "profileIds": [...], "types": [...] } no gasta nada y devuelve: toBuy (cuántos datos se buscarían), alreadyHave, alreadySearched, inFlight, withoutLinkedin, doNotContact (cuántas personas se dejan afuera por la marca), workspaceCredits (los créditos que se cobrarían si se encuentran todos: es el máximo), fitsCredit (si el saldo del workspace alcanza) y exceedsCap (si el pedido es demasiado grande para una sola vez). El costo por tipo de dato de tu plan está en revealCredits de GET /billing/usage-standing.

POST/actions/enrich_contact

Body

CampoTipoRequeridoDescripción
profileIdsstring[] (uuid)SíPersonas del pool. De 1 a 50; los repetidos se ignoran.
typesenum[]SíUno o más de EMAIL_WORK, EMAIL_PERSONAL, PHONE.

Ejemplo

curl -X POST https://app.reclee.com/api/v1/actions/enrich_contact \
  -H "Authorization: Bearer rcl_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d21c4aa-reveal-0042" \
  -d '{
    "profileIds": ["3f6c1a2e-8b4d-4e1f-9a7c-2d5e8f1b4c90"],
    "types": ["EMAIL_WORK", "PHONE"]
  }'

Respuesta

Para una persona, el estado de cada dato pedido (found, searching, notFound o failed):

{
  "data": {
    "people": 1,
    "contacts": [
      { "type": "EMAIL_WORK", "status": "found" },
      { "type": "PHONE", "status": "searching" }
    ]
  },
  "links": [
    {
      "kind": "profile",
      "id": "3f6c1a2e-8b4d-4e1f-9a7c-2d5e8f1b4c90",
      "label": "Lucía Ferreyra",
      "href": "https://app.reclee.com/talent-pool?talent=3f6c1a2e-8b4d-4e1f-9a7c-2d5e8f1b4c90"
    }
  ],
  "next": {
    "missing": [],
    "suggestions": [
      { "tool": "get_profile", "input": { "profileId": "3f6c1a2e-8b4d-4e1f-9a7c-2d5e8f1b4c90" } }
    ]
  },
  "cost": { "aiUsagePct": 0, "teamUsagePct": 0, "credits": 10, "billedLater": true }
}

Para varias personas, cuántas búsquedas se iniciaron:

{
  "data": {
    "people": 11,
    "lookups": 20,
    "searching": true,
    "skipped": [{ "profileId": "8c2e4a6b-0d1f-4e3a-9b5c-7d9e1f3a5b7c", "reason": "DO_NOT_CONTACT" }]
  },
  "links": [ "…una por persona…" ],
  "cost": { "aiUsagePct": 0, "teamUsagePct": 0, "credits": 0, "billedLater": true }
}

Seguir el estado

Consulta POST /talent/contacts/states con los mismos profileIds hasta que ningún dato siga pendiente. Por MCP, la tool de lectura get_profile muestra qué datos tiene la persona (sin los valores). Los créditos se descuentan a medida que los datos aparecen: mientras quede algo buscándose, cost.billedLater es true y cost.credits puede ser menor que el gasto final.

Errores

CódigoHTTPCuándo
NOTHING_TO_REVEAL409No queda nada por buscar: todo se conoce, se buscó hace poco o ya está en curso. Se contesta antes de gastar.
DO_NOT_CONTACT409La persona pedida (o todas las pedidas) está marcada «No contactar» en el workspace. No se gasta nada.
NO_CREDITS402El saldo de créditos del workspace no cubre el pedido.
TOO_LARGE413El pedido es demasiado grande para una sola vez. Divídelo.
PROVIDER_NO_CREDITS503La búsqueda de contactos no está disponible en este momento. No depende de tu plan: avisa a soporte de Reclee.
NOT_FOUND404Con un solo id, la persona no existe o el workspace no la puede ver.

En esta página