# Customers and contacts

People, companies, segments, forms, reviews, conversations and consent.

Scopes for this area: `contacts:read`, `contacts:write` and `contacts:admin`.

134 operations.

## contact

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/contacts` | Find and list contacts: search text, a saved segment, a tag or rules. | read | `rivier contacts contact list` |
| POST | `/crm/contacts` | Add a contact, or update the one that already has this email or number. | write | `rivier contacts contact create` |
| GET | `/crm/contacts/lookup` | The contact with this email, phone or handle. | read | `rivier contacts contact lookup` |
| GET | `/crm/contacts/{id}` | One contact. | read | `rivier contacts contact get` |
| PATCH | `/crm/contacts/{id}` | Change a contact: fields, tags, custom fields, identities. | write | `rivier contacts contact update` |
| GET | `/crm/contacts/{id}/timeline` | What happened with this person across email, phone, text, chat, orders, bookings and payments, newest first. | read | `rivier contacts contact timeline` |
| POST | `/crm/contacts/{id}/share` | Share a contact with the other projects of the organisation, or stop sharing. | write | `rivier contacts contact share` |
| POST | `/crm/merge` | Merge one contact into another; history, identities and tags move over. | admin | `rivier contacts contact merge` |

## organisation

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/organisation/contacts` | Contacts the organisation's other projects have shared. | read | `rivier contacts organisation list` |
| POST | `/crm/organisation/contacts/adopt` | Copy a shared contact into this project (without its consent). | write | `rivier contacts organisation adopt` |

## event

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/crm/events` | Tell the contact store something happened with a person (an order, a booking, a payment, a chat); the person is found or made. | write | `rivier contacts event ingest` |

## consent

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/crm/contacts/{id}/consent` | Record a consent decision with its proof (the words, the source, the policy version). | write | `rivier contacts consent record` |
| GET | `/crm/contacts/{id}/consent` | Every consent decision for this person, oldest first, with its proof. | read | `rivier contacts consent ledger` |

## suppression

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/suppressions` | Addresses and numbers that must not be written to. | read | `rivier contacts suppression list` |
| POST | `/crm/suppressions` | Stop writing to an address or number. | write | `rivier contacts suppression add` |
| POST | `/crm/suppressions/remove` | Lift a suppression, with the reason it is lifted. | admin | `rivier contacts suppression remove` |

## company

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/companies` | Companies. | read | `rivier contacts company list` |
| POST | `/crm/companies` | Add a company. | write | `rivier contacts company create` |
| GET | `/crm/companies/{id}` | A company and its people. | read | `rivier contacts company get` |
| PATCH | `/crm/companies/{id}` | Change a company. | write | `rivier contacts company update` |

## segment

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/segments` | Saved segments (live rules). | read | `rivier contacts segment list` |
| POST | `/crm/segments` | Save a segment: a rule over contacts that is evaluated each time it is used. | write | `rivier contacts segment create` |
| PATCH | `/crm/segments/{id}` | Change a segment. | write | `rivier contacts segment update` |
| DELETE | `/crm/segments/{id}` | Delete a segment that no campaign or flow uses. | write | `rivier contacts segment delete` |
| POST | `/crm/segments/preview` | How many people match a rule or segment, and a few of them. | read | `rivier contacts segment preview` |

## note

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/notes` | Notes on a contact or company. | read | `rivier contacts note list` |
| POST | `/crm/notes` | Add a note. | write | `rivier contacts note create` |

## task

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/tasks` | Tasks. | read | `rivier contacts task list` |
| POST | `/crm/tasks` | Add a task. | write | `rivier contacts task create` |
| POST | `/crm/tasks/{id}/complete` | Mark a task done (or open again). | write | `rivier contacts task complete` |

## pipeline

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/pipelines` | Deal pipelines and their stages. | read | `rivier contacts pipeline list` |
| POST | `/crm/pipelines` | Define a pipeline. | write | `rivier contacts pipeline create` |
| GET | `/crm/pipelines/{id}/board` | Each stage of a pipeline with its deals and totals. | read | `rivier contacts pipeline board` |

