> ## Documentation Index > Fetch the complete documentation index at: https://docs.heffl.com/llms.txt > Use this file to discover all available pages before exploring further. # List deals > Returns a paginated list of deals. Supports cursor pagination, full-text search, structured filters (pipeline, stage, client, owner, status, tags, dates), and sorting. Results respect the API key user's ownership permissions. See the [Listing & filters](/api-v2/listing-and-filters) guide for filter syntax. ## OpenAPI ````yaml /openapi.v2.json get /deals openapi: 3.1.1 info: title: Heffl API v2 (Beta) version: 2.0.0 description: >- Heffl REST API v2 (beta) — resource-oriented endpoints with consistent response envelopes. Endpoints, schemas, and behavior may change until GA. See Agent workflows and ID prefixes guides for automation. contact: name: Heffl Support url: https://heffl.com/support email: support@heffl.com servers: - url: https://api.heffl.com/api/v2 description: Production API Server security: - ApiKeyAuth: [] paths: /deals: get: tags: - Objects summary: List deals description: >- Returns a paginated list of deals. Supports cursor pagination, full-text search, structured filters (pipeline, stage, client, owner, status, tags, dates), and sorting. Results respect the API key user's ownership permissions. See the [Listing & filters](/api-v2/listing-and-filters) guide for filter syntax. operationId: objects.deals.list parameters: - name: cursor in: query required: false schema: type: string description: >- Cursor for pagination. Pass the previous response meta.nextCursor value to fetch the next page. - name: pageSize in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 30 description: Number of items to return per page (max 100) - name: search in: query required: false schema: type: string description: Search by deal title, number, or client name - name: orderBy in: query required: false schema: type: string enum: - createdAt - position - expectedCloseDate - price default: createdAt description: Field to sort results by - name: orderDir in: query required: false schema: type: string enum: - asc - desc default: desc description: Sort direction - name: filters in: query required: false schema: type: object description: >- Structured filters. Each key is a filter field with operator and values. Option fields use string IDs; date fields use ISO 8601 date-time strings. See the Listing & filters guide. properties: clientId: type: object properties: operator: type: string enum: - is - is_not - is_any_of - is_none_of values: type: array items: type: string description: Contact or company ID (e.g. clt_abc123) pipelineId: type: object properties: operator: type: string enum: - is - is_not - is_any_of - is_none_of values: type: array items: type: string description: Pipeline ID (e.g. dpl_abc123) stageId: type: object properties: operator: type: string enum: - is - is_not - is_any_of - is_none_of values: type: array items: type: string description: Pipeline stage ID (e.g. dps_abc123) status: type: object properties: operator: type: string enum: - is - is_not - is_any_of - is_none_of values: type: array items: type: string enum: - ACTIVE - WON - LOST priority: type: object properties: operator: type: string enum: - is - is_not - is_any_of - is_none_of values: type: array items: type: string enum: - LOW - MEDIUM - HIGH ownerUserId: type: object properties: operator: type: string enum: - is - is_not - is_any_of - is_none_of values: type: array items: type: string description: Owner user ID (e.g. usr_abc123) crmSourceId: type: object properties: operator: type: string enum: - is - is_not - is_any_of - is_none_of values: type: array items: type: string description: Source ID (e.g. src_abc123) createdById: type: object properties: operator: type: string enum: - is - is_not - is_any_of - is_none_of values: type: array items: type: string description: Creator user ID (e.g. usr_abc123) listId: type: object properties: operator: type: string enum: - is - is_not - is_any_of - is_none_of values: type: array items: type: string description: List ID (e.g. lst_abc123) tagId: type: object properties: operator: type: string enum: - include - exclude - include_any_of - include_all_of - exclude_if_any_of - exclude_if_all values: type: array items: type: string description: Tag ID (e.g. tag_abc123) services: type: object properties: operator: type: string enum: - include - exclude - include_any_of - include_all_of - exclude_if_any_of - exclude_if_all values: type: array items: type: string description: Product ID (e.g. prd_abc123) createdAt: type: object properties: operator: type: string enum: - is - is_not - is_before - is_after - is_on_or_before - is_on_or_after - is_between - is_not_between values: type: array items: type: string format: date-time expectedCloseDate: type: object properties: operator: type: string enum: - is - is_not - is_before - is_after - is_on_or_before - is_on_or_after - is_between - is_not_between values: type: array items: type: string format: date-time style: deepObject explode: true responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Deal' meta: $ref: '#/components/schemas/ListMeta' required: - data - meta '400': description: Validation error or bad request content: application/json: schema: $ref: '#/components/schemas/V2ApiError' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/V2ApiError' '403': description: Insufficient permission content: application/json: schema: $ref: '#/components/schemas/V2ApiError' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/V2ApiError' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/V2ApiError' components: schemas: Deal: type: object properties: id: type: string description: Deal ID number: type: string description: Auto-generated deal number title: type: string description: Deal title clientId: anyOf: - type: string - type: 'null' description: Contact or company ID (clt_ prefix) client: anyOf: - type: object - type: 'null' description: Linked client record price: anyOf: - type: number - type: 'null' description: Deal value expectedCloseDate: anyOf: - type: string format: date-time - type: 'null' description: Expected close date status: anyOf: - type: string enum: - ACTIVE - WON - LOST - type: 'null' description: Deal status priority: anyOf: - type: string enum: - LOW - MEDIUM - HIGH - type: 'null' description: Deal priority pipelineId: anyOf: - type: string - type: 'null' description: Pipeline ID (dpl_ prefix) stageId: anyOf: - type: string - type: 'null' description: Pipeline stage ID (dps_ prefix) stage: anyOf: - type: string - type: 'null' description: Pipeline stage name leadId: anyOf: - type: string - type: 'null' description: Lead ID leadName: anyOf: - type: string - type: 'null' description: Lead name crmSourceId: anyOf: - type: string - type: 'null' description: CRM source ID (src_ prefix) source: anyOf: - type: string - type: 'null' description: CRM source name ownerUserId: anyOf: - type: string - type: 'null' description: Owner user ID (usr_ prefix) ownerId: anyOf: - type: string - type: 'null' description: Owner user ID (usr_ prefix) ownerName: anyOf: - type: string - type: 'null' description: Owner name contactEmails: type: array items: type: string description: Emails of linked contacts createdAt: anyOf: - type: string format: date-time - type: 'null' description: When the deal was created updatedAt: anyOf: - type: string format: date-time - type: 'null' description: When the deal was last updated required: - id - number - title - contactEmails additionalProperties: description: >- Custom field values as top-level cf_* keys (for example cf_priority). There is no customFields wrapper. ListMeta: type: object properties: nextCursor: type: - string - 'null' description: Cursor to fetch the next page. Null if there are no more results. hasMore: type: boolean description: Whether additional results are available required: - hasMore V2ApiError: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string details: type: object securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- API key for authentication. Get yours at app.heffl.com/settings/developers ````