# Simple CRM

The pipelines and deals in Victoria AI's Simple CRM, what a deal links to, what happens on a booked meeting, and the CRM endpoints.

The Simple CRM tracks deals through pipelines. An organization has 1 or more pipelines, each with its own stages, and 1 of them is the default for new deals.

## Deals

A deal has a name, a value in dollars, a win probability from 0 to 100, an expected close date, an actual close date once it closes, an owner (a member of your organization), notes and custom fields. Each deal links to 1 lead.

A booked meeting moves the lead's existing deal forward. A positive reply does not create a deal on its own; you create deals yourself, in the app, by API, or through a connected assistant. There are no company records: a deal belongs to a lead, and the company is a field on the lead.

## Pipelines and stages by API

| Task | Endpoint | Scope |
| - | - | - |
| List active pipelines | [`GET /v1/crm/pipelines`](https://docs.versionseven.ai/api-reference/crm-pipelines/list-pipelines) | `crm:read` |
| Retrieve a pipeline with its stages | [`GET /v1/crm/pipelines/{pipeline_id}`](https://docs.versionseven.ai/api-reference/crm-pipelines/retrieve-pipeline) | `crm:read` |
| Rename a pipeline, make it the default, or hide it | [`PATCH /v1/crm/pipelines/{pipeline_id}`](https://docs.versionseven.ai/api-reference/crm-pipelines/update-pipeline) | `crm:write` |

Listing pipelines doesn't include stages; retrieve the pipeline to get them, in display order, each with an `id`, `name` and `display_order`. Setting `is_default: true` on a pipeline makes every other pipeline non-default. The API doesn't create pipelines or stages, and doesn't rename or reorder stages; that happens in the app.

## Deals by API

| Task | Endpoint | Scope |
| - | - | - |
| List deals | [`GET /v1/crm/deals`](https://docs.versionseven.ai/api-reference/crm-deals/list-deals) | `crm:read` |
| Create a deal | [`POST /v1/crm/deals`](https://docs.versionseven.ai/api-reference/crm-deals/create-deal) | `crm:write` |
| Retrieve a deal | [`GET /v1/crm/deals/{deal_id}`](https://docs.versionseven.ai/api-reference/crm-deals/retrieve-deal) | `crm:read` |
| Update a deal or move it to a stage | [`PATCH /v1/crm/deals/{deal_id}`](https://docs.versionseven.ai/api-reference/crm-deals/update-deal) | `crm:write` |

Listing deals returns them newest first, each with a summary of its lead, filtered by `stage_id`, `owner_id` or `lead_id`, and paged with `limit` and `offset`.

Creating a deal takes a `name` and either `lead_id` for an existing lead or an inline `lead` to create one with the deal, never both. `stage_id` defaults to the first stage in the pipeline. `value`, `probability`, `expected_close_date`, `owner_id`, `notes` and `metadata` are optional. The request accepts an `Idempotency-Key` header, which makes a retry safe (see [Idempotency](https://docs.versionseven.ai/guides/idempotency)). A `lead_id`, `stage_id` or `owner_id` that isn't in your organization answers `400 INVALID_LEAD`, `INVALID_STAGE` or `INVALID_OWNER`.

Updating a deal changes only the fields you send. `stage_id` moves it to another stage, and `actual_close_date` records when it closed. The API doesn't delete deals.

Going the other way, [Add CRM contacts to a campaign](https://docs.versionseven.ai/cookbook/add-crm-contacts) is a complete script that takes contacts exported from another CRM and enrols them in a Victoria AI campaign.

## From a connected assistant

An assistant connected over MCP reads pipelines and deals with `pipelines_lookup`, `deals_lookup` and `deal_detail`, and creates or updates deals with `create_deal` and `update_deal`. The writes are annotated as such, so the host asks for your approval before each one runs. `create_deal` acts as a person: the user who connected, or, with an API key, the user who generated it. [Connect your AI](https://docs.versionseven.ai/guides/connect-your-ai) covers the setup.