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.

Authorization

apiKey

AuthorizationBearer <token>

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

In: header

Query Parameters

cursor?string

Opaque pagination cursor returned as next_cursor in a previous response. Pass this to fetch the next page.

limit?string

Maximum number of deals to return per page.

Default"20"

pipeline_id?string

Filter by pipeline ID (exact match).

Match^pp_

stage_id?string

Filter by stage ID (exact match).

Match^ps_

contact_id?string

Filter by linked contact ID (exact match).

Match^ct_

company_id?string

Filter by linked company ID (exact match).

Match^co_

tags?string

Filter by tags (comma-separated). Deals must contain all specified tags.

min_value?string

Filter deals with value greater than or equal to this amount.

max_value?string

Filter deals with value less than or equal to this amount.

sort?string

Comma-separated sort fields. Prefix with - for descending order. Supported fields: created_at, updated_at, value, expected_close_date. Default: -created_at.

Response Body

`application/json`

curl -X GET "https://api.nodestash.io/v1/deals?pipeline_id=pp_8rT4mK9pQsVwXyZaB2cD4&stage_id=ps_4kT9mN2qRsYvAzCeB2cD4&contact_id=ct_5hJ3kM9pQrVwXyZaB2cD4&company_id=co_7rT4mK9pQsVwXyZaB2cD4&tags=enterprise%2Cq2-target&min_value=10000&max_value=100000&sort=-value"

{
  "data": [
    {
      "id": "dl_3xK8nM2qTsYvAzCeB2cD4",
      "type": "deal",
      "attributes": {
        "id": "dl_3xK8nM2qTsYvAzCeB2cD4",
        "title": "Enterprise Contract",
        "value": "50000.00",
        "currency": "EUR",
        "pipeline_id": "pp_8rT4mK9pQsVwXyZaB2cD4",
        "stage_id": "ps_4kT9mN2qRsYvAzCeB2cD4",
        "contact_id": "ct_5hJ3kM9pQrVwXyZaB2cD4",
        "company_id": "co_7rT4mK9pQsVwXyZaB2cD4",
        "owner_id": null,
        "expected_close_date": "2026-06-30",
        "closed_at": null,
        "custom_fields": {
          "priority": "high"
        },
        "tags": [
          "enterprise",
          "q2-target"
        ],
        "created_at": "2026-02-01T14:00:00Z",
        "updated_at": "2026-02-01T14:00:00Z"
      }
    },
    {
      "id": "dl_9yL2mN4qTsWvBzDe6fH8",
      "type": "deal",
      "attributes": {
        "id": "dl_9yL2mN4qTsWvBzDe6fH8",
        "title": "Startup Onboarding",
        "value": "5000.00",
        "currency": "EUR",
        "pipeline_id": "pp_8rT4mK9pQsVwXyZaB2cD4",
        "stage_id": "ps_1aB2cD3eF4gH5iJ6kL7m",
        "contact_id": null,
        "company_id": "co_3xK8nM2qTsYvAzCe5fH7",
        "owner_id": null,
        "expected_close_date": "2026-03-15",
        "closed_at": null,
        "custom_fields": {},
        "tags": [
          "startup"
        ],
        "created_at": "2026-01-28T16:30:00Z",
        "updated_at": "2026-01-28T16:30:00Z"
      }
    }
  ],
  "meta": {
    "request_id": "req_abc123def456",
    "pagination": {
      "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMS0yOFQxNjozMDowMFoiLCJpZCI6ImRsXzl5TDJtTjRxVHNXdkJ6RGU2Zkg4In0",
      "has_more": true
    }
  }
}

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing or invalid Authorization header"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Authorization

Query Parameters

Response Body

200application/json

401application/json

429application/json

`application/json`

`application/json`

`application/json`