CRM: opportunities, activities and the pipeline

The CRM keeps an entity's pipeline of deals (opportunities) and the timeline of what happened with a customer or a deal (notes, calls, meetings, e-mails, stage changes) together with the tasks of what is to be done. Nothing in it posts to the ledger, and it is not a second customer master: a customer is a party, with its own controls (draft, activation by a second person). The design is ADR-0036; this guide is slice 1 as built. Subscriptions, upsells and downsells, proration and credit notes, and MRR are later slices of the same ADR. The controls are in the control matrix (section "CRM", CR1 to CR6).

Everything is a REST operation first (/v1, tag "crm" in the generated reference); the MCP tools are the same operations for an AI sales assistant: list_opportunities, opportunity_pipeline, create_opportunity, update_opportunity, move_opportunity_stage, list_people, list_activities, log_activity and complete_task, for the people at customers list_contacts, list_custom_fields, create_contact and update_contact (erasing a contact stays a person's decision), and for its quotes list_quotes, get_sales_document, create_quote and update_quote (drafts only: a person sends a quote, see quotes and sales orders). A company coming from Salesforce brings its accounts, deals and their activities over with the Salesforce import.

Opportunities

New deal in the app asks for what only you know and fills or offers the rest: each field says what goes in it, a new deal is yours unless you pick a colleague, picking a customer brings its currency, and the close day is one click away (the end of this or next month or quarter). Edit offers the usual next steps (book a demo, send the offer, call to follow up, ask for the decision), and Suggest with AI proposes one from the deal's title, stage, customer and amount, with its reason; nothing is saved until you save. Moving a deal to Lost offers the common reasons.

POST  /v1/opportunities                        {entity, title, party | prospect_name, amount, ...}
GET   /v1/opportunities                        ?entity&stage&open&party_id&owner_user_id
GET   /v1/opportunities/{opportunity_id}
PATCH /v1/opportunities/{opportunity_id}       what changes ("" empties a text field)
POST  /v1/opportunities/{opportunity_id}/stage {stage, probability?, lost_reason?, on?, note?}
GET   /v1/opportunities/pipeline               ?entity&closed_from&closed_to

A deal is with a customer (party, a customer of the entity; a vendor is not one) or with a prospect that is not a customer yet (prospect_name, prospect_country and a contact person on the deal). It gets the next number of its entity (OPP-000001), a kind (new_business, expansion, renewal), an expected net amount in a currency (by default the customer's, else the entity's functional currency), an expected close day, an owner (a person of the organization), a source and a next step.

An open stage takes the stage's default probability unless the request names one. won and lost set the close day (on, default today; not in the future and not before the deal was created). The weighted_amount of a deal is its amount times its probability. Each stage change writes a stage_change activity with the note, so the deal's timeline (GET /v1/activities?opportunity_id=) is its history. Deals are never deleted.

Activities and tasks

POST /v1/activities                        {opportunity_id | lead_id | entity + party, kind, subject, body?, occurred_on?, due_on?, assignee_user_id?}
GET  /v1/activities                        ?entity&opportunity_id&lead_id&party_id&kind&open_tasks&assignee_user_id
POST /v1/activities/{activity_id}/complete

An activity is about a deal (it takes the deal's entity and customer), about a customer only, or about a lead before it is anyone's customer (it names no deal, customer or contact and stays with the lead once converted, ADR-0095). kind is note, call, meeting, email or task; a task has a due day and an assignee (by default the deal's or the lead's owner) and is completed once. An activity is never edited or deleted. overdue is a task not done whose due day has passed (today, UTC). The open tasks list the earliest due first.

The pipeline

GET /v1/opportunities/pipeline?entity=CH01 sums the open deals by stage (in pipeline order) and currency: count, amount and weighted amount; the deals won and lost from closed_from (default 1 January) to closed_to (default today); and the entity's open and overdue tasks. Amounts are summed per currency and never converted: a pipeline is an expectation, and a conversion at one day's rate would show a precision it does not have. The sales reports convert each deal at one named ECB fixing for the forecast, quotas and the win rate, and keep the sums per currency beside it.

Who does what

Nothing here posts, approves or changes master data, so there is no approval step. Every change is in the audit trail: opportunity.create, opportunity.update (with the previous values; for the contact details, personal data, only whether they were set), opportunity.stage, activity.create, activity.complete.

Gmail and Google Calendar

A person links their own Google account on Gmail and Google Calendar (the person menu, Settings, or the button on Sales pipeline). From then on the e-mails they send and receive and the meetings they take part in are read every 15 minutes (or with Read now), the first time from the last 30 days, and each one with someone the CRM knows is logged on that timeline as an email or meeting activity:

Only exact addresses match, never a domain alone, and the organization's own people never do. One e-mail is logged once per deal or customer, also when a colleague who was on it has linked their account too (the Message-ID is the same in every mailbox). A meeting is logged once it has started. What is kept: the subject, who wrote to whom (or who took part, and when) and Google's short preview of the text, with a link to open it in Gmail or Google Calendar; never an attachment. Google is read read-only: nothing is ever sent.

GET    /v1/me/mailbox           whether this system offers the link, and your own link
POST   /v1/me/mailbox/google    {code}: link with the code of Google's consent popup
POST   /v1/me/mailbox/sync      read now
DELETE /v1/me/mailbox           unlink (Google takes the access back; what was logged stays)

Only the person, signed in, with the draft right, links their own account: never an API key or an agent. A test copy never reads a mailbox: it is refused a link, and a clone never copies one. The refresh token Google gives is sealed with the deployment's key and never exported. If Google stops accepting the link (revoked, password changed) the page says so and the person links again. The link is offered once the operator has set it up (deployment); the design is ADR-0036 section 9. Outlook is a later slice.

Mail to or from a support queue's inbox in a linked mailbox is also handed, with its full text, to the support desk, where it opens or continues a case.

Not yet

Lines with products and prices on a deal, turning a won deal into a subscription and renewal deals created by a subscription: later slices of ADR-0036. The people at customers are contacts of their own, which deals and activities name: contacts. Owners of customers, contacts and activities, sales teams and who sees whose records: sales teams. contacts of their own, which deals and activities name: contacts. The people who may become customers are leads, converted into a customer, its contact and a deal in one step, and come from website forms too: leads.