Skip to content

Deals & Pipeline API

Updated

On this page16

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 (see Deal Stages below).
  • limit (integer) — Records per page. 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",
      "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": null
    }
  ],
  "count": 1,
  "total": null
}

Each deal embeds its customer (id, name, email) and workspace (id, name). count is the number of records in this page; total is not computed for deals and is always null, so request further pages until a page returns fewer records than limit.

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.
  • stage (string) — One of the stages listed under Deal Stages. Default: lead.
  • probability (integer) — Win probability percentage (0-100).
  • expected_close_date (string) — Expected close date in YYYY-MM-DD format. Must be today or later.
  • description (string) — Free-text description.
  • customer_id (string) — ID of the customer record the deal belongs to.
  • assigned_to (string) — User ID of the deal owner.
  • close_reason (string) — Why the deal was won or lost.
  • closed_at (string) — ISO 8601 timestamp of when the deal closed.
  • custom_fields (object) — Custom field key-value pairs. Define the fields under Settings → Custom fields.

Fields that are not part of the deal record are rejected 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

Update deal properties. Only include fields you want to change. The response is the updated deal.

Delete a Deal#

DELETE /api/deals/:id

Permanently deletes a deal. This action cannot be undone. The response is {"message": "Deal deleted successfully"}.

Deal Stages#

A deal's position in the pipeline is its stage value. The accepted values are:

  • lead
  • qualified
  • discovery
  • demo
  • proposal
  • evaluation
  • negotiation
  • onboarding
  • closed_won
  • closed_lost

To move a deal, update its stage:

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": "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. There are no separate pipeline or stage endpoints.

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 (updates need each deal's id) creates or updates many deals 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, optionally filtered, for example "filters": {"stage": "closed_won"}.

Troubleshooting#

  • 400 mentioning deals_stage_check: The stage value is not one of the accepted stages. Use the underscore forms closed_won and closed_lost, 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 expected_close_date: The date must be today or later, in YYYY-MM-DD format.
  • 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.

Was this page helpful?