Opportunity CRUD Setup

Connect to the GoHighLevel Opportunities API and start managing deals programmatically. This guide covers creating, reading, updating, and deleting opportunities through four core endpoints.

Prerequisites

Before you begin, confirm the following:

• A GoHighLevel sub-account with at least one pipeline and one stage configured
• A Private Integration Token (PIT) with the opportunities scope enabled
• Your locationId (sub-account ID) available in Settings > Business Info
• At least one contact in your CRM to associate with test opportunities
• A REST client like Postman, Insomnia, or curl installed on your machine

Set Up Authentication

All opportunity endpoints require a Bearer token from your Private Integration Token.

1. Go to Settings > Integrations > Private Integrations in your sub-account
2. Click Create Private Integration
3. Name it something descriptive like “Opportunity Manager”
4. Under Scopes, enable opportunities (read and write)
5. Click Save and copy the generated token

Set the token as an environment variable so you can reuse it across requests:

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

Every request needs these headers:

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

Make Your First Call

Start by creating an opportunity. You need a valid pipelineId, pipelineStageId, and contactId.

Create an opportunity:

curl -X POST "https://services.leadconnectorhq.com/opportunities/" \
  -H "Authorization: Bearer $GHL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "pipelineId": "your-pipeline-id",
    "pipelineStageId": "your-stage-id",
    "locationId": "'"$LOCATION_ID"'",
    "contactId": "your-contact-id",
    "name": "Test Deal",
    "monetaryValue": 5000,
    "status": "open"
  }'

Read an opportunity using the ID returned from the create call:

curl -X GET "https://services.leadconnectorhq.com/opportunities/{opportunityId}" \
  -H "Authorization: Bearer $GHL_TOKEN" \
  -H "Version: 2021-07-28"

Update an opportunity to change the value or name:

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

Delete an opportunity when you no longer need it:

curl -X DELETE "https://services.leadconnectorhq.com/opportunities/{opportunityId}" \
  -H "Authorization: Bearer $GHL_TOKEN" \
  -H "Version: 2021-07-28"

Handle the Response

A successful POST returns 201 with the new opportunity object, including id, name, monetaryValue, pipelineId, pipelineStageId, and status. Store the id for subsequent operations.

A GET returns 200 with the full opportunity record, including contact details, assignedTo, and custom field values. A PUT returns the updated object. A DELETE returns 200 with a success confirmation.

Common error codes to handle:

• 401 — Invalid or expired token. Regenerate your PIT.
• 404 — Opportunity, pipeline, or contact ID not found. Double-check your IDs.
• 422 — Missing required fields like pipelineId or contactId.

Test Your Setup

Run through this checklist to confirm everything works:

1. Create a test opportunity and note the returned id
2. Read that opportunity by ID and verify the data matches
3. Update the monetaryValue and confirm the change in a follow-up GET
4. Delete the test opportunity and verify a subsequent GET returns 404
5. Check the opportunity appeared (and disappeared) in the GHL dashboard under Opportunities

If any step fails, verify your token has the opportunities scope and your locationId matches the sub-account you are working in.

Next Steps

Read the full Opportunity CRUD guide for advanced patterns including bulk operations and custom field mapping. Explore Opportunity Search to query opportunities with filters, or set up the Status Manager to automate stage transitions.