Deals & Pipeline API

Overview

The Deals & Pipeline API allows you to manage your sales pipeline programmatically. Create, update, and move deals through pipeline stages, manage multiple pipelines, and track deal activities and associated contacts.

List Deals

GET /v1/deals

Returns a paginated list of deals with support for filtering and sorting.

Query Parameters

pipeline_id (string) — Filter by pipeline.
stage_id (string) — Filter by specific stage.
owner_id (string) — Filter by deal owner (user ID).
status (string) — Filter: open, won, lost.
min_value (number) — Minimum deal value.
max_value (number) — Maximum deal value.
expected_close_after (string) — ISO 8601 date filter.
expected_close_before (string) — ISO 8601 date filter.
sort (string) — Sort options: created_at, value, expected_close_date, updated_at.
limit (integer) — Records per page. Default: 25, Max: 100.
cursor (string) — Pagination cursor.

Example Request

curl -X GET "https://app.automatenexuscrm.com/functions/v1/api/deals?status=open&sort=-value&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "deal_xyz789",
      "title": "Enterprise License - Acme Corp",
      "pipeline_id": "pipe_001",
      "stage_id": "stage_003",
      "stage_name": "Proposal Sent",
      "value": 75000,
      "currency": "USD",
      "probability": 60,
      "owner_id": "usr_abc123",
      "contact_id": "con_def456",
      "expected_close_date": "2026-04-15",
      "status": "open",
      "custom_fields": {
        "deal_type": "new_business",
        "competitors": "Salesforce, HubSpot"
      },
      "created_at": "2026-02-01T10:00:00Z",
      "updated_at": "2026-03-18T15:30:00Z"
    }
  ],
  "meta": {"total": 45, "limit": 20, "has_more": true}
}

Get a Deal

GET /v1/deals/:id

Returns complete details for a single deal including all custom fields, associated contacts, and stage history.

Create a Deal

POST /v1/deals

Request Body

title (string, required) — Deal title or name.
pipeline_id (string, required) — Pipeline to create the deal in.
stage_id (string) — Initial stage. Defaults to the first stage in the pipeline.
value (number) — Deal monetary value.
currency (string) — ISO 4217 currency code. Default: workspace currency.
contact_id (string) — Primary contact associated with this deal.
owner_id (string) — User ID of the deal owner.
expected_close_date (string) — Expected close date in YYYY-MM-DD format.
probability (integer) — Win probability percentage (0-100).
custom_fields (object) — Custom field key-value pairs.
tags (array) — Array of tag strings.

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",
    "pipeline_id": "pipe_001",
    "value": 24000,
    "currency": "USD",
    "contact_id": "con_abc123",
    "expected_close_date": "2026-05-01"
  }'

Update a Deal

PUT /v1/deals/:id

Update deal properties. Only include fields you want to change.

Delete a Deal

DELETE /v1/deals/:id

Permanently deletes a deal. This action cannot be undone.

Move Deal to Stage

PUT /v1/deals/:id/stage

Move a deal to a different pipeline stage. This is the recommended way to update deal stages as it properly triggers automations and records stage history.

curl -X PUT "https://app.automatenexuscrm.com/functions/v1/api/deals/deal_xyz789/stage" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stage_id": "stage_004", "note": "Client approved the proposal"}'

List Pipelines

GET /v1/pipelines

Returns all pipelines configured in your workspace.

{
  "success": true,
  "data": [
    {
      "id": "pipe_001",
      "name": "Sales Pipeline",
      "stages": [
        {"id": "stage_001", "name": "Lead", "position": 1, "probability": 10},
        {"id": "stage_002", "name": "Qualified", "position": 2, "probability": 25},
        {"id": "stage_003", "name": "Proposal", "position": 3, "probability": 50},
        {"id": "stage_004", "name": "Negotiation", "position": 4, "probability": 75},
        {"id": "stage_005", "name": "Closed Won", "position": 5, "probability": 100}
      ],
      "is_default": true
    }
  ]
}

Pipeline Stages

GET /v1/pipelines/:id/stages

Returns the stages for a specific pipeline with their positions, probabilities, and deal counts.

Deal Activities

GET /v1/deals/:id/activities

Returns all activities logged against a deal.

Deal Contacts

GET /v1/deals/:id/contacts

Returns all contacts associated with a deal, including their roles (decision maker, influencer, champion, etc.).

Win/Loss Tracking

Mark a deal as won or lost:

# Mark as won
curl -X PUT "https://app.automatenexuscrm.com/functions/v1/api/deals/deal_xyz789" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "won", "won_reason": "Best feature fit"}'

# Mark as lost
curl -X PUT "https://app.automatenexuscrm.com/functions/v1/api/deals/deal_xyz789" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "lost", "lost_reason": "Price too high", "competitor": "Salesforce"}'

Troubleshooting

Cannot move deal to stage: Ensure the target stage belongs to the same pipeline as the deal. Cross-pipeline stage moves are not supported — update the pipeline_id first.
Deal value not updating: Value must be a number, not a string. Send "value": 50000 not "value": "$50,000".
Contact association failing: Verify the contact ID exists and belongs to the same workspace.