Sign in

v1

latestOpenAPI 3.0.12026-07-268028223.9 KB
Opportunities

Update an opportunity

Update an existing opportunity for a household. To move stages, set pipeline_stage_id. The stage must belong to the opportunity pipeline; PATCH does not accept pipeline_id. There is no cross-pipeline move endpoint; create a new opportunity in the target pipeline.

patch/v1/households/{household_id}/opportunities/{id}

Path parameters

idstring required

The opportunity ID

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

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

pipeline_stage_idstring

The pipeline stage ID. Must belong to the opportunity pipeline.

assigned_to_idstring

The assigned user ID from the relevant book users list. Prefer this over owner_id.

owner_idstring

Alias for assigned_to_id

household_idstring

Legacy household ID for household-backed opportunities. Set to null to clear the relationship.

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

Related record type for the opportunity. Must be provided with opportunityable_id.

opportunityable_idstring

Related record ID for the opportunity. Must be provided with opportunityable_type. Set opportunityable_type and opportunityable_id to null to clear the relationship.

custom_fieldsobject

Custom field values as key-value pairs

Example request

{
  "name": "Updated opportunity",
  "value": 750000,
  "probability": 80
}

Response

opportunity updated

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"
    }
  }
}