## deal

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/deals` | Deals. | read | `rivier contacts deal list` |
| POST | `/crm/deals` | Open a deal. | write | `rivier contacts deal create` |
| POST | `/crm/deals/{id}/move` | Move a deal to another stage. | write | `rivier contacts deal move` |

## duplicate

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/duplicates` | People who are probably the same. | read | `rivier contacts duplicate list` |
| POST | `/crm/duplicates/scan` | Look through the contacts for duplicates and propose merges. | write | `rivier contacts duplicate scan` |
| POST | `/crm/duplicates/{id}/dismiss` | Say two people are not the same. | write | `rivier contacts duplicate dismiss` |

## import

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/crm/import` | Import contacts from a CSV file. A dry run first reports what would happen; nobody becomes subscribed by being in a file unless the importer states the basis. | admin | `rivier contacts import run` |

## export

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/crm/export` | Export contacts as CSV. | admin | `rivier contacts export run` |

## person

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/crm/export/person/{id}` | Everything held about one person, to hand to them. | admin | `rivier contacts person export` |
| POST | `/crm/erase/{id}` | Erase a person: record, history, notes and tasks go; their address stays suppressed as a one-way hash. | admin | `rivier contacts person erase` |
| POST | `/contacts/lookup` | Find or create the contact for a phone, address or handle. | write | `rivier contacts person lookup` |
| GET | `/contacts/{id}` | One contact with its identities. | read | `rivier contacts person get` |

## hubspot

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/hubspot` | Whether the HubSpot sync is on and connected, when it last ran and what it did. | read | `rivier contacts hubspot status` |
| POST | `/crm/hubspot/sync` | Run the HubSpot sync now: changes both ways, matched by email; consent never moves as a grant. | admin | `rivier contacts hubspot sync` |

## live

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/live` | Whether real mail may go out for this project: the checks (sender name, postal address, sending domain verified) and who put it live. | read | `rivier contacts live status` |
| POST | `/crm/live` | Put the project live for real recipients. An owner's or admin's decision, only when the checks pass; until then only test addresses receive anything. | admin | `rivier contacts live enable` |
| POST | `/crm/live/disable` | Back to test and hold mode. | admin | `rivier contacts live disable` |

## settings

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/settings` | Sender identity, footer address, opt-in policy, custom fields, grants and limits. | read | `rivier contacts settings get` |
| PUT | `/crm/settings` | Change the settings. The autonomy of agents and campaigns is a person's to change. | admin | `rivier contacts settings save` |

## form

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/forms` | Signup forms. | read | `rivier contacts form list` |
| POST | `/crm/forms` | Create a signup form: fields, the consent words, double opt-in. Returns the hosted address and the embed code. | write | `rivier contacts form create` |
| GET | `/crm/forms/{id}` | One form. | read | `rivier contacts form get` |
| PUT | `/crm/forms/{id}` | Change a form. | write | `rivier contacts form update` |
| DELETE | `/crm/forms/{id}` | Delete a form; its address stops answering. | write | `rivier contacts form delete` |

## submission

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/submissions` | What the forms received: held entries (state held or unconfirmed), accepted and turned away, with sender, form, page, reasons and a preview. | read | `rivier contacts submission list` |
| GET | `/crm/submissions/summary` | One blunt count: the real people the guard held this month, the spam it kept out, and what waits for a decision. | read | `rivier contacts submission summary` |
| GET | `/crm/submissions/senders` | Senders the owner allowed or blocked. | read | `rivier contacts submission senders` |
| POST | `/crm/submissions/senders` | Allow or block a sender (by email address) for the guard. | admin | `rivier contacts submission sender` |
| GET | `/crm/submissions/{id}` | One submission with every field. | read | `rivier contacts submission get` |
| POST | `/crm/submissions/bulk` | Accept or reject many held submissions at once (up to a hundred), optionally allowing or blocking each sender. Each result is reported; one failure does not stop the rest. | admin | `rivier contacts submission bulk` |
| POST | `/crm/submissions/{id}/accept` | Let a held submission in: the person is made or found, the consent they ticked is recorded, the thread moves from Held to the inbox. A person's decision. | admin | `rivier contacts submission accept` |
| POST | `/crm/submissions/{id}/reject` | Reject a held submission: its words are deleted and the thread leaves the Held folder. A person's decision. | admin | `rivier contacts submission reject` |

