CRM API v1

Esta referencia cubre veintidós endpoints sobre cuatro objetos: contactos, su línea de tiempo de interacciones, currículums y los pipelines de contratación (listas) donde tus contactos aparecen como tarjetas. Los endpoints de lectura usan el alcance crm:read; toda escritura, incluidas las rutas de pipelines, usa crm:write. Usa /public/usage para consultar tu cuota 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 las demás familias de la API - una sola clave sirve para todos los productos, controlada por alcance. 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

GET /public/contacts recibe un search opcional (de 1 a 200 caracteres) que coincide con nombre, empresa, puesto, habilidades, industria, educación, correo y teléfono, además de page (base 1) y pageSize (hasta 50, predeterminado 10). Pagina solo con hasMore - no hay conteo total. jobTitle es un arreglo: lleva todos los puestos del currículum del contacto, así que un contacto puede mostrar varios títulos. Las cadenas largas se truncan a 150 caracteres con un marcador ... [truncated].

curl "https://aio-backend-prod.cazvid.app/api/v3.0/crm/public/contacts?search=logistics%20manager&pageSize=10" \
  -H "x-api-key: cazvid_jb_..."

{
  "items": [
    {
      "id": "6a57e240f55eb331f6e396c8",
      "name": "Sidney G.",
      "firstName": "Sidney",
      "lastName": "G.",
      "jobTitle": ["Logistics Manager", "Operations Coordinator"],
      "companyName": "Acme Freight",
      "companyId": null,
      "emails": [],
      "phones": [],
      "linkedinUrl": "https://www.linkedin.com/in/example",
      "locationName": "Bogota, Colombia",
      "locationGeoNameId": null,
      "tags": [{ "id": "6a1f0b2c9c7c630206ba1e77", "name": "priority" }],
      "hasResume": true,
      "resumeCount": 1,
      "cazvidUserId": null,
      "linkedCazvidUser": false,
      "createdAt": "2026-07-01T12:30:00.000Z",
      "updatedAt": null
    }
  ],
  "page": 1,
  "pageSize": 10,
  "hasMore": true
}

GET /public/contacts/{id} devuelve el contacto completo. En el endpoint de lista, los campos marcados abajo como ocultos-en-lista están vacíos o en null por diseño.

{
  "id": "6a57e240f55eb331f6e396c8",
  "name": "Sidney G.",
  "firstName": "Sidney",
  "lastName": "G.",
  "jobTitle": ["Logistics Manager", "Operations Coordinator"],
  "companyName": "Acme Freight",
  "companyId": "6a1f0b2c9c7c630206ba1e44",
  "emails": [{ "email": "sidney@example.com", "type": "work" }],
  "phones": [{ "phone": "+57 300 000 0000", "type": "mobile" }],
  "linkedinUrl": "https://www.linkedin.com/in/example",
  "locationName": "Bogota, Colombia",
  "locationGeoNameId": 3688689,
  "tags": [{ "id": "6a1f0b2c9c7c630206ba1e77", "name": "priority" }],
  "hasResume": true,
  "resumeCount": 1,
  "cazvidUserId": null,
  "linkedCazvidUser": false,
  "createdAt": "2026-07-01T12:30:00.000Z",
  "updatedAt": "2026-07-03T09:15:00.000Z"
}

Crea con POST /public/contacts (solo name es obligatorio), actualiza con PATCH /public/contacts/{id} (envía solo los campos que quieras cambiar) y archiva con DELETE /public/contacts/{id}. Los tres usan el alcance crm:write.

El cuerpo de creación acepta estos campos. La actualización acepta el mismo conjunto, todos opcionales.

curl -X POST https://aio-backend-prod.cazvid.app/api/v3.0/crm/public/contacts \
  -H "x-api-key: cazvid_jb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sidney G.",
    "companyName": "Acme Freight",
    "jobTitle": ["Logistics Manager"],
    "emails": [{ "email": "sidney@example.com", "type": "work" }],
    "phones": [{ "phone": "+57 300 000 0000", "type": "mobile" }]
  }'

