Customers

Return headline counts for this workspace’s customers.

Returns totals for the workspace — how many customers exist, how many are new in the period, and the breakdown by pipeline stage. Use it for a quick health read instead of paging the whole list. Read-only and rate-limited to 20 calls per minute.

Page through this workspace’s customers, most recently updated first.

Returns customers with their contact details, tags, pipeline stage, nullable primaryBranchId and last inbound message time. Use it to find a customer before messaging them, or to sweep a segment by stage, tag, channel, consent, blacklist, WhatsApp-window state, date range or payment status. Pass updatedSince to poll only what changed. Read-only — nothing is written and no message is sent. Paginated: follow meta.pagination.nextCursor until hasMore is false.

Add a customer record with a phone number, name and optional tags.

Creates a customer in this workspace. Use it when a lead arrives from outside the messaging channels. Writes a new record and sends nothing. A phone number that already exists is rejected — find it with customers.list and update it instead. consentStatus: true records an opt-in (logged with consentSource) so the customer can receive broadcasts; only set it when the customer really agreed.

Resolve a phone number or Instagram id to one customer.

Looks up the single customer that owns a channel identity, for example the phone number on an incoming message. Use it before customers.create to avoid duplicates, or to turn a conversation contact into a customer id. Only whatsapp (phone number, with or without +) and instagram (Instagram-scoped id) are stored on the customer; other channels answer null. Answers null in data when nothing matches — that is not an error. Read-only.

Return a short list of {id, name, phoneNumber} matches for a search term.

A lightweight picker: returns only id, name and phoneNumber for customers whose name or phone number contains the search text, newest first. Use it to resolve "Rina" to a customer id cheaply; use customers.list when you need tags, stage, consent or filters. Read-only. Paginated: follow meta.pagination.nextCursor until hasMore is false.

Return customers who have given consent and are not blacklisted.

Returns the audience a broadcast is allowed to target: consented customers who are not blacklisted, sorted by name, optionally narrowed by search text, tags or pipeline stage. Use it to size or preview an audience before broadcasts.create. Read-only — nothing is sent. Paginated: follow meta.pagination.nextCursor until hasMore is false.

List phone numbers that appear on more than one customer record.

Scans the workspace for phone numbers shared by two or more customers and returns each group with a preview of its records. Use it to audit data quality before merging in the dashboard; merging is not available through the API. Read-only but scans the whole customer table, so limited to 20 calls per minute. Paginated by phone number: pass meta.pagination.nextCursor as cursor (it is a phone number, digits with an optional leading +).

Return every customer record sharing one phone number.

Returns all the customers that share the given phone number, with their relation counts, so you can see which record is the fuller one. Take the phone number from customers.duplicatePhoneGroups. Read-only; merging is not available through the API.

Fetch a single customer by id, with their full profile.

Returns one customer including contact details, tags, pipeline stage, nullable primaryBranchId, consent and messaging-window state. Use it after customers.list to read the detail you need before acting. Read-only. Answers 404 when the id does not belong to this workspace.

Permanently delete a customer and everything attached to them.

Removes the customer, their conversations and their history. This cannot be undone and there is no soft-delete to recover from. Use it only for a record the workspace owner has asked to erase. Requires the customers:delete scope, which is separate from ordinary writes, and is limited to 5 calls per minute.

Change a customer’s name, tags, pipeline stage or contact details.

Updates the fields you send and leaves the rest alone. Use it to move a customer along the pipeline, retag them, or correct their details. Writes to the record and can trigger stage-based automation, but sends the customer nothing. consentStatus and blacklisted change the flags directly and write NO consent log — use customers.consent.update to record an opt-in/opt-out properly and customers.blacklist.update to blacklist. Both flags gate broadcasts and outbound messaging. Send pipelineStageId: null to remove the customer from the pipeline.

Return the internal notes a team member has left on this customer.

Returns the notes attached to one customer, newest first. Use it to pick up context before replying. Read-only, and notes are never shown to the customer. Paginated by limit; a customer with a long history returns the newest page first.

Attach an internal note to a customer.

Records a note against the customer so the next reader has the context. Use it to write down what you did or what the customer asked for. Writes a note; the customer never sees it and nothing is sent.

Return the activity history recorded against this customer.

Returns the timeline for one customer — stage moves, messages, payments and follow-ups — newest first. Use it to reconstruct what has already happened before deciding what to do next. Read-only. Paginated: follow meta.pagination.nextCursor until hasMore is false.

Record an activity on a customer’s timeline.

Adds an entry to the customer timeline that customers.activities.list reads back. Use it to leave an audit trail of something that happened outside the platform, such as a phone call (type NOTE_ADDED with the text in description). A NOTE_ADDED entry with a description also creates a customer note. It only records history: it does not send a message, move the stage or change any field, even for types like MESSAGE_SENT or STAGE_CHANGED.

Tell whether free-form WhatsApp text is allowed or a template is required.

Returns whether the customer’s WhatsApp customer-service window is open. When isActive is true you may send free-form text with messages.send; when false (status expired or never_messaged) only an approved template can be sent. Call it before messages.send to pick text versus template. Includes lastInboundMessageAt, windowExpiresAt and the time remaining. Read-only.

List other customer records that look like the same person.

Returns records that share this customer’s phone number, with relation counts for each, so you can judge duplicates. Use it to report data-quality problems. Read-only; merging is not available through the API and has to be done in the dashboard.

Log an opt-in or opt-out and update the customer’s consent flag.

