Skip to main content
API Reference

Search, Bulk & CSV

Cross-object search, duplicate detection and merge, all-or-nothing bulk updates and tagging, and CSV import and export with dry-run validation.

Overview

Four data-management surfaces on top of the CRM objects:

  • Search — one query across contacts, companies, deals, notes and tasks.
  • Duplicates & merge — find records that are the same thing twice, then fold them together.
  • Bulk — update, tag or delete up to 500 records in one all-or-nothing call.
  • Tags — the labels in use on contacts, companies and leads, for autocomplete.
  • CSV — export a filtered set, preview a file's column mapping, or import with a dry run first.

Authentication

Authorization: Bearer cm_your_api_key
OperationScope
Search, duplicatescrm_search:read
Mergecrm_search:write
Bulk update, bulk add/remove tags, bulk deletecrm_bulk:write
Tag countscontacts:read, companies:read or crm_leads:read, matching entity_type
CSV exportcrm_csv:read
CSV inspect, CSV importcrm_csv:write

crm_bulk has no read half — there is nothing to read, only writes.


Search

GET/api/v1/crm/search

ParameterTypeRequiredConstraints
qstringYes2–320 characters
typesstringNoAt most 128 characters. Comma-separated subset of contact,company,deal,note,task. Default: all five
limitintegerNo1 <= limit <= 50, default 10. Per type, not overall
curl "https://api.callmissed.com/api/v1/crm/search?q=acme&types=contact,company&limit=5" \
  -H "Authorization: Bearer cm_your_api_key"
{
  "contacts": [
    { "id": "4411…", "type": "contact", "title": "Asha Menon", "subtitle": "[email protected]" }
  ],
  "companies": [
    { "id": "5c6d…", "type": "company", "title": "Acme Retail", "subtitle": "acme.com" }
  ],
  "deals": [],
  "notes": [
    { "id": "7e21…", "type": "note", "title": "Called Acme about the renewal…", "subtitle": "company", "parent_type": "company", "parent_id": "5c6d…" }
  ],
  "tasks": []
}

Every hit has the same shape. parent_type and parent_id are set only on notes and tasks: the record the note or task is attached to (contact, company, deal, and so on), so you can link the hit to that record. They are null on contacts, companies and deals, and on a task that is not attached to anything.

Every key is always present — an object type with no hits returns an empty array rather than being omitted, so your client never has to guard for a missing key. With limit=50 and all five types you get at most 250 rows.

GET/api/v1/crm/search/duplicates

ParameterTypeRequiredConstraints
entity_typestringYescontact or company
limitintegerNo1 <= limit <= 200, default 50. Counts groups, not records
{
  "entity_type": "contact",
  "groups": [
    { "reason": "email", "key": "[email protected]", "ids": ["4411…", "9922…"], "count": 2 }
  ]
}

reason is what made them look alike: email, phone, name for contacts, and domain or name for companies. key is the normalised value they share — a lower-cased email, the last 10 digits of a phone number, a lower-cased name with whitespace collapsed, or a domain with any http(s)://, leading www. and trailing / removed. A record can appear in more than one group. Groups are largest first, and limit caps the total across all reasons.

POST/api/v1/crm/search/merge

Folds duplicates into one surviving record.

FieldTypeRequiredConstraints
entity_typestringYescontact or company
primary_idUUIDYesThe record that survives. Must not appear in duplicate_ids
duplicate_idsUUID[]Yes1–20 entries, no repeats
{
  "entity_type": "contact",
  "primary_id": "4411…",
  "merged_ids": ["9922…"],
  "fields_filled": ["email", "company_id"],
  "repointed": {
    "conversations": 3,
    "crm_deals": 2,
    "commerce_events": 0,
    "crm_notes": 4,
    "crm_tasks": 1,
    "contact_memory": 0
  }
}

fields_filled lists the fields that were blank on the primary and taken from a duplicate — merging never overwrites a value the primary already had. external_ids maps are combined key by key, with the primary winning any conflict.

repointed counts the related rows moved onto the primary. For a contact merge the keys are conversations, crm_deals, commerce_events, crm_notes, crm_tasks, contact_memory, crm_quotes, crm_invoices, crm_leads, support_tickets, csat_surveys, payment_requests, wa_flow_responses and wa_orders; for a company merge they are contacts, crm_deals, crm_notes, crm_tasks, crm_quotes, crm_invoices and crm_leads.