{
  "id": "6a57e240f55eb331f6e396c8",
  "deduplicated": false,
  "name": "Sidney G.",
  "firstName": "Sidney",
  "lastName": "G.",
  "jobTitle": ["Logistics Manager"],
  "companyName": "Acme Freight",
  "companyId": null,
  "emails": [{ "email": "sidney@example.com", "type": "work" }],
  "phones": [{ "phone": "+57 300 000 0000", "type": "mobile" }],
  "linkedinUrl": null,
  "locationName": null,
  "locationGeoNameId": null,
  "tags": [],
  "hasResume": false,
  "resumeCount": 0,
  "cazvidUserId": null,
  "linkedCazvidUser": false,
  "createdAt": "2026-07-25T12:30:00.000Z",
  "updatedAt": "2026-07-25T12:30:00.000Z"
}

POST /public/contacts/{id}/resume adjunta un currículum a un contacto como un archivo base64 en línea. fileName, mimeType y contentBase64 son todos obligatorios. Devuelve 202 Accepted y consume una llamada diaria de CRM más una de una cuota de subida de currículums separada por clave (predeterminado 50 por día UTC; ver el bloque resumeUpload en /public/usage).

• mimeType debe ser uno de application/pdf, application/msword o application/vnd.openxmlformats-officedocument.wordprocessingml.document (PDF, DOC, DOCX).
• El archivo decodificado debe pesar como mucho 10 MB, y su tipo real se verifica a partir de sus magic bytes contra mimeType; una discrepancia devuelve 400 MIME_MISMATCH, un archivo vacío 400 EMPTY_FILE, y una entrada no decodificable 400 INVALID_BASE64.
• El análisis es asíncrono: el 202 confirma que el currículum se encoló. Los campos analizados (nombre, correo, teléfono, ubicación, puesto, habilidades, LinkedIn) se escriben en el contacto después, llenando solo sus campos vacíos. Consulta GET /public/contacts/{id} para ver actualizarse hasResume y resumeCount.

curl -X POST https://aio-backend-prod.cazvid.app/api/v3.0/crm/public/contacts/6a57e240f55eb331f6e396c8/resume \
  -H "x-api-key: cazvid_jb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "sidney-resume.pdf",
    "mimeType": "application/pdf",
    "contentBase64": "JVBERi0xLjc...=="
  }'

Una interacción es una entrada de la línea de tiempo de un contacto - una llamada, correo, entrevista, oferta, nota, etc. Registra una con POST /public/contacts/{id}/interactions (type es obligatorio), lee la línea de tiempo de la más reciente a la más antigua con GET /public/contacts/{id}/interactions, y descubre los nombres de tipo válidos con GET /public/interaction-types. El registro nunca se deduplica: cada llamada crea una entrada nueva, así que no reintentes a ciegas una llamada que quizá ya tuvo éxito. Puedes pasar una date futura para registrar un seguimiento programado.

curl -X POST https://aio-backend-prod.cazvid.app/api/v3.0/crm/public/contacts/6a57e240f55eb331f6e396c8/interactions \
  -H "x-api-key: cazvid_jb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phonecall",
    "notes": "Left a voicemail about the operations role.",
    "date": "2026-07-04T16:00:00.000Z"
  }'

Una lista es un pipeline de contratación: un tablero con nombre y etapas ordenadas que contiene una tarjeta por candidato. Es el mismo objeto que la app de CazVid llama lista, así que un pipeline que construyas aquí aparece en el tablero que usan tus reclutadores, y los movimientos que ellos hagan arrastrando tarjetas se ven a través de estas rutas. Doce endpoints cubren los tres niveles: el pipeline, sus etapas y sus tarjetas. Las lecturas usan crm:read; toda escritura usa crm:write.

curl "https://aio-backend-prod.cazvid.app/api/v3.0/crm/public/lists?pageSize=10" \
  -H "x-api-key: cazvid_jb_..."

curl -X POST https://aio-backend-prod.cazvid.app/api/v3.0/crm/public/lists \
  -H "x-api-key: cazvid_jb_..." \
  -H "Idempotency-Key: weekly-pipeline-2026-W32" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Warehouse Hiring 2026",
    "color": "#0EA5E9",
    "stages": [
      { "name": "Sourced", "color": "#64748B" },
      { "name": "Phone Screen", "color": "#4F46E5" },
      { "name": "Offer", "color": "#16A34A" }
    ]
  }'

