CRM API v1

This reference covers twenty-two endpoints over four objects: contacts, their interaction timeline, resumes, and the hiring pipelines (lists) your contacts sit on as cards. Read endpoints use the crm:read scope; every write, including the pipeline routes, uses crm:write. Use /public/usage to check your remaining quota without spending it.

Send your API key with the x-api-key header or as an Authorization: Bearer token. This is the same CazVid Developer API key as the other API families - one key works across products, gated by scope. Keys belong to an organization; org owners and admins manage them in the app under Profile > Developer API. Plaintext keys are shown once when created and stored hash-only by CazVid. Treat keys as secrets: do not put them in frontend code, mobile apps, screenshots, logs, or support messages.

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

GET /public/contacts takes an optional search (1 to 200 characters) that matches name, company, job title, skills, industry, education, email, and phone, plus page (1-based) and pageSize (up to 50, default 10). It paginates on hasMore only - there is no total count. jobTitle is an array: it carries every role from the contact's resume, so one contact can show several titles. Long strings are truncated at 150 characters with a ... [truncated] marker.

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} returns the full contact. On the list endpoint the fields marked below as list-withheld are empty or null by design.

{
  "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"
}

Create with POST /public/contacts (only name is required), update with PATCH /public/contacts/{id} (send only the fields you want to change), and archive with DELETE /public/contacts/{id}. All three use the crm:write scope.

The create body accepts these fields. Update accepts the same set, all optional.

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 attaches a resume to a contact as an inline base64 file. fileName, mimeType, and contentBase64 are all required. It returns 202 Accepted and consumes one CRM daily call plus one of a separate per-key resume-upload quota (default 50 per UTC day; see the resumeUpload block in /public/usage).

• mimeType must be one of application/pdf, application/msword, or application/vnd.openxmlformats-officedocument.wordprocessingml.document (PDF, DOC, DOCX).
• The decoded file must be at most 10 MB, and its real type is verified from its magic bytes against mimeType; a mismatch returns 400 MIME_MISMATCH, an empty file 400 EMPTY_FILE, and undecodable input 400 INVALID_BASE64.
• Parsing is asynchronous: the 202 confirms the resume was queued. The parsed fields (name, email, phone, location, job title, skills, LinkedIn) are written onto the contact later, filling only its empty fields. Poll GET /public/contacts/{id} to see hasResume and resumeCount update.

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...=="
  }'

An interaction is a timeline entry on a contact - a call, email, interview, offer, note, and so on. Log one with POST /public/contacts/{id}/interactions (type is required), read the timeline newest-first with GET /public/contacts/{id}/interactions, and discover the valid type names with GET /public/interaction-types. Logging is never de-duplicated: each call creates a new entry, so do not blindly retry a call that may already have succeeded. You can pass a future date to record a scheduled follow-up.

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"
  }'

A list is a hiring pipeline: a named board with ordered stages, holding one card per candidate. It is the same object the CazVid app calls a list, so a pipeline you build here shows up on the board your recruiters use, and their drag-and-drop moves are visible through these routes. Twelve endpoints cover the three levels: the pipeline itself, its stages, and its cards. Reads use crm:read; every write uses 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 returns every field below except updatedAt and stages. GET /public/lists/{id} adds those two, and applies the same page / pageSize window to EVERY stage, echoing them alongside hasMore at the top level. pageSize goes up to 50 and defaults to 10; page is 1-based and capped at 10000. hasMore is true when ANY stage has more cards, not just the largest one.

{
  "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"
        }
      ]
    }
  ]
}