404 Contact not found (or Company) when the primary or any duplicate is not in your tenant — nothing is merged.

Merging is destructive and irreversible. It runs in a single transaction: either every duplicate is folded in and removed, or nothing changes. Preview with /duplicates first, and keep duplicate_ids small so a mistake is small.


Bulk operations

Every bulk endpoint takes 1–500 ids per request (repeated ids are collapsed) and are all-or-nothing: every id is verified to be in your tenant before a single row is touched.

{ "entity_type": "task", "requested": 3, "affected": 3 }

requested is the raw count you sent; affected is the de-duplicated count actually changed.

POST/api/v1/crm/bulk/update

FieldTypeRequiredConstraints
entity_typestringYescontact, company, deal, task, lead or ticket
idsUUID[]Yes1–500 entries
changesobjectYesNon-empty. At most 16,000 characters serialised

What changes may contain

EntitySettable keys
taskstatus (open / done), assignee_user_id (nullable), due_at (nullable)
dealstage_id (not nullable), owner_user_id (nullable), status (open / won / lost)
contactcompany_id (nullable), owner_user_id (nullable), lifecycle_stage (nullable; subscriber / lead / qualified / opportunity / customer / churned), lead_source (nullable; same values as a lead's source)
companyindustry (nullable), size (nullable)
leadowner_user_id (nullable), source (not nullable)
ticketassignee_user_id (nullable), priority (low / normal / high / urgent)

A lead's or ticket's status is never bulk-settable — converting a lead and moving a ticket through its lifecycle each have their own endpoint. Bulk calls on lead also need the crm_leads:write scope, and on ticket the support_tickets:write scope, in addition to crm_bulk:write.

Anything outside the list — including id, tenant_id, created_at, updated_at and created_by_user_id — returns 422 naming the key and the allowed set. A value of the wrong type returns 422 Invalid value for '<key>'.

Ids inside changes must also be yours: an unknown assignee_user_id, owner_user_id, company_id or stage_id returns 404 Assignee not found (or Owner / Company / Stage). A deal stage_id must belong to the pipeline of every deal in ids — 422 Stage does not belong to this pipeline otherwise — and it closes or re-opens the deals exactly as a move does, unless you also send status. Setting a task's status stamps or clears completed_at; setting a deal's status stamps or clears closed_at.

curl -X POST https://api.callmissed.com/api/v1/crm/bulk/update \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "task",
    "ids": ["bb33…", "cc44…"],
    "changes": { "status": "done", "assignee_user_id": null }
  }'

If any id is missing you get 404 2 of 50 task ids were not found in this tenant; nothing was changed — the count tells you how badly your list has drifted, and nothing was half-applied.

POST/api/v1/crm/bulk/delete

FieldTypeRequiredConstraints
entity_typestringYescontact, company, deal, task, lead or ticket
idsUUID[]Yes1–500 entries

409 One or more company records are still referenced; nothing was deleted when something points at them — clear the references first.

POST/api/v1/crm/bulk/add-tags

Adds tags to every record in ids, keeping the tags each record already has. A tag a record already carries is skipped, so repeating a call changes nothing.

FieldTypeRequiredConstraints
entity_typestringYescontact, company or lead
idsUUID[]Yes1–500 entries
tagsstring[]Yes1–20 tags, each at most 40 characters. Trimmed; blanks and repeats dropped

Bulk calls on lead also need the crm_leads:write scope.

A record can hold at most 20 tags. The limit is checked for each record as it is written, and if any selected record would go over it the whole call is refused — 422 3 of 50 contact records would have more than 20 tags; nothing was changed — rather than trimmed. Remove some tags from those records first.

curl -X POST https://api.callmissed.com/api/v1/crm/bulk/add-tags \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "entity_type": "contact", "ids": ["4411…", "5522…"], "tags": ["vip"] }'

POST/api/v1/crm/bulk/remove-tags

Same body as add-tags. Removes those tags from every record in ids and keeps the rest in order. A record that doesn't carry a tag is left as it is.


Tags