GET /public/lists devuelve todos los campos de abajo excepto updatedAt y stages. GET /public/lists/{id} añade esos dos y aplica la misma ventana page / pageSize a CADA etapa, devolviéndolos junto con hasMore en el nivel superior. pageSize llega hasta 50 y su valor predeterminado es 10; page es de base 1 y su máximo es 10000. hasMore es true cuando CUALQUIER etapa tiene más tarjetas, no solo la más grande.

{
  "id": "6a3ff55406ae2ed06ddb5fd2",
  "name": "Warehouse Hiring 2026",
  "color": "#0EA5E9",
  "templateType": "CANDIDATE_PIPELINE_EN",
  "associatedPosts": [],
  "itemCount": 1,
  "createdAt": "2026-08-01T10:00:00.000Z",
  "updatedAt": "2026-08-02T09:12:00.000Z",
  "page": 1,
  "pageSize": 10,
  "hasMore": false,
  "stages": [
    {
      "id": "6a3ff55406ae2ed06ddb5fe1",
      "name": "Sourced",
      "color": "#64748B",
      "zorder": 1,
      "itemCount": 1,
      "items": [
        {
          "id": "6a3ff55406ae2ed06ddb5fd1",
          "listId": "6a3ff55406ae2ed06ddb5fd2",
          "stageId": "6a3ff55406ae2ed06ddb5fe1",
          "contactId": "6a57e240f55eb331f6e396c8",
          "authorId": null,
          "rating": null,
          "applicationStatus": null,
          "disqualified": false,
          "disqualifiedReason": null,
          "source": "contact",
          "createdAt": "2026-08-01T10:05:00.000Z",
          "updatedAt": "2026-08-01T10:05:00.000Z"
        }
      ]
    }
  ]
}

Cada tarjeta del arreglo items de una etapa lleva exactamente estos doce campos.

curl -X POST https://aio-backend-prod.cazvid.app/api/v3.0/crm/public/lists/6a3ff55406ae2ed06ddb5fd2/items \
  -H "x-api-key: cazvid_jb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "6a57e240f55eb331f6e396c8",
    "stageId": "6a3ff55406ae2ed06ddb5fe1"
  }'

• zorder es de base 1 y contiguo. Cada cambio en las etapas renumera todo el tablero, así que zorder: 1 es siempre la etapa donde caen los candidatos nuevos.
• Un pipeline admite como máximo 30 etapas activas cuando envías tus propias stages o añades una con POST /public/lists/{id}/stages. copyFromListId deliberadamente NO aplica ese límite, así que copiar un tablero más largo te deja un pipeline por encima del máximo, y uno que ya no se puede reordenar con esta API, porque stageIds también está limitado a 30.
• stages y copyFromListId son mutuamente excluyentes al crear (400 VALIDATION_ERROR si envías ambos). Si no envías ninguno obtienes el pipeline de candidatos predeterminado. No hay selector de idioma: crea un tablero en español enviando tus propias stages o copiando uno existente en español.
• Las reglas de nombre son distintas para un pipeline y para sus etapas. El name de un pipeline solo acepta palabras alfanuméricas separadas por un solo espacio, así que un acento, guion, apóstrofo, ampersand, punto o espacio doble devuelve 400 VALIDATION_ERROR. Los nombres de etapa no tienen esa regla: aceptan caracteres acentuados y barras, que es como se nombran los tableros en español predefinidos. Así que Contratación Almacén se rechaza como nombre de pipeline pero se acepta como nombre de etapa.
• Añadir una tarjeta requiere un contacto existente. POST /public/lists/{id}/items recibe un contactId, no los datos de la persona, así que crea primero el contacto. Añadir el mismo contacto dos veces nunca duplica la tarjeta, pero una repetición con un stageId distinto la mueve: trata la ubicación en la etapa como una escritura intencional, no como una operación sin efecto.
• stageId debe pertenecer al pipeline de la ruta. La etapa de otro pipeline devuelve 404 NOT_FOUND con details[0].field igual a stageId; una tarjeta nunca puede moverse a un tablero ajeno. Añadir una tarjeta a un pipeline sin etapas devuelve 409 LIST_HAS_NO_STAGES: el id es válido, así que añade una etapa en vez de buscar otro pipeline.
• Las tarjetas nunca se pierden en silencio. Eliminar una etapa que contiene tarjetas exige ?moveToStageId, otra etapa activa del mismo pipeline; sin él la llamada devuelve 400 MOVE_TO_STAGE_REQUIRED, y un moveToStageId que no sea una etapa activa de ese pipeline devuelve 404 NOT_FOUND nombrando moveToStageId. La última etapa que le queda a un pipeline no puede eliminarse (400 LAST_STAGE_UNDELETABLE), y una etapa con una cantidad extrema de tarjetas devuelve 400 TOO_MANY_ITEMS_TO_REASSIGN.
• PUT /public/lists/{id}/stages/order recibe el orden completo: stageIds debe contener exactamente los ids de las etapas activas actuales del pipeline, sin faltantes, sobrantes, ajenos ni repetidos.
• Cada ruta de pipelines consume exactamente una llamada de la misma cuota diaria, el mismo límite por minuto y el mismo límite por IP que las rutas de contactos e interacciones. No hay un pool aparte ni un multiplicador por ruta.
• Eliminar un pipeline informa su alcance. La respuesta lleva effects con stagesDeleted e itemsDeleted, contados antes de ejecutar la cascada. La cascada borra de forma suave el pipeline, sus etapas y sus tarjetas, y quita el vínculo del pipeline en la publicación de empleo que apuntaba a él: como mucho una, y no se cuenta en effects, así que vuelve a leer la publicación si necesitas confirmarlo. Los contactos en sí no se tocan.

