Overview#
The Deals & Pipeline API allows you to manage your sales pipeline programmatically. Create and update deals, move them through the pipeline by changing their stage, and mark them won or lost. Deals are the records you see under CRM → Deals. Every request needs an API key in the Authorization header; see API Overview & Authentication.
List Deals#
GET /api/dealsReturns deals newest first, 50 per page unless you pass limit.
Query Parameters#
- stage (string) — Filter by stage, using the stage's slug (see Deal Stages below).
- limit (integer) — Records per page, from 1 to 1,000. Default: 50.
- offset (integer) — Records to skip. Default: 0.
Example Request#
curl -X GET "https://app.automatenexuscrm.com/functions/v1/api/deals?stage=negotiation&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"Example Response#
{
"data": [
{
"id": "6d2f8b4a-1c3e-4f5a-9b7c-8d9e0f1a2b3c",
"title": "Enterprise License - Acme Corp",
"description": "Annual license for 200 seats",
"value": 75000,
"currency": "USD",
"stage": "negotiation",
"probability": 60,
"expected_close_date": "2026-04-15",
"customer_id": "8a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"assigned_to": "b7e3c1d2-5f6a-4b8c-9d0e-1f2a3b4c5d6e",
"workspace_id": "e4b1c9a0-2d3f-4e5a-9b8c-7d6e5f4a3b2c",
"close_reason": null,
"closed_at": null,
"custom_fields": {
"deal_type": "new_business"
},
"created_at": "2026-02-01T10:00:00Z",
"updated_at": "2026-03-18T15:30:00Z",
"customer": {
"id": "8a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"name": "Acme Corp",
"email": "billing@acme.example"
},
"workspace": {
"id": "e4b1c9a0-2d3f-4e5a-9b8c-7d6e5f4a3b2c",
"name": "Main"
}
}
],
"count": 1,
"total": 1,
"pagination": { "count": 1, "total": 1, "offset": 0, "limit": 20, "has_more": false }
}Each deal embeds its customer (id, name, email) and workspace (id, name). count is the number of records in this page and total the number that match; request further pages until pagination.has_more is false.
Get a Deal#
GET /api/deals/:idReturns a single deal with the same fields and embedded objects. Returns 404 when no deal with that ID exists in your organization.
Create a Deal#
POST /api/dealsRequest Body#
- title (string, required) — Deal title or name.
- value (number) — Deal monetary value. Must be zero or more.
- currency (string) — ISO 4217 currency code, for example
USD. Left out, the deal takes its workspace's currency. - stage (string) — The slug of one of your pipeline stages (see Deal Stages). Default:
lead. - probability (integer) — Win probability percentage (0-100).
- expected_close_date (string) — Expected close date in YYYY-MM-DD format.
- description (string) — Free-text description.
- customer_id (string) — ID of the customer record the deal belongs to, in your organization.
- assigned_to (string) — User ID of the deal owner, a member of your organization (
GET /api/userslists them). - workspace_id (string) — The workspace the deal belongs to (
GET /api/workspaces). Left out, the deal goes to your main workspace. - close_reason (string) — Why the deal was won or lost.
- closed_at (string) — ISO 8601 timestamp of when the deal closed.
- custom_fields (object) — Your own fields, by field key. Define them under Settings → Custom fields;
GET /api/custom-fields?entity_type=deallists the keys.
Fields the API does not write are left out of the deal and named in the X-Ignored-Fields response header; they are not an error. An ID that is not a UUID, or that is not a record or member of your organization, is refused with 400. The response is 201 with the created deal.
Example#
curl -X POST "https://app.automatenexuscrm.com/functions/v1/api/deals" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Premium Plan - TechStart Inc",
"value": 24000,
"currency": "USD",
"stage": "qualified",
"customer_id": "8a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"expected_close_date": "2026-11-01"
}'Update a Deal#
PUT /api/deals/:id
PATCH /api/deals/:idUpdate deal properties. Only include fields you want to change. The response is the updated deal. PUT replaces the whole custom_fields object with the one you send; PATCH merges the keys you send into the ones already there and removes a key you send as null.
Delete a Deal#
DELETE /api/deals/:idPermanently deletes a deal. A deal deleted through the API does not go to Recently deleted, so this cannot be undone. The response is {"message": "Deal deleted successfully"}, or 404 ("Deal not found") when no deal with that ID exists in your organization.
Deal Stages#
A deal's position in the pipeline is its stage value: the slug of one of your organization's pipeline stages. GET /api/stages lists your stages in board order, each with its slug (the value a deal's stage holds), name, position, color, win_probability, is_closed_won, and is_closed_lost:
curl -X GET "https://app.automatenexuscrm.com/functions/v1/api/stages" \
-H "Authorization: Bearer YOUR_API_KEY"These built-in slugs are always accepted:
leadqualifieddiscoverydemoproposalevaluationnegotiationonboardingclosed_wonclosed_lost
A stage you add in Manage pipeline stages (the Stages button on the board under CRM → Deals) has a slug of its own: use the slug from GET /api/stages, not the stage's name. A renamed stage keeps its slug, so its deals keep their stage.
To move a deal, update its stage:
curl -X PATCH "https://app.automatenexuscrm.com/functions/v1/api/deals/6d2f8b4a-1c3e-4f5a-9b7c-8d9e0f1a2b3c" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"stage": "proposal"}'A stage change delivers the deal.stage_changed webhook event (as well as deal.updated) to any webhook subscribed to it; see the Webhooks API. Stages are read through /api/stages; they are added, renamed, and reordered on the board.
Win/Loss Tracking#
Mark a deal as won or lost by moving it to closed_won or closed_lost. Add close_reason to record why, and closed_at if you want the closing time stored:
# Mark as won
curl -X PUT "https://app.automatenexuscrm.com/functions/v1/api/deals/6d2f8b4a-1c3e-4f5a-9b7c-8d9e0f1a2b3c" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"stage": "closed_won", "close_reason": "Best feature fit", "closed_at": "2026-04-10T16:00:00Z"}'
# Mark as lost
curl -X PUT "https://app.automatenexuscrm.com/functions/v1/api/deals/6d2f8b4a-1c3e-4f5a-9b7c-8d9e0f1a2b3c" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"stage": "closed_lost", "close_reason": "Price too high"}'Deal Notes#
GET /api/notes?target_type=deal&target_id=:id
POST /api/notesAttach plain-text notes to a deal by creating a note with "target_type": "deal" and the deal's ID as target_id. Provide at least a title or body_text. Listing with the same two parameters returns the deal's notes, newest first.
Search, Bulk, and Export#
- Search:
GET /api/search?q=acme&entities=dealsmatches deal titles and descriptions and returns up tolimitdeals (default 10) underresults.deals. - Bulk:
POST /api/bulkwith"entity_type": "deals","operation": "create"or"update", and adataarray of up to 200 deals (updates need each deal'sid) creates or updates them in one request and reportssuccess_countanderror_count. - Export:
POST /api/exportwith"entity_type": "deals"and"format": "json"or"csv"returns every deal (up to 50,000), optionally filtered, for example"filters": {"stage": "closed_won"}.
Troubleshooting#
- 400 "The stage … isn't one of this organization's pipeline stages": Use a slug from
GET /api/stages. The built-in closed stages areclosed_wonandclosed_lost, with underscores, not hyphens. - Deal value not updating: Value must be a number, not a string. Send
"value": 50000not"value": "$50,000". Negative values are rejected. - 400 on
probability: The value must be between 0 and 100. - Customer association failing:
customer_idmust be the ID of an existing customer record in the same organization as the API key; otherwise the answer is400"customer_id … not found in this organization". - A field you sent did not change: Read the
X-Ignored-Fieldsresponse header. It names each field the API left out, for example a misspelled name. Deals carry no tags through the API.