Contacts, companies and leads each carry tags: a list of your own labels, such as vip or renewal.

  • At most 20 tags per record and 40 characters per tag. Longer tags are refused, not cut.
  • Tags are trimmed and runs of spaces become one space. Blank tags and repeats are dropped.
  • Matching is exact: VIP and vip are two different tags.
  • Set the whole list with tags on create or PATCH; add or remove single tags across many records with the bulk endpoints above.
  • Filter any of the three lists by tag with ?tag= (repeatable, matches records carrying any of the tags).

GET/api/v1/crm/tags

The tags in use on one record type, most used first.

ParameterTypeRequiredConstraints
entity_typestringYescontact, company or lead
qstringNoCase-insensitive prefix, at most 40 characters
limitintegerNo1 <= limit <= 200, default 50
curl "https://api.callmissed.com/api/v1/crm/tags?entity_type=contact&q=v" \
  -H "Authorization: Bearer cm_your_api_key"
[
  { "tag": "vip", "count": 42 },
  { "tag": "vendor", "count": 3 }
]

CSV

GET/api/v1/crm/csv/export

ParameterTypeRequiredApplies to
entity_typestringYescontact, company or deal
qstringNoContacts (matches phone, email, name) and companies (matches name, domain). At most 320 characters
company_idUUIDNoContacts and deals
contact_idUUIDNoDeals
pipeline_idUUIDNoDeals
stage_idUUIDNoDeals
owner_user_idUUIDNoContacts and deals
statusstringNoDeals — open, won or lost
lifecycle_stagestringNoContacts
lead_sourcestringNoContacts
tagstring (repeatable)NoContacts and companies — records carrying any of these tags. At most 20
idsUUID (repeatable)NoAny — only these records, e.g. ?ids=…&ids=…. At most 100
curl "https://api.callmissed.com/api/v1/crm/csv/export?entity_type=contact&q=acme" \
  -H "Authorization: Bearer cm_your_api_key" \
  -o contacts.csv

Streams text/csv with Content-Disposition: attachment; filename="contacts-YYYYMMDD.csv". Capped at 50,000 rows — narrow the filters if you need more. Every cell is escaped so a spreadsheet cannot execute a value as a formula.

Export columns

EntityColumns
contactid, name, email, phone, company_id, whatsapp_opt_in, email_opt_in, sms_opt_in, consent_source, created_at, updated_at
companyid, name, domain, phone, website, industry, size, notes, created_at, updated_at
dealid, title, value, currency, status, pipeline_id, stage_id, contact_id, company_id, owner_user_id, expected_close_date, closed_at, last_activity_at, created_at, updated_at

POST/api/v1/crm/csv/inspect

Preview how a file's columns map onto CallMissed fields before you import it. Writes no records and keeps no copy of the file. Requires crm_csv:write.

multipart/form-data.