{
  "id": "6a3ff55406ae2ed06ddb5fd2",
  "deleted": true,
  "effects": {
    "stagesDeleted": 3,
    "itemsDeleted": 12
  }
}

GET /public/usage devuelve tu cuota diaria de CRM y la cuota de subida de currículums separada por clave. Usa la misma autenticación que los demás endpoints 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.

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

{
  "dailyQuota": 500,
  "used": 39,
  "remaining": 461,
  "resetsAt": "2026-07-26T00:00:00.000Z",
  "period": "utc_day",
  "resumeUpload": {
    "dailyLimit": 50,
    "used": 0,
    "remaining": 50
  }
}

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, los 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 por IP lleva minute.

{
  "statusCode": 429,
  "errorCode": "RATE_LIMIT_EXCEEDED",
  "message": "CRM API burst limit exceeded. Slow down and retry shortly.",
  "details": {
    "limit": 30,
    "period": "minute"
  },
  "retryAfter": 43,
  "path": "/api/v3.0/crm/public/contacts"
}

• La cuota diaria de CRM es de 500 llamadas exitosas por organización por día UTC. Es una cuota separada de las demás familias de la API. Cada llamada con cuota (lecturas y escrituras) consume una; GET /public/usage es gratis.
• Un límite por organización de 30 llamadas por minuto, más un límite compartido de 60 por minuto por IP, protegen el backend. Al exceder cualquiera se devuelve 429 con details.period en minute.
• Las subidas de currículum tienen su propia cuota de 50 por clave de API por día UTC, además de la llamada diaria que cada subida también consume.
• El endpoint de lista oculta correos, teléfonos, companyId, locationGeoNameId y updatedAt; consulta un contacto individual para esos. jobTitle es un arreglo, y las cadenas largas se truncan a 150 caracteres.
• Un contacto en otro workspace devuelve un 404 indistinguible. Rota las claves creando una nueva, actualizando tu integración y luego revocando la anterior.
• Las rutas de pipelines comparten ese mismo pool: cada una consume una sola llamada diaria, y sus escrituras son a nivel de workspace (cualquier clave con alcance sobre el workspace puede gestionar cualquier pipeline dentro de él). Un pipeline, etapa o tarjeta de otro workspace devuelve el mismo 404 indistinguible.

¿Prefieres controlar tu CRM desde un agente de IA en vez de HTTP directo? El servidor MCP de CazVid expone las nueve herramientas crm_* (buscar, obtener, crear, actualizar, eliminar contacto, registrar y listar interacciones, listar tipos de interacción y subir currículum) además de list_api_usage a Claude Code, Claude.ai, ChatGPT, Cursor y VS Code, con esta misma clave de API y cuota.