## reviews

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/reviews/settings` | Reviews and ratings settings: moderation, review requests, incentive notice, destination inbox. | read | `rivier contacts reviews settings get` |
| PUT | `/crm/reviews/settings` | Set up or change reviews and ratings. A person's setting. | admin | `rivier contacts reviews settings save` |
| GET | `/crm/reviews` | Reviews and ratings: the queue (held and waiting) by default, or any state, kind or subject. | read | `rivier contacts reviews list` |
| GET | `/crm/reviews/aggregate` | Average (weighted for recency and verification), simple average, distribution, trend by month, verified count and the NPS or thumbs share for a subject or the whole project. | read | `rivier contacts reviews aggregate` |
| POST | `/crm/reviews/{id}/approve` | Publish a held or waiting review; its thread leaves the Held folder. A person's decision. | admin | `rivier contacts reviews approve` |
| POST | `/crm/reviews/{id}/reject` | Reject a review; its words are not shown and its held thread is deleted. Optionally block the sender. A person's decision. | admin | `rivier contacts reviews reject` |
| POST | `/crm/reviews/{id}/remove` | Take a published review down. A person's decision. | admin | `rivier contacts reviews remove` |
| POST | `/crm/reviews/{id}/reply` | Reply to a review in public. Written by a person (a draft can be used as the starting text). | admin | `rivier contacts reviews reply` |
| POST | `/crm/reviews/{id}/draft-reply` | Draft a reply with the writing assistant; marked as AI-written, kept private until a person publishes it. | admin | `rivier contacts reviews draft reply` |

## history

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/history` | What changed, by whom and when: every audited change names the records it touched. Ask with a record id to see that record's history. | read | `rivier contacts history list` |

## search

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/search` | Search segments, forms, deals, notes, tasks, companies, templates, campaigns, flows or pipelines by the words in them. | read | `rivier contacts search documents` |
| GET | `/crm/consent-records` | Consent decisions as they stand, by channel, purpose and state, for the people matching some words. | read | `rivier contacts search consent` |

## archive

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/archive/{kind}` | Archived records of a kind, to restore from. | read | `rivier contacts archive list` |
| POST | `/crm/archive/{kind}/{id}` | Take a record out of the lists. Nothing is lost; it can be restored. A person's decision. | admin | `rivier contacts archive archive` |
| POST | `/crm/restore/{kind}/{id}` | Put an archived record back. | admin | `rivier contacts archive restore` |