PartTypeRequiredConstraints
filefileYesCSV with a header row, UTF-8 or Windows-1252 (Excel's default "CSV" save), comma, semicolon or tab separated. At most 5 MB
entity_typetextYescontact, company or deal
use_aitextNoDefault true. When true, headers that no alias or value pattern matched are also tried with an AI pass, billed at the model's token rate. The pass is skipped when your credit balance is empty or your budget cap is reached, and the mapping then uses the rules alone. Send false for a purely rule-based mapping
curl -X POST https://api.callmissed.com/api/v1/crm/csv/inspect \
  -H "Authorization: Bearer cm_your_api_key" \
  -F "[email protected]" \
  -F "entity_type=contact"
{
  "headers": ["Full Name", "Mobile No.", "Email ID", "Notes"],
  "sample_rows": [
    { "Full Name": "Asha Menon", "Mobile No.": "+919876543210", "Email ID": "[email protected]", "Notes": "" }
  ],
  "proposals": [
    { "header": "Full Name", "field": "name", "source": "alias" },
    { "header": "Mobile No.", "field": "phone", "source": "alias" },
    { "header": "Email ID", "field": "email", "source": "alias" },
    { "header": "Notes", "field": null, "source": null }
  ],
  "unresolved": ["Notes"],
  "importable_fields": ["id", "name", "email", "phone", "company_id", "company_domain", "whatsapp_opt_in", "email_opt_in", "sms_opt_in", "consent_source"],
  "detected_encoding": "utf-8",
  "detected_delimiter": ","
}
FieldNotes
headersYour header row, in its original spelling
sample_rowsUp to 5 data rows, echoed for review
proposals[].sourcealias (exact name match), heuristic (matched on the sample values) or ai. null when unmapped
unresolvedHeaders still unmapped — map them yourself or leave them out
importable_fieldsEvery valid mapping target for this entity_type
detected_encodingHow the file was read: utf-8 (with or without a BOM) or windows-1252. A windows-1252 file was saved by Excel as plain "CSV", which has already replaced Hindi and other non-Latin text with ?; save it as CSV UTF-8 to keep it
detected_delimiterThe separator found in the file: ,, ; or a tab

Turn the confirmed proposals into the column_map you send to /import, e.g. {"Full Name": "name", "Mobile No.": "phone", "Email ID": "email"}.

POST/api/v1/crm/csv/import

multipart/form-data.

PartTypeRequiredConstraints
filefileYesCSV with a header row, UTF-8 or Windows-1252, comma, semicolon or tab separated. At most 5 MB and 10,000 rows
entity_typetextYescontact, company or deal
dry_runtextNoDefaults to true
column_maptextNoA JSON object string mapping your headers to import columns, e.g. {"Mobile No.": "phone"}. Usually built from /inspect. Targets must be import columns for this entity_type, and two headers may not map to the same column

dry_run defaults to true. A plain import call validates and reports without writing anything — send dry_run=false explicitly to commit. Run the dry pass first, read the errors, then commit the same file.

curl -X POST https://api.callmissed.com/api/v1/crm/csv/import \
  -H "Authorization: Bearer cm_your_api_key" \
  -F "[email protected]" \
  -F "entity_type=contact" \
  -F "dry_run=true"
{
  "entity_type": "contact",
  "dry_run": true,
  "total": 1200,
  "created": 1140,
  "updated": 52,
  "skipped": 8,
  "errors": [
    { "row": 42, "field": "company_domain", "message": "company_domain does not match a company in this account" }
  ],
  "errors_truncated": false,
  "detected_encoding": "utf-8",
  "detected_delimiter": ","
}

row is the 1-based line in the file, so the first data row is 2 — it lines up with what a spreadsheet shows. Bad rows are counted in skipped and do not stop the rest of the file. At most 100 errors are reported; errors_truncated tells you there were more. The report has the same shape for a dry run and a real import, and carries the same detected_encoding and detected_delimiter as /inspect.

Upsert keys

EntityMatched on, in order
contactid, else phone, else email
companyid, else domain
dealid only — a row without id always creates

A matched row is updated, never duplicated. A contact row with none of id, phone, email (or a company row with neither id nor domain) is reported as an error rather than inserted.

Import columns

EntityAccepted columns
contactid, name, email, phone, company_id, company_domain, whatsapp_opt_in, email_opt_in, sms_opt_in, consent_source
companyid, name, domain, phone, website, industry, size, notes
dealid, title, value, currency, status, pipeline_id, stage_id, contact_id, company_id, owner_user_id, expected_close_date

company_domain on a contact row resolves to an existing company by domain — handy when your source system has no CallMissed ids.

Whole-file problems return 422 and nothing is written: a file that is neither UTF-8 nor Windows-1252 (a UTF-16 "Unicode Text" save is refused with a message to save as CSV UTF-8), an empty file or missing header, a header with no recognised columns (the message lists what was expected), more than 10,000 rows, more than 5 MB, an upload that is not a CSV content type, or an invalid column_map. A concurrent change during the write returns 409 Import conflicted with a concurrent change; nothing was written. Retry.


Errors

StatusWhen
403Key is missing the matching crm_search:* / crm_bulk:write / crm_csv:* scope, or the entity's read scope for tag counts
404An id in your list (or inside changes, or a merge id) is not in your tenant — nothing was changed
409Records still referenced, or a concurrent import
422Query too short, unknown types, over 500 ids, a non-updatable change key, a bulk tag call that would put a record over 20 tags, a deal stage from another pipeline, a file over 5 MB or 10,000 rows, an unrecognised CSV header, or a bad column_map

Nothing on this page consumes credits except the optional AI header-mapping pass (use_ai), which is billed at the model's token rate.

On this page