Candidate Search API v1

La v1 tiene dos endpoints públicos. Usa /public/search para encontrar candidatos con una consulta y filtros opcionales. Usa /public/usage para consultar tu cuota diaria restante sin gastarla.

Envía tu clave de API con el encabezado x-api-key o como un token Authorization: Bearer. Es la misma clave de CazVid Developer API que la de Job Builder - una sola clave sirve para ambos productos. Las claves pertenecen a una organización; los propietarios y administradores las gestionan en la app en Perfil > Developer API. Las claves en texto plano se muestran una sola vez al crearlas y CazVid las almacena solo como hash. Trata las claves como secretos: no las pongas en código de frontend, apps móviles, capturas de pantalla, registros ni mensajes de soporte.

x-api-key: cazvid_jb_...
Authorization: Bearer cazvid_jb_...
Content-Type: application/json

POST /public/search recibe un query obligatorio (de 2 a 300 caracteres) y filtros estructurados opcionales. Los filtros acotan el mismo pool de candidatos que usa la búsqueda de reclutadores en la app. Envía page y pageSize para paginar; pageSize está limitado a 25 y page a 100.

curl -X POST https://aio-backend-prod.cazvid.app/api/v3.0/candidate-search/public/search \
  -H "x-api-key: cazvid_jb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "bilingual customer support agent in Mexico City",
    "location": "Mexico City, Mexico",
    "remote": true,
    "requireVideo": true,
    "language": "en",
    "page": 1,
    "pageSize": 10
  }'

Cada resultado es un perfil público de candidato depurado. Los campos anulables se omiten o son null cuando CazVid no tiene ese dato. candidateId es un token pc1. opaco y estable, no un id de plataforma sin procesar y no reversible por quien llama. cazumeUrl solo está presente cuando el candidato ha publicado un perfil público de Cazume.

{
  "results": [
    {
      "candidateId": "pc1.aGVsbG8td29ybGQ",
      "displayName": "Maria G.",
      "headline": "Bilingual Customer Support Specialist",
      "summary": "Five years supporting SaaS customers in English and Spanish.",
      "topSkills": ["Customer support", "Zendesk", "Bilingual (EN/ES)"],
      "matchedSkills": ["Customer support", "Bilingual (EN/ES)"],
      "matchTier": "local",
      "locationName": "Mexico City, Mexico",
      "countryCode": "MX",
      "isRemote": true,
      "language": "en",
      "hasVideo": true,
      "videoUrl": "https://ik.imagekit.io/cazvid/videos/example.mp4",
      "thumbnailUrl": "https://ik.imagekit.io/cazvid/thumbs/example.jpg",
      "avatarUrl": "https://ik.imagekit.io/cazvid/avatars/example.jpg",
      "cazumeUrl": "https://cazvid.com/cazume/maria-g",
      "updatedAt": "2026-07-01T12:30:00.000Z"
    }
  ],
  "hasMore": true,
  "page": 1,
  "pageSize": 10
}

La respuesta envuelve los resultados con metadatos de paginación. Esta API pagina solo con hasMore - no hay un conteo total.

• results - los perfiles de candidatos de esta página.
• hasMore - true cuando existe otra página. Solicita la siguiente incrementando page.
• page - el número de página (base 1) devuelto.
• pageSize - el tamaño de página devuelto.
• No hay campo de conteo total. No esperes un total ni un count: sigue solicitando páginas mientras hasMore sea true.

GET /public/usage devuelve la cuota diaria de Candidate Search de la organización que llama. Usa la misma autenticación que la búsqueda y no cuenta para la cuota, así que puedes consultarlo antes de un lote para evitar respuestas 429. Las consultas están limitadas a 60 solicitudes por minuto por clave de API; al excederlo se devuelve la forma estándar de 429 con details.period en minute.

curl https://aio-backend-prod.cazvid.app/api/v3.0/candidate-search/public/usage \
  -H "x-api-key: cazvid_jb_..."

{
  "dailyQuota": 100,
  "used": 12,
  "remaining": 88,
  "resetsAt": "2026-07-08T00:00:00.000Z",
  "period": "utc_day"
}

Las respuestas de error usan valores errorCode estables para que las integraciones no tengan que analizar mensajes de texto. Cada error devuelve el path de la solicitud; las respuestas 429 añaden retryAfter, el número de segundos hasta que se reinicia la ventana del límite. Un 429 de la cuota diaria lleva details.period utc_day; un 429 del límite por minuto o del límite de consultas de uso lleva minute.

{
  "statusCode": 429,
  "errorCode": "RATE_LIMIT_EXCEEDED",
  "message": "Daily Candidate Search API quota exceeded.",
  "details": {
    "limit": 100,
    "period": "utc_day"
  },
  "retryAfter": 21600,
  "path": "/api/v3.0/candidate-search/public/search"
}

Los datos de candidatos se proporcionan para atender la solicitud del usuario final que tienes enfrente, no para copiarse ni revenderse. Al usar esta API aceptas lo siguiente. Estos términos pueden ser reemplazados por términos formales de la API cuando la API pase a disponibilidad general.

• Sin duplicación masiva ni redistribución. No copies el índice de candidatos a tu propio almacén ni construyas un directorio o conjunto de datos competidor a partir de él.
• Sin retención más allá de atender la solicitud. Conserva los resultados solo el tiempo necesario para responder la solicitud que tienes enfrente; no construyas una copia persistente de los perfiles de candidatos.
• Sin reventa. Los perfiles de candidatos y cualquier campo derivado de ellos no pueden venderse, sublicenciarse ni redistribuirse.
• Contacta a los candidatos solo a través de CazVid. Los resultados no incluyen datos de contacto; contacta a un candidato a través de su perfil público de Cazume o de la app de CazVid, nunca fuera de la plataforma.
• Sin evasión de la cuota. No uses varias claves, organizaciones ni cuentas para evadir la cuota diaria por organización ni el límite por minuto.

• La cuota de la v1 es de 100 llamadas exitosas a search por organización por día UTC. Es una cuota separada de la de Job Builder API.
• Un límite por organización de 20 búsquedas por minuto protege el backend de búsqueda compartido. Al excederlo se devuelve 429 con details.period en minute.
• pageSize está limitado a 25 y page a 100. Las solicitudes por encima de esos límites devuelven 400 VALIDATION_ERROR.
• Los resultados no incluyen datos de contacto (ni correo, ni teléfono, ni LinkedIn) ni ids de plataforma sin procesar. Contacta a los candidatos a través de la app de CazVid o de su perfil de Cazume.
• Rota las claves creando una clave nueva, actualizando tu integración y luego revocando la anterior. La misma clave sirve también para la Job Builder API.

¿Prefieres controlar la búsqueda de candidatos desde un agente de IA en vez de HTTP directo? El servidor MCP de CazVid expone search_candidates (además de list_api_usage) a Claude Code, Claude.ai, ChatGPT, Cursor y VS Code, con esta misma clave de API y cuota diaria.