nodestash
Deals

Update a deal

Partially updates a deal. Only the provided fields are changed — omitted fields remain untouched. `custom_fields` are **merged** with existing values (not replaced). When `stage_id` is changed, the stage must belong to the deal's current pipeline. `closed_at` is automatically set when moving to a `won` or `lost` stage and cleared when moving back to an `open` stage.

PATCH
/deals/{id}

Authorization

apiKey
AuthorizationBearer <token>

API key from your nodestash dashboard. Pass as a Bearer token in the Authorization header.

In: header

Path Parameters

id*string

Deal ID (prefixed with dl_).

Match^dl_

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://api.nodestash.io/v1/deals/dl_3xK8nM2qTsYvAzCeB2cD4" \  -H "Content-Type: application/json" \  -d '{    "title": "Enterprise Contract - Renewal",    "value": 75000,    "stage_id": "ps_5dE6fG7hI8jK9lM1nO2p",    "tags": [      "enterprise",      "q2-target",      "upsell"    ]  }'
{
  "data": {
    "id": "dl_3xK8nM2qTsYvAzCeB2cD4",
    "type": "deal",
    "attributes": {
      "id": "dl_3xK8nM2qTsYvAzCeB2cD4",
      "title": "Enterprise Contract - Renewal",
      "value": "75000.00",
      "currency": "EUR",
      "pipeline_id": "pp_8rT4mK9pQsVwXyZaB2cD4",
      "stage_id": "ps_5dE6fG7hI8jK9lM1nO2p",
      "contact_id": "ct_5hJ3kM9pQrVwXyZaB2cD4",
      "company_id": "co_7rT4mK9pQsVwXyZaB2cD4",
      "owner_id": null,
      "expected_close_date": "2026-06-30",
      "closed_at": "2026-02-20T16:45:00Z",
      "custom_fields": {
        "priority": "high"
      },
      "tags": [
        "enterprise",
        "q2-target",
        "upsell"
      ],
      "created_at": "2026-02-01T14:00:00Z",
      "updated_at": "2026-02-20T16:45:00Z"
    }
  },
  "meta": {
    "request_id": "req_7gH8iJ9kL1mN2oP3qR4s"
  }
}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email"
      }
    ]
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing or invalid Authorization header"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Contact not found"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

List deals

Returns a paginated list of deals in the authenticated workspace. Supports cursor-based pagination, filtering by pipeline, stage, contact, company, tags, and value range, as well as configurable sorting.

Create a new pipeline

Creates a new pipeline with stages in the authenticated workspace. The `stages` array must contain at least one stage of type `won` and one of type `lost`. Stages are ordered by their `position` field.