Authentication
Deal Flow uses Mautic®'s built-in authentication. All API calls must be made with credentials that have the appropriate Deal Flow permissions.
HTTP Basic Auth
curl -u "your_username:your_password" \
https://your-mautic.com/deal-flow/1/view
OAuth2
Mautic supports OAuth2 for API access. Configure your client in Mautic → Settings → API Credentials, then pass the Bearer token in your requests.
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://your-mautic.com/deal-flow/1/view
The API is available at your Mautic instance URL. There is no separate Deal Flow API server. All requests go through Mautic's routing layer.
Deals
Returns a paginated list of deals visible to the authenticated user.
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | optional | Page number, default 1 |
Returns a single deal by ID, including its stage, pipeline, contacts, notes, and tasks.
| Parameter | Type | Required | Description |
|---|---|---|---|
objectId | integer | required | Deal ID |
Creates a new deal. Submit as a form POST with the deal fields.
| Field | Type | Required | Description |
|---|---|---|---|
deal[title] | string | required | Deal title |
deal[amount] | decimal | optional | Deal value |
deal[pipeline] | integer | optional | Pipeline ID |
deal[stage] | integer | optional | Stage ID |
deal[closeDate] | date | optional | Expected close date (YYYY-MM-DD) |
deal[owner] | integer | optional | Mautic user ID |
Updates an existing deal. Accepts the same fields as the create endpoint. Only include fields you want to change.
Moves a deal to a different stage. Triggers a stage change audit event and syncs deal status.
| Field | Type | Required | Description |
|---|---|---|---|
stage_id | integer | required | Target stage ID |
Moving a deal to a stage with type won or lost automatically updates the deal's status field.
Updates a single deal field inline (used by the deal detail view's click-to-edit). Returns JSON with the updated value.
| Field | Type | Required | Description |
|---|---|---|---|
field | string | required | Field name (e.g. title, amount) |
value | mixed | required | New value |
Performs a batch action (delete, change owner, change stage) on multiple deals at once.
| Field | Type | Required | Description |
|---|---|---|---|
ids[] | integer[] | required | Array of deal IDs |
action | string | required | delete, reassign, or move_stage |
Stages
Returns all pipeline stages visible to the authenticated user.
Pipelines
Returns all pipelines. Each pipeline contains its stages in order.
Contacts (Buying Committee)
Associates a Mautic contact with a deal, optionally assigning a role in the buying committee.
| Field | Type | Required | Description |
|---|---|---|---|
contact_id | integer | required | Mautic contact ID |
role | string | optional | Role label (e.g. Champion, Economic Buyer) |
is_primary | boolean | optional | Whether this is the primary contact |
Removes a contact from a deal's buying committee.
Notes
Adds a note to a deal. Note body supports HTML (sanitized on save).
| Field | Type | Required | Description |
|---|---|---|---|
note[body] | string (HTML) | required | Note content |
Tasks
Creates a task associated with a deal.
| Field | Type | Required | Description |
|---|---|---|---|
task[title] | string | required | Task title |
task[dueDate] | date | optional | Due date (YYYY-MM-DD) |
task[assignee] | integer | optional | Mautic user ID to assign to |
Marks a task as complete. Returns JSON {"success": true}.
Error Responses
Deal Flow follows Mautic's error response conventions. HTTP status codes indicate the result:
| Status | Meaning |
|---|---|
200 | Success |
403 | Insufficient permissions |
404 | Deal or resource not found |
422 | Validation error — check response body for field errors |
500 | Server error — check Mautic logs |
The interactive API documentation is also available inside your Mautic installation at Deal Flow → Settings → API Docs.