v1

latestOpenAPI 3.0.12026-07-268028223.9 KB

Opportunities

Create an opportunity

Create a new opportunity for a household

post/v1/households/{household_id}/opportunities

Headers

Idempotency-Keystring

Unique key to ensure idempotent request handling. If a request with the same key was already processed, the original response will be returned.

Request body

namestring required

Name of the opportunity

valueinteger

The monetary value of the opportunity in whole dollars, not cents

probabilityinteger

The probability of closing (0-100)

target_close_datestring date-time

Expected close date (must be in the future)

pipeline_idstring

The pipeline ID. Selects the exact pipeline and takes precedence over household type defaults.

pipeline_stage_idstring

The pipeline stage ID. Must belong to the selected pipeline. Defaults to the first stage.

owner_idstring

Alias for assigned_to_id

assigned_to_idstring

The assigned user ID from the relevant book users list (defaults to authenticated user)

Example request

{
  "name": "New Investment Opportunity",
  "value": 500000,
  "probability": 75,
  "target_close_date": "2026-06-01T00:00:00Z",
  "pipeline_id": "pipeline123xyz",
  "pipeline_stage_id": "stage123xyz",
  "owner_id": "user123xyz",
  "assigned_to_id": "user123xyz"
}

Response

opportunity created

idstring required

The opportunity ID

namestring required

The name of the opportunity

valueinteger nullable

The monetary value of the opportunity in dollars

probabilityinteger nullable

The probability of closing (0-100)

target_close_datestring date-time nullable

Expected close date

stage_updated_atstring date-time nullable

When the opportunity last moved stages. Useful for stage aging and pipeline reporting.

book_idstring required

The book ID

household_idstring nullable

The household ID (null for unassociated opportunities)

opportunityable_type'Household' | 'Contact' | 'Business' nullable

The related record type for this opportunity

opportunityable_idstring nullable

The related record ID for this opportunity

custom_fieldsobject

Custom field values as key-value pairs

created_atstring date-time

When the opportunity was created

updated_atstring date-time

When the opportunity was last updated

Example response

{
  "id": "abc123xyz",
  "name": "New Investment Opportunity",
  "value": 5000,
  "probability": 75,
  "book_id": "book123xyz",
  "household_id": "household123xyz",
  "pipeline": {
    "id": "pipeline123xyz",
    "name": "Sales Pipeline",
    "pipeline_type": "prospect",
    "book_id": "book123xyz",
    "pipeline_stages": [
      {
        "id": "stage123xyz",
        "name": "Qualified",
        "stage_order": 1,
        "visible": true,
        "default_probability": 50
      }
    ]
  },
  "pipeline_stage": {
    "id": "stage123xyz",
    "name": "Qualified",
    "stage_order": 1,
    "visible": true,
    "default_probability": 50
  },
  "custom_fields": {
    "lead_source": "Referral"
  },
  "assigned_to": {
    "id": "abc123xyz",
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "api_access": {
      "auth_type": "personal_access_token",
      "scope": "read_write"
    }
  }
}