## marketing

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/marketing/plans` | Marketing plans: goal, metric, window and how many drafts each has. | read | `rivier contacts marketing plan list` |
| POST | `/crm/marketing/propose` | The advisor's dialogue: what the person said (and the earlier turns) becomes a proposed plan and the questions still open. Nothing is saved; the person confirms by creating the plan. | write | `rivier contacts marketing propose` |
| POST | `/crm/marketing/plans` | Make a marketing plan: the outcome wanted, the measure, the window, the channels, the words to avoid, the hypothesis and the rule for deciding. Nothing is sent or spent. | write | `rivier contacts marketing plan create` |
| GET | `/crm/marketing/plans/{id}` | One plan with its drafts, their checks and the context it was made in. | read | `rivier contacts marketing plan get` |
| POST | `/crm/marketing/plans/{id}/campaign-draft` | Draft an email or text campaign for a plan in the project's voice; it is an ordinary draft campaign that a person reviews and approves. | write | `rivier contacts marketing campaign draft` |
| POST | `/crm/marketing/plans/{id}/content-draft` | Draft a social post, a page block or a business-profile post for a plan; kept as a marked AI draft, published by a person. | write | `rivier contacts marketing content draft` |
| GET | `/crm/marketing/calendar` | Planned items with the reason for each, and the project's other scheduled campaigns marked as unplanned. | read | `rivier contacts marketing calendar` |
| GET | `/crm/marketing/plans/{id}/results` | What happened against the plan's goal, with what that does and does not show said in plain words. | read | `rivier contacts marketing results` |
| POST | `/crm/marketing/plans/{id}/finish` | Close a plan with the lessons learned; the next plan starts from them. | write | `rivier contacts marketing finish` |
| GET | `/crm/marketing/learnings` | What closed plans taught, newest first. | read | `rivier contacts marketing learnings` |
| POST | `/crm/marketing-approval/{id}` | Approve, start, close or cancel a plan. A person's decision. | admin | `rivier contacts marketing state` |

## chat

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/chat` | The chat widget: the inbox it uses, wording, opening hours, hand-off, rating, transcript and notice; and the embed. | read | `rivier contacts chat get` |
| PUT | `/crm/chat` | Set up or change the chat widget. A person's setting. | admin | `rivier contacts chat save` |

## map

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/maps` | The maps of this project: places, load mode, design and the embed. | read | `rivier contacts map list` |
| POST | `/crm/maps` | Make a map: a list of places (name, address, hours, phone, tags). Addresses without coordinates are looked up once and remembered. | write | `rivier contacts map create` |
| GET | `/crm/maps/{id}` | One map. | read | `rivier contacts map get` |
| PUT | `/crm/maps/{id}` | Change a map. | write | `rivier contacts map update` |
| DELETE | `/crm/maps/{id}` | Delete a map; its address stops answering. | write | `rivier contacts map delete` |
| POST | `/crm/maps/geocode` | Check an address while setting a map up: the place found (or none) and whether a real map service answered. | write | `rivier contacts map geocode` |

## consent widget

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/consent-widget` | The cookie and consent widget: the optional categories in use, the cookie and storage list, the analytics ceiling, copy, design and the embed. Defaults when nothing is saved. | read | `rivier contacts consent widget get` |
| PUT | `/crm/consent-widget` | Set up or change the cookie and consent widget. Visitors are asked again after a change. A person's setting. | admin | `rivier contacts consent widget save` |
| GET | `/crm/consent-widget/stats` | How the banner is doing: times shown, customise opened, decisions, accept all and reject all, by day. | read | `rivier contacts consent widget stats` |
| POST | `/crm/consent-widget/by-region` | What a visitor from each region gets under the given banner settings: whether the banner asks first, what is on before a choice and with a browser privacy signal, the analytics level before and after agreeing, and which regions the project serves. Saves nothing. | read | `rivier contacts consent widget by region` |

## widget

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/crm/widgets` | Every widget Rivier offers, with its manifest: what is built here, what other parts of the product own and register, and what is planned. | read | `rivier contacts widget catalogue` |
| POST | `/crm/widgets` | Make a widget from a template (email signup, newsletter, waiting list, contact, lead form): a form with its words in seven languages, ready to embed. Returns the three embed options. | write | `rivier contacts widget create` |
| GET | `/crm/forms/{id}/embed` | The embed options of a widget: one-line script (shadow DOM, no layout shift), iframe, and the hosted page on the project's domain. | read | `rivier contacts widget embed` |
| GET | `/crm/forms/{id}/stats` | Views, starts, submits, what the guard held, what was let in, confirmations and the conversion of a widget over the last days (default 30). | read | `rivier contacts widget stats` |

## customer account

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/customer-accounts` | The people who have an account to sign in to the project's sites: when they joined and last signed in, whether blocked, and how many devices and passkeys they have. Addresses are the customer's own sign-in addresses. | read | `rivier contacts customer account list` |
| POST | `/customer-accounts/{id}/block` | Block a customer account: every session ends and sign-in stops, without saying why to the customer. A person's decision; an agent needs a person's approval for this exact call. | write | `rivier contacts customer account block` |
| POST | `/customer-accounts/{id}/unblock` | Let a blocked customer account sign in again. | write | `rivier contacts customer account unblock` |
| POST | `/customer-accounts/{id}/delete` | Delete a customer account: sessions and passkeys end and the address is freed. The person's orders, bookings and invoices stay (they are the business's records); their data-subject request is the compliance center's. Needs a person's approval. | write | `rivier contacts customer account remove` |
| POST | `/customer-accounts/test-link` | Send a sign-in code and link to an address as a test. In test mode the mail goes only to the project's test addresses. | admin | `rivier contacts customer account test link` |

