The short answer
To manage existing Mautic deals through an API, authenticate with Mautic Basic Auth and call the documented deal routes to list or inspect records, update fields, move a deal to another stage, add notes or tasks, read its timeline, or import a CSV. The documented surface does not include POST /api/dealflow/deals for creating one deal. Use the CSV import route for bulk ingestion; use the n8n node when a workflow needs to create one deal programmatically.
Deal Flow exposes these operations under /api/dealflow/ on your own Mautic instance. This guide stays inside the published API surface and does not assume undocumented response shapes.
Scope: this is an operational guide for documented routes. It is not a generated client reference, and every example deliberately shows the request only.
Authenticate once with Mautic Basic Auth
Set the instance URL and credentials in your shell, then reuse them in each request. Replace the example values locally; do not put working credentials in this page or a shared script.
export MAUTIC_URL="https://mautic.example.com"
export MAUTIC_USER="your-username"
export MAUTIC_PASSWORD="your-password"
Every cURL command below sends those credentials with --user. Your Mautic user also needs permission to perform the requested Deal Flow action.
The documented deal-management routes
Endpoint and field names checked August 21, 2026 against the published Deal Flow API reference and the product domain specification.
| Method | Route | Operation |
|---|---|---|
| GET | /api/dealflow/deals | List deals |
| GET | /api/dealflow/deals/{id} | Get one deal |
| PATCH | /api/dealflow/deals/{id} | Update a deal |
| POST | /api/dealflow/deals/{id}/stage | Move its stage |
| POST | /api/dealflow/deals/{id}/notes | Add a note |
| POST | /api/dealflow/deals/{id}/tasks | Add a task |
| GET | /api/dealflow/deals/{id}/timeline | Get its timeline |
| POST | /api/dealflow/deals/import | Import a CSV |
List and inspect existing deals
Use the collection route to list deals. The domain specification does not define query parameters or a response envelope, so this example adds neither.
List deals
curl --user "$MAUTIC_USER:$MAUTIC_PASSWORD" \
--request GET \
"$MAUTIC_URL/api/dealflow/deals"
Get one deal by ID
Replace 42 with the existing deal ID you want to inspect.
curl --user "$MAUTIC_USER:$MAUTIC_PASSWORD" \
--request GET \
"$MAUTIC_URL/api/dealflow/deals/42"
Update a deal or move its stage
Deal updates and stage moves use separate documented routes. The examples below use field names from the Deal entity in the domain specification.
Update documented deal fields
curl --user "$MAUTIC_USER:$MAUTIC_PASSWORD" \
--request PATCH \
--header "Content-Type: application/json" \
--data '{"title":"Renewal opportunity","expected_close_date":"2026-09-30T17:00:00Z"}' \
"$MAUTIC_URL/api/dealflow/deals/42"
Move the deal to a documented stage ID
curl --user "$MAUTIC_USER:$MAUTIC_PASSWORD" \
--request POST \
--header "Content-Type: application/json" \
--data '{"stage_id":5}' \
"$MAUTIC_URL/api/dealflow/deals/42/stage"
Add notes and tasks, then read the timeline
Notes and tasks have their own endpoints. The request keys shown here are fields documented for the DealNote and DealTask entities.
Add a note
curl --user "$MAUTIC_USER:$MAUTIC_PASSWORD" \
--request POST \
--header "Content-Type: application/json" \
--data '{"body":"Proposal sent to procurement.","activity_type":"note"}' \
"$MAUTIC_URL/api/dealflow/deals/42/notes"
Add a task
curl --user "$MAUTIC_USER:$MAUTIC_PASSWORD" \
--request POST \
--header "Content-Type: application/json" \
--data '{"title":"Review procurement reply","due_at":"2026-09-01T14:00:00Z"}' \
"$MAUTIC_URL/api/dealflow/deals/42/tasks"
Read the deal timeline
curl --user "$MAUTIC_USER:$MAUTIC_PASSWORD" \
--request GET \
"$MAUTIC_URL/api/dealflow/deals/42/timeline"
Get deals in through CSV import
The documented bulk-ingestion route is POST /api/dealflow/deals/import. Send a CSV file to that route; the canonical domain specification names the route but does not publish mapping parameters or a response schema, so this example does not add either.
curl --user "$MAUTIC_USER:$MAUTIC_PASSWORD" \
--request POST \
--form "file=@deals.csv" \
"$MAUTIC_URL/api/dealflow/deals/import"
Creating one deal is different. The documented REST table does not include a single-deal create endpoint. If a workflow needs to create one record programmatically, follow the Mautic deals with n8n guide.
Manage deal operations inside Mautic
Deal Flow adds pipeline and buying-committee workflows to your Mautic instance.
See Deal Flow options Try free for 7 daysFrequently asked questions
Does the Deal Flow API document a create-deal endpoint?
No. The documented REST surface does not include POST /api/dealflow/deals. For bulk ingestion, use POST /api/dealflow/deals/import. For a workflow that creates one deal programmatically, use the Deal Flow n8n node guide.
How does Basic Auth work in these examples?
Pass your Mautic username and password with curl's --user option. Store them in environment variables rather than writing credentials into scripts or shell history.
Can the API move a deal and record follow-up work?
Yes. The documented routes include POST /api/dealflow/deals/{id}/stage, POST /api/dealflow/deals/{id}/notes, and POST /api/dealflow/deals/{id}/tasks.
How do I add many deals at once?
The documented bulk route is POST /api/dealflow/deals/import for CSV import. The current domain specification does not publish an example response shape, so this guide does not invent one.