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| Operation | Scope |
|---|---|
| Search, duplicates | crm_search:read |
| Merge | crm_search:write |
| Bulk update, bulk add/remove tags, bulk delete | crm_bulk:write |
| Tag counts | contacts:read, companies:read or crm_leads:read, matching entity_type |
| CSV export | crm_csv:read |
| CSV inspect, CSV import | crm_csv:write |
crm_bulk has no read half — there is nothing to read, only writes.
Search
GET/api/v1/crm/search
| Parameter | Type | Required | Constraints |
|---|---|---|---|
q | string | Yes | 2–320 characters |
types | string | No | At most 128 characters. Comma-separated subset of contact,company,deal,note,task. Default: all five |
limit | integer | No | 1 <= 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
| Parameter | Type | Required | Constraints |
|---|---|---|---|
entity_type | string | Yes | contact or company |
limit | integer | No | 1 <= 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.
| Field | Type | Required | Constraints |
|---|---|---|---|
entity_type | string | Yes | contact or company |
primary_id | UUID | Yes | The record that survives. Must not appear in duplicate_ids |
duplicate_ids | UUID[] | Yes | 1–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
/duplicatesfirst, and keepduplicate_idssmall 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
| Field | Type | Required | Constraints |
|---|---|---|---|
entity_type | string | Yes | contact, company, deal, task, lead or ticket |
ids | UUID[] | Yes | 1–500 entries |
changes | object | Yes | Non-empty. At most 16,000 characters serialised |
What changes may contain
| Entity | Settable keys |
|---|---|
task | status (open / done), assignee_user_id (nullable), due_at (nullable) |
deal | stage_id (not nullable), owner_user_id (nullable), status (open / won / lost) |
contact | company_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) |
company | industry (nullable), size (nullable) |
lead | owner_user_id (nullable), source (not nullable) |
ticket | assignee_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
| Field | Type | Required | Constraints |
|---|---|---|---|
entity_type | string | Yes | contact, company, deal, task, lead or ticket |
ids | UUID[] | Yes | 1–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.
| Field | Type | Required | Constraints |
|---|---|---|---|
entity_type | string | Yes | contact, company or lead |
ids | UUID[] | Yes | 1–500 entries |
tags | string[] | Yes | 1–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:
VIPandvipare two different tags. - Set the whole list with
tagson create orPATCH; 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.
| Parameter | Type | Required | Constraints |
|---|---|---|---|
entity_type | string | Yes | contact, company or lead |
q | string | No | Case-insensitive prefix, at most 40 characters |
limit | integer | No | 1 <= 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
| Parameter | Type | Required | Applies to |
|---|---|---|---|
entity_type | string | Yes | contact, company or deal |
q | string | No | Contacts (matches phone, email, name) and companies (matches name, domain). At most 320 characters |
company_id | UUID | No | Contacts and deals |
contact_id | UUID | No | Deals |
pipeline_id | UUID | No | Deals |
stage_id | UUID | No | Deals |
owner_user_id | UUID | No | Contacts and deals |
status | string | No | Deals — open, won or lost |
lifecycle_stage | string | No | Contacts |
lead_source | string | No | Contacts |
tag | string (repeatable) | No | Contacts and companies — records carrying any of these tags. At most 20 |
ids | UUID (repeatable) | No | Any — 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.csvStreams 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
| Entity | Columns |
|---|---|
contact | id, name, email, phone, company_id, whatsapp_opt_in, email_opt_in, sms_opt_in, consent_source, created_at, updated_at |
company | id, name, domain, phone, website, industry, size, notes, created_at, updated_at |
deal | id, 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.
| Part | Type | Required | Constraints |
|---|---|---|---|
file | file | Yes | CSV with a header row, UTF-8 or Windows-1252 (Excel's default "CSV" save), comma, semicolon or tab separated. At most 5 MB |
entity_type | text | Yes | contact, company or deal |
use_ai | text | No | Default 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": ","
}| Field | Notes |
|---|---|
headers | Your header row, in its original spelling |
sample_rows | Up to 5 data rows, echoed for review |
proposals[].source | alias (exact name match), heuristic (matched on the sample values) or ai. null when unmapped |
unresolved | Headers still unmapped — map them yourself or leave them out |
importable_fields | Every valid mapping target for this entity_type |
detected_encoding | How 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_delimiter | The 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.
| Part | Type | Required | Constraints |
|---|---|---|---|
file | file | Yes | CSV with a header row, UTF-8 or Windows-1252, comma, semicolon or tab separated. At most 5 MB and 10,000 rows |
entity_type | text | Yes | contact, company or deal |
dry_run | text | No | Defaults to true |
column_map | text | No | A 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_rundefaults to true. A plain import call validates and reports without writing anything — senddry_run=falseexplicitly 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
| Entity | Matched on, in order |
|---|---|
contact | id, else phone, else email |
company | id, else domain |
deal | id 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
| Entity | Accepted columns |
|---|---|
contact | id, name, email, phone, company_id, company_domain, whatsapp_opt_in, email_opt_in, sms_opt_in, consent_source |
company | id, name, domain, phone, website, industry, size, notes |
deal | id, 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
| Status | When |
|---|---|
403 | Key is missing the matching crm_search:* / crm_bulk:write / crm_csv:* scope, or the entity's read scope for tag counts |
404 | An id in your list (or inside changes, or a merge id) is not in your tenant — nothing was changed |
409 | Records still referenced, or a concurrent import |
422 | Query 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.