Skip to content
SAVE4545% off every plan.See the offer

API ReferenceDeals & Pipeline API

Deals & Pipeline API

On this page· 16

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/deals

Returns 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/:id

Returns 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/deals

Request 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/users lists 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=deal lists 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/:id

Update 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/:id

Permanently 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:

  • lead
  • qualified
  • discovery
  • demo
  • proposal
  • evaluation
  • negotiation
  • onboarding
  • closed_won
  • closed_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/notes

Attach 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=deals matches deal titles and descriptions and returns up to limit deals (default 10) under results.deals.
  • Bulk: POST /api/bulk with "entity_type": "deals", "operation": "create" or "update", and a data array of up to 200 deals (updates need each deal's id) creates or updates them in one request and reports success_count and error_count.
  • Export: POST /api/export with "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 are closed_won and closed_lost, with underscores, not hyphens.
  • Deal value not updating: Value must be a number, not a string. Send "value": 50000 not "value": "$50,000". Negative values are rejected.
  • 400 on probability: The value must be between 0 and 100.
  • Customer association failing: customer_id must be the ID of an existing customer record in the same organization as the API key; otherwise the answer is 400 "customer_id … not found in this organization".
  • A field you sent did not change: Read the X-Ignored-Fields response header. It names each field the API left out, for example a misspelled name. Deals carry no tags through the API.

Was this page helpful?

Last updated