Status Manager Setup

Update opportunity stages and statuses programmatically using the PATCH endpoint. Status changes can trigger workflow automations, making this a key tool for pipeline management at scale.

Prerequisites

Before you begin, confirm the following:

• A GoHighLevel sub-account with at least one pipeline containing multiple stages
• A Private Integration Token (PIT) with the opportunities scope enabled
• Your locationId from Settings > Business Info
• At least one existing opportunity to update (create one using the CRUD endpoint if needed)
• Knowledge of your pipeline stage IDs (retrieve them with the Pipeline Getter endpoint)

Set Up Authentication

The status endpoint uses Bearer token authentication with the opportunities scope.

1. Go to Settings > Integrations > Private Integrations
2. Select or create a PIT with opportunities scope (read and write)
3. Copy the token and set your environment:

export GHL_TOKEN="your-private-integration-token"
export LOCATION_ID="your-location-id"

Required headers:

Authorization: Bearer $GHL_TOKEN
Content-Type: application/json
Version: 2021-07-28

Make Your First Call

The status endpoint is PUT /opportunities/{opportunityId}/status. It accepts a status field and an optional pipelineStageId to move the opportunity to a different stage at the same time.

Update status to won:

curl -X PUT "https://services.leadconnectorhq.com/opportunities/{opportunityId}/status" \
  -H "Authorization: Bearer $GHL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "status": "won"
  }'

Move to a new stage and keep status open:

curl -X PUT "https://services.leadconnectorhq.com/opportunities/{opportunityId}/status" \
  -H "Authorization: Bearer $GHL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "status": "open",
    "pipelineStageId": "new-stage-id"
  }'

Mark as lost:

curl -X PUT "https://services.leadconnectorhq.com/opportunities/{opportunityId}/status" \
  -H "Authorization: Bearer $GHL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "status": "lost"
  }'

Valid status values are: open, won, lost, and abandoned. The pipelineStageId is optional. If omitted, the opportunity stays in its current stage.

Handle the Response

A successful 200 response returns the updated opportunity object with the new status and pipelineStageId values reflected.

Key behavior to know:

• Changing status to won or lost triggers any workflows configured with the “Opportunity Status Changed” trigger in your GHL account.
• Moving to a new pipelineStageId triggers “Pipeline Stage Changed” workflows.
• You can combine both in a single call. For example, set status: "won" and pipelineStageId to your “Closed Won” stage simultaneously.

Common errors:

• 401 — Token invalid or expired. Regenerate your PIT.
• 404 — Opportunity ID not found. Verify the ID exists with a GET call first.
• 422 — Invalid status value. Must be one of: open, won, lost, abandoned.
• 400 — Invalid pipelineStageId. The stage must belong to the same pipeline as the opportunity.

Test Your Setup

Walk through this sequence to verify everything works:

1. Create a test opportunity using the CRUD endpoint (or use an existing one)
2. Move stage: Send a status update with a new pipelineStageId and status: "open". Confirm the stage changed in the dashboard.
3. Mark as won: Update the same opportunity with status: "won". Check that any “Opportunity Won” workflows fired.
4. Reopen: Set status: "open" to reopen the opportunity. Verify it returns to the active pipeline view.
5. Mark as lost: Set status: "lost" and confirm the opportunity moves to the lost column.

If workflows do not trigger, check that they are published (not in draft mode) and that the trigger type matches the status change you made.

Next Steps

Read the full Status Manager guide for batch status update patterns and workflow integration strategies. Combine with Opportunity CRUD for full lifecycle management, or use Pipeline Getter to dynamically look up stage IDs before making status changes.