> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opennous.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# List deals

> Deals, CRM and implied, filtered and paginated. Read-only. The CRM is the source of truth. A member key sees deals on its own accounts.

Deals are read-only. Your CRM is the source of truth, and OpenNous reads it.

## Implied deals

An account with no CRM deal still has a deal, its implied deal. That covers workspaces without a CRM and accounts the CRM has no deal for. An implied deal has the id `implied:<account_id>` and `implied: true`. Its stage is the account's stage, and it has no pipeline or close date. It works anywhere a deal id does, in [get a deal](/public-api/deals/get) and as the `focus` of [get context](/public-api/context).

## How the objects fit

| Object | Created by | Linked to | `stage` means |
| - | - | - | - |
| Person | Activity from your connected tools | The account they work at, and the deals they are on | How far that person's thread has gone |
| Account | Activity, or the CRM | Its people and its deals | The furthest stage among its people |
| Deal | Your CRM, or implied for an account without one | One account, and its stakeholders | The CRM stage, mapped onto the standard ladder as `canonical_stage` |

All three share the standard ladder. See [list pipelines](/public-api/deals/pipelines) for how your CRM stages map onto it.

```bash theme={"theme":{"light":"github-light-default","dark":"vesper"}}
curl "https://api.opennous.cloud/v2/deals?status=open&closing_within_days=30&sort=win_probability" \
  -H "Authorization: Bearer $NOUS_API_KEY"
```


## OpenAPI

````yaml GET /v2/deals
openapi: 3.1.0
info:
  title: OpenNous REST API
  version: 2.0.0
  description: >-
    Read and write the OpenNous revenue context graph over HTTP. Authenticate
    with a workspace API key.
servers:
  - url: https://api.opennous.cloud
    description: OpenNous Cloud
security:
  - bearerAuth: []
  - apiKeyHeader: []
tags:
  - name: People
  - name: Accounts
  - name: Deals
  - name: Notes
  - name: Attention
  - name: Insights
  - name: Enrich & score
  - name: Organization
  - name: Workflows
  - name: Webhooks
    description: >-
      Subscribe to events and have them pushed to your own stack, with the
      account record attached.
  - name: Usage