Records that the customer opted in (OPT_IN), opted out (OPT_OUT) or that consent details changed (UPDATE), writes a consent-log entry and sets the consent flag (true only for OPT_IN). Consent gates broadcasts: a customer without consent is excluded from them, and consent is a legal record, so only log what the customer actually did and say where it came from in source. This is the compliant way to change consent, unlike setting consentStatus in customers.update. Sends the customer nothing.

Block a customer from broadcasts and outbound messaging, or lift the block.

Sets the blacklist flag. A blacklisted customer is excluded from broadcasts and should not be messaged, so use it for people who asked to stop or are abusive, and unblacklist only on their request. Reversible; writes the flag and sends nothing.

Permanently remove one internal note from a customer.

Deletes a single note. This cannot be undone and the timeline entry that was written when the note was added stays. Use it only when asked to remove a specific note, with ids from customers.notes.list. Requires the customers:delete scope and is limited to 5 calls per minute.

Return the sales pipelines configured on this workspace with their ordered stages.

Returns each pipeline and the stages inside it, with the stage ids you need to filter customers.list or to move a customer with customers.update. Call it once and reuse the result — stages change rarely. Read-only. For the cards in each stage use crm.pipelines.board, or filter customers by stageId.

Return every stage of a pipeline with its customer count and first customers.

Returns the kanban view of one pipeline: each stage with its real total and the first page of customers in it (id, name, phone number, lead score, where to reply). Use it to see how many deals sit in each stage at a glance. limit sets how many customers come back per stage; read further customers of one stage with crm.stages.customers. Read-only, but it queries every stage so it is limited to 20 calls per minute. Get the pipeline id from pipelines.list.

Page through the customers sitting in one pipeline stage.

Returns the customers in one stage, newest first, in the compact board-card shape (id, name, phone number, lead score, where to reply). Use it to read past the first page that crm.pipelines.board returns, or to work one stage at a time. Read-only. Paginated: follow meta.pagination.nextCursor until hasMore is false. Stage ids come from pipelines.list.

Return customers who have no pipeline stage yet.

Returns {id, name, phoneNumber} for customers with no pipeline stage, newest first, optionally filtered by name or phone number. Use it to find leads that still need triage, then place them with customers.update and a pipelineStageId. Read-only. Paginated: follow meta.pagination.nextCursor until hasMore is false.

Return the custom fields this workspace defines for customers.

Returns each custom field with its id, name, key, type, options and whether it is required. Call it before customers.create or customers.update with customFields, because values are written by fieldDefinitionId. Read-only; defining fields is done in the dashboard. Paginated by limit; most workspaces fit on the first page.

Return the rules that tag customers and move them between stages.

Returns the workspace’s auto-tagging rules: the keywords and optional triggering-conversation branch condition, the tags it adds, the stage it moves the customer to, its priority and whether it is active. Use it to understand why a customer got a tag or changed stage. Read-only. Paginated by limit; most workspaces fit on the first page.

Fetch a single auto-tagging rule by id.

Returns one rule with its keywords, nullable branchId condition, tags to add, target stage, priority and active state. Read-only. Answers 404 when the id does not belong to this workspace.

Flip a rule between active and inactive.

Switches an automation on or off: while active, the rule adds tags to customers and may move them to another pipeline stage whenever a message matches its keyword and branch conditions. The call flips the current state (it is not set-to-value), so read the rule with crm.autoTagging.rules.get first and check isActive in the answer. Reversible; sends the customer nothing.

Add a sales pipeline, optionally with its first stages.

Creates a pipeline for this workspace. Pass stages to create them in the same call; their order is the order sent unless a stage names its own order. A new pipeline is never the default: make it the default afterwards with crm.pipelines.update and isDefault. Moves and sends nothing to customers. Answers the pipeline with its stage ids.

Rename a pipeline, change its description or make it the default.

Changes only the fields you send. isDefault true makes this the default pipeline and clears the flag on the others; isDefault false leaves the workspace with no default, so prefer making another pipeline the default instead. Stages are not touched: use crm.stages.create, crm.stages.update and crm.stages.delete. Read the current values with pipelines.list first.

Create a stage at the end of a pipeline, or at a given position.

Adds a stage. Without order it goes after the last stage; without color it is black (#000000). Sends nothing to customers and moves none. Answers the new stage with its id. Answers 404 when the pipeline does not belong to this workspace.

Permanently remove a pipeline stage that has no customers.

Deletes the stage. It is refused with 409 stage_not_empty while any customer sits in it, so a customer is never dropped from the pipeline by accident: move them first with customers.update and a pipelineStageId, or read them with crm.stages.customers. Auto-tagging rules that point at the stage stop moving customers. Cannot be undone. Answers 404 when the stage does not belong to this workspace.

Rename a stage, recolour it or move it to another position.

Changes only the fields you send. Moving a stage means setting its order: stages are shown lowest order first and a clash is not rejected, so give each stage you move a distinct number (read the current orders with pipelines.list first). Customers in the stage stay in it. Answers 404 when the stage does not belong to this workspace.

Find customers whose Instagram username or name matches the person in a thread.

For an Instagram conversation, returns the customer it is already linked to, or up to 10 customers whose Instagram username or name matches the participant, including their phone numbers, which is why it needs customers:read and not conversations:read. Use it before instagram.linkCustomer to pick the right customer instead of creating a duplicate. Read-only. Returns the conversation participant's username and name when unlinked.