## customer sign in

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/customer-accounts/activity` | Recent sign-in activity on the project's sites: codes asked for, sign-ins, failures, blocks and rate limits, with a masked address, the device and a coarse network. Never a code, a token or a full address. | read | `rivier contacts customer sign in list` |

## customer summary

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/customer-accounts/summary` | A count for the home page: accounts, new this week, how many signed in this week, how many use a passkey, how many are blocked and how many attempts were turned away. | read | `rivier contacts customer summary get` |

## customer settings

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/customer-accounts/settings` | How customers sign in to a site: open sign-up or existing accounts only, passkeys on or off, how long a session lasts. | read | `rivier contacts customer settings get` |
| PUT | `/customer-accounts/settings` | Change how customers sign in to a site. A person's decision; an agent is refused. | admin | `rivier contacts customer settings update` |

## identity

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/contacts/{id}/identities` | Attach another identity to a contact. | write | `rivier contacts identity attach` |

## donotcontact

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/suppressions` | Addresses and numbers we must not contact. | read | `rivier contacts donotcontact list` |
| POST | `/suppressions` | Add to the do-not-contact list. | write | `rivier contacts donotcontact add` |
| DELETE | `/suppressions` | Remove from the do-not-contact list. | write | `rivier contacts donotcontact remove` |

## service

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/workspace/service` | Customer service overview: conversations and state. | read | `rivier contacts service get` |
| POST | `/workspace/service/sync` | Pull the latest mail and tickets. | write | `rivier contacts service sync` |

## conversation

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/workspace/service/conversations/{id}` | One customer conversation. | read | `rivier contacts conversation get` |
| POST | `/workspace/service/conversations/{id}/answer` | Answer a customer. | write | `rivier contacts conversation answer` |
| POST | `/workspace/service/conversations/{id}/close` | Close a conversation. | write | `rivier contacts conversation close` |
| POST | `/workspace/service/conversations/{id}/draft` | Draft an answer from the knowledge. | write | `rivier contacts conversation draft` |

## source

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/workspace/service/sources` | What the service answers from. | read | `rivier contacts source list` |
| POST | `/workspace/service/sources` | Add a page or note to the knowledge. | write | `rivier contacts source add` |
| DELETE | `/workspace/service/sources/{id}` | Remove a source. | write | `rivier contacts source delete` |

## voice

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/workspace/service/voice` | How the service sounds. | read | `rivier contacts voice get` |
| PATCH | `/workspace/service/voice` | Change the service's tone and signature. | write | `rivier contacts voice update` |

## bulk

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/crm/bulk` | Change many contacts at once: tag, record consent on the ledger, add to a list, share with the organisation, archive, or move to another project. Starts as a dry run that changes nothing; set dryRun to false to apply. Consent changes need the consent permission; moves are a person's decision. | write | `rivier contacts bulk run` |

## bulk recipients

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/crm/bulk/recipients` | Compile a multi-select of segments, lists, tags and individual contacts, less exclusions, into one audience rule and count it live: matched, able to receive, and without consent. | read | `rivier contacts bulk recipients compile` |

## bulk import

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/crm/bulk/import/preview` | See what a CSV import would do without importing it (always a dry run). The import itself needs a key with the contacts:admin scope. | write | `rivier contacts bulk import preview` |