paths:
  /v2/deals:
    get:
      tags:
        - Deals
      summary: List deals
      description: >-
        Deals, CRM and implied, filtered and paginated. Read-only. The CRM is
        the source of truth. A member key sees deals on its own accounts.
      operationId: listDeals
      parameters:
        - name: account
          in: query
          required: false
          schema:
            type: string
          description: Only one account's deals. Entity UUID or domain.
        - name: pipeline
          in: query
          required: false
          schema:
            type: string
          description: CRM pipeline id. Excludes implied deals.
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - open
              - won
              - lost
          description: Deal status.
        - name: stage
          in: query
          required: false
          schema:
            type: string
            enum:
              - identified
              - connected
              - interested
              - meeting_booked
              - discovery
              - demo
              - negotiation
              - closed_won
              - closed_lost
              - disqualified
              - churned
          description: Standard stage (`canonical_stage`).
        - name: owner
          in: query
          required: false
          schema:
            type: string
          description: CRM owner. An email or a name.
        - name: closing_within_days
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 3650
          description: >-
            Open deals with a close date from today to N days out. Excludes
            implied deals.
        - name: min_amount
          in: query
          required: false
          schema:
            type: number
          description: Minimum amount.
        - name: implied
          in: query
          required: false
          schema:
            type: boolean
          description: '`true` for implied deals only, `false` for CRM deals only.'
        - name: sort
          in: query
          required: false
          schema:
            type: string
            enum:
              - last_activity
              - close_date
              - amount
              - win_probability
            default: last_activity
          description: >-
            `close_date` is soonest first. The others are highest or newest
            first.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 200
          description: Page size.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
          description: Rows to skip.
      responses:
        '200':
          description: A page of deals.
          content:
            application/json:
              schema:
                type: object
                properties:
                  deals:
                    type: array
                    items:
                      $ref: '#/components/schemas/DealSummary'
                  limit:
                    type: integer
                  offset:
                    type: integer
                  has_more:
                    type: boolean
              example:
                deals:
                  - id: d3c1b2a0-5e4f-4a7b-9c8d-1e2f3a4b5c6d
                    name: Acme — 40 seats
                    account:
                      entity_id: 3e7a1d52-8c4b-4b9e-a0f3-6d2c9e8b7a15
                      name: Acme
                      domain: acme.com
                    stage: Discovery call
                    canonical_stage: discovery
                    status: open
                    amount: 48000
                    currency: USD
                    close_date: '2026-11-15'
                    owner:
                      name: Jordan Lee
                      email: jordan@yourco.com
                    pipeline:
                      id: default
                      name: Sales pipeline
                    health: 71
                    win_probability: 0.42
                    close_within_30d: 0.18
                    last_activity_at: '2026-09-24T15:02:00Z'
                    implied: false
                  - id: implied:3e7a1d52-8c4b-4b9e-a0f3-6d2c9e8b7a15
                    name: Acme deal
                    account:
                      entity_id: 3e7a1d52-8c4b-4b9e-a0f3-6d2c9e8b7a15
                      name: Acme
                      domain: acme.com
                    stage: Discovery
                    canonical_stage: discovery
                    status: open
                    amount: null
                    currency: null
                    close_date: null
                    owner:
                      name: Jordan Lee
                      email: jordan@yourco.com
                    pipeline: null
                    health: 71
                    win_probability: 0.42
                    close_within_30d: 0.18
                    last_activity_at: '2026-09-24T15:02:00Z'
                    implied: true
                limit: 50
                offset: 0
                has_more: false
        '400':
          description: A bad query parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unknown_query_param:
                  summary: unknown_query_param
                  value:
                    error: unknown_query_param
                    detail: 'unsupported query param(s): foo'
                    supported:
                      - account
                      - pipeline
                      - ...
                invalid_status:
                  summary: invalid_status
                  value:
                    error: invalid_status
                    detail: status must be one of open, won, lost
                invalid_stage:
                  summary: invalid_stage
                  value:
                    error: invalid_stage
                    supported:
                      - identified
                      - connected
                      - interested
                      - meeting_booked
                      - discovery
                      - demo
                      - negotiation
                      - closed_won
                      - closed_lost
                      - disqualified
                      - churned
                ambiguous_account:
                  summary: ambiguous_account
                  value:
                    error: ambiguous_account
                    detail: >-
                      that name matches several records; pass an entity id or a
                      domain
                    candidates: []
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/UpgradeRequired'
        '404':
          description: '`account` matches no account visible to this key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: account_not_found
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    DealSummary:
      type: object
      properties:
        id:
          type: string
          description: CRM deal entity UUID, or `implied:<account_id>`.
        name:
          type: string
        account:
          type:
            - object
            - 'null'
          properties:
            entity_id:
              type: string
              format: uuid
            name:
              type:
                - string
                - 'null'
            domain:
              type:
                - string
                - 'null'
        stage:
          type:
            - string
            - 'null'
          description: The stage as the CRM (or the workspace's own ladder) names it.
        canonical_stage:
          type:
            - string
            - 'null'
          enum:
            - identified
            - connected
            - interested
            - meeting_booked
            - discovery
            - demo
            - negotiation
            - closed_won
            - closed_lost
            - disqualified
            - churned
            - null
          description: '`stage` mapped onto the standard ladder.'
        status:
          type: string
          enum:
            - open
            - won
            - lost
        amount:
          type:
            - number
            - 'null'
        currency:
          type:
            - string
            - 'null'
        close_date:
          type:
            - string
            - 'null'
        owner:
          type:
            - object
            - 'null'
          properties:
            name:
              type:
                - string
                - 'null'
            email:
              type:
                - string
                - 'null'
        pipeline:
          type:
            - object
            - 'null'
          properties:
            id:
              type:
                - string
                - 'null'
            name:
              type:
                - string
                - 'null'
        health:
          type:
            - number
            - 'null'
        win_probability:
          type:
            - number
            - 'null'
          description: Chance the deal is won. Open deals only.
        close_within_30d:
          type:
            - number
            - 'null'
          description: Chance it is won within 30 days. Open deals only.
        last_activity_at:
          type:
            - string
            - 'null'
          format: date-time
        implied:
          type: boolean
          description: True for an account's implied deal, which is not a CRM record.
    Error:
      type: object
      description: >-
        Every error response. `error` is a stable machine code. Some errors add
        fields such as `detail`, `supported`, `max`, or `reason`.
      required:
        - error
      properties:
        error:
          type: string
          description: Machine-readable error code.
        detail:
          type: string
          description: Human-readable explanation, when there is one.
      additionalProperties: true
  responses:
    Unauthorized:
      description: Missing, unknown, or expired API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing:
              summary: api_key_required
              value:
                error: api_key_required
            invalid:
              summary: invalid_api_key
              value:
                error: invalid_api_key
            expired:
              summary: api_key_expired
              value:
                error: api_key_expired
                detail: >-
                  This API key has expired. Create or rotate a key to get a
                  fresh one.
    UpgradeRequired:
      description: The workspace is past its monthly operations limit and grace window.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: upgrade_required
            reason: ops_limit_reached
            current_plan: starter
            upgrade_url: /settings?section=billing
    RateLimited:
      description: More than 600 requests in a minute on this key.
      headers:
        RateLimit-Limit:
          schema:
            type: integer
          description: Requests allowed per window.
        RateLimit-Remaining:
          schema:
            type: integer
          description: Requests left in the window.
        RateLimit-Reset:
          schema:
            type: integer
          description: Seconds until the window resets.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: rate_limited
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: internal_error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Workspace API key. Create one in **Settings → API keys**.
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: The same key, sent as a header.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.