Each card in a stage's items array carries exactly these twelve fields.

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 is 1-based and contiguous. Every stage mutation renumbers the whole board, so zorder: 1 is always the stage new candidates land in.
• A pipeline is capped at 30 active stages when you send your own stages or append one with POST /public/lists/{id}/stages. copyFromListId deliberately does NOT apply that cap, so copying a longer board gives you a pipeline over the limit - and one that can no longer be reordered through this API, since stageIds is itself capped at 30.
• stages and copyFromListId are mutually exclusive on create (400 VALIDATION_ERROR when both are sent). Send neither and you get the default candidate pipeline. There is no language selector: build a Spanish board by sending your own stages, or by copying an existing Spanish one.
• Name rules differ between a pipeline and its stages. A pipeline name accepts only alphanumeric words separated by single spaces, so an accent, hyphen, apostrophe, ampersand, period, or double space is 400 VALIDATION_ERROR. Stage names carry no such rule: they accept accented characters and slashes, which is how the seeded Spanish boards are named. So Contratación Almacén is rejected as a pipeline name but accepted as a stage name.
• Adding a card needs an existing contact. POST /public/lists/{id}/items takes a contactId, not a person's details, so create the contact first. Adding the same contact twice never duplicates the card, but a repeat carrying a different stageId moves it - treat stage placement as an intentional write rather than a no-op.
• stageId must belong to the pipeline in the path. Another pipeline's stage is 404 NOT_FOUND with details[0].field of stageId; a card can never be moved onto a foreign board. Adding a card to a pipeline that has no stages is 409 LIST_HAS_NO_STAGES - the id is valid, so add a stage rather than hunting for another pipeline.
• Cards are never silently lost. Deleting a stage that holds cards requires ?moveToStageId, another active stage of the same pipeline; without it the call is 400 MOVE_TO_STAGE_REQUIRED, and a moveToStageId that is not an active stage of that pipeline is 404 NOT_FOUND naming moveToStageId. A pipeline's last remaining stage cannot be deleted at all (400 LAST_STAGE_UNDELETABLE), and a stage holding an extreme number of cards is 400 TOO_MANY_ITEMS_TO_REASSIGN.
• PUT /public/lists/{id}/stages/order takes the full order: stageIds must be exactly the pipeline's current active stage ids, with no missing, extra, foreign, or repeated entry.
• Every pipeline route consumes exactly one call from the same daily quota, burst limit, and per-IP backstop as the contacts and interactions routes. There is no separate pool and no per-route multiplier.
• Deleting a pipeline reports its blast radius. The response carries effects with stagesDeleted and itemsDeleted, counted before the cascade runs. The cascade soft-deletes the pipeline, its stages, and its cards, and clears the pipeline link on the job posting that pointed at it - at most one, and not counted in effects, so re-read a posting if you need to confirm. The contacts themselves are untouched.

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

GET /public/usage returns your daily CRM quota and the separate per-key resume-upload quota. It uses the same authentication as the other endpoints and does not count against the quota, so you can poll it before a batch to avoid 429 responses. Polling is throttled to 60 requests per minute per API key.

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
  }
}

Error responses use stable errorCode values so integrations do not need to parse prose messages. Every error echoes the request path; 429 responses add retryAfter, the seconds until the limit window resets. A 429 from the daily quota carries details.period of utc_day; a 429 from the per-minute burst or per-IP backstop carries 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"
}

• The CRM daily quota is 500 successful calls per organization per UTC day. This is a separate quota from the other API families. Every metered call (reads and writes) consumes one; GET /public/usage is free.
• A per-organization burst limit of 30 calls per minute, plus a shared 60-per-minute per-IP backstop, protect the backend. Exceeding either returns 429 with details.period of minute.
• Resume uploads have their own quota of 50 per API key per UTC day, on top of the daily call slot each upload also consumes.
• The list endpoint withholds emails, phones, companyId, locationGeoNameId, and updatedAt; fetch a single contact for those. jobTitle is an array, and long strings truncate at 150 characters.
• A contact in another workspace returns an indistinguishable 404. Rotate keys by creating a new key, updating your integration, then revoking the old key.
• The pipeline routes share that one pool: each consumes a single daily call, and their writes are workspace-wide (any key scoped to the workspace can manage any pipeline in it). A pipeline, stage, or card in another workspace returns the same indistinguishable 404.

Prefer to drive your CRM from an AI agent instead of raw HTTP? The CazVid MCP server exposes the nine crm_* tools (search, get, upsert, update, delete contact, log and list interactions, list interaction types, and upload resume) plus list_api_usage to Claude Code, Claude.ai, ChatGPT, Cursor, and VS Code, using this same API key and quota.