---
title: "List opportunities"
method: GET
path: "/v1/households/{household_id}/opportunities"
tags: ["Opportunities"]
---

# List opportunities

`GET /v1/households/{household_id}/opportunities`

## Request

- Base URL: `https://api.slant.app`
- URL: `https://api.slant.app/v1/households/{household_id}/opportunities`
- Auth: HTTP bearer

List all opportunities for a household

## Query parameters

- `page` integer
- `per_page` integer
- `pipeline_type` 'prospect' | 'client'
- `pipeline_id` string
- `pipeline_stage_id` string

## Response `200`

successful

- object
  - `data` Opportunity[], required
    - `id` string, required: The opportunity ID
    - `name` string, required: The name of the opportunity
    - `value` integer, nullable: The monetary value of the opportunity in dollars
    - `probability` integer, nullable: The probability of closing (0-100)
    - `target_close_date` string, date-time, nullable: Expected close date
    - `stage_updated_at` string, date-time, nullable: When the opportunity last moved stages. Useful for stage aging and pipeline reporting.
    - `book_id` string, required: The book ID
    - `household_id` string, nullable: The household ID (null for unassociated opportunities)
    - `opportunityable_type` 'Household' | 'Contact' | 'Business', nullable: The related record type for this opportunity
    - `opportunityable_id` string, nullable: The related record ID for this opportunity
    - `opportunityable` object, nullable: Compact related record payload for the opportunity
      - `id` string
      - `name` string, nullable
      - `type` string
    - `pipeline` Pipeline, required
      - `id` string, required: The pipeline ID
      - `name` string, required: The name of the pipeline
      - `pipeline_type` 'prospect' | 'client', nullable: Deprecated legacy pipeline type for client/prospect-only pipelines
      - `audience_types` string[], required: Record audiences supported by this pipeline
      - `default_pipeline_types` string[]: Legacy default client/prospect types served by this pipeline
      - `book_id` string, nullable: The sole shared book ID when accessible; null for pipelines shared with multiple books
      - `book_ids` string[]: Shared book IDs accessible to the authenticated user
      - `pipeline_stages` PipelineStage[]: Ordered pipeline stages
        - `id` string, required: The pipeline stage ID
        - `name` string, required: The name of the pipeline stage
        - `stage_order` integer: The stage order within the pipeline
        - `visible` boolean: Whether this stage is visible by default
        - `default_probability` integer, nullable: Default probability for opportunities in this stage
    - `pipeline_stage` PipelineStage, required
      - `id` string, required: The pipeline stage ID
      - `name` string, required: The name of the pipeline stage
      - `stage_order` integer: The stage order within the pipeline
      - `visible` boolean: Whether this stage is visible by default
      - `default_probability` integer, nullable: Default probability for opportunities in this stage
    - `custom_fields` object: Custom field values as key-value pairs
    - `assigned_to` User, required
      - `id` string, required: The ID of the user
      - `email` string, email, required: Email address of the user
      - `first_name` string, nullable, required: First name of the user
      - `last_name` string, nullable, required: Last name of the user
      - `api_access` object: Authentication details on /v1/me for personal tokens and back-office OAuth connections; omitted for company OAuth connections.
        - `auth_type` 'personal_access_token' | 'oauth'
        - `scope` 'read_only' | 'read_write', nullable
    - `created_at` string, date-time: When the opportunity was created
    - `updated_at` string, date-time: When the opportunity was last updated
  - `pagination` object, required
    - `current_page` integer
    - `total_pages` integer
    - `total_count` integer
    - `per_page` integer

## Other responses

- `400`: Bad Request - malformed JSON, invalid filters, or missing required book context
- `401`: unauthorized - missing or invalid token
- `403`: Access denied. Policy and membership failures may have an empty body. A read-only personal token cannot perform writes.
- `429`: An hourly API rate limit was exceeded. Wait Retry-After seconds before retrying.

## Changes

- **2026-11-03** `173c41bf6be9`: 1 breaking, 1 warning, 8 info
  - the response property `data/items/assigned_to/allOf[#/components/schemas/User]/api_access/scope` became nullable for the status `200`
  - added the new `oauth` enum value to the `data/items/assigned_to/allOf[#/components/schemas/User]/api_access/auth_type` response property for the response status `200`
  - added the new optional `query` request parameter `pipeline_id`
  - added the new optional `query` request parameter `pipeline_stage_id`
  - …6 more

[Operation history](https://skmtc.dev/slant/apis/slant-public-api-v1/changes/v1/households/:household_id/opportunities/get.md)

---

[API](https://skmtc.dev/slant/apis/slant-public-api-v1.md) - [All operations](https://skmtc.dev/slant/apis/slant-public-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/slant/apis/slant-public-api-v1/revisions/173c41bf6be9?raw)