UPS

Opportunity Upsert

Pipelines & Opportunities · Intermediate · Updated March 2026

Create a new opportunity or update an existing one in a single API call. Prevents duplicates using contact and pipeline matching.

The upsert pattern eliminates the most common integration headache: deciding whether to create a new record or update an existing one. Opportunity Upsert handles both in a single call. If a matching opportunity exists (based on contact and pipeline), it updates. If not, it creates. This is the safest way to push deal data from external systems into GHL without creating duplicates.

What This MCP Tool Does

Create or update an opportunity in a single call. The endpoint checks for existing opportunities matching the contact and pipeline combination. If found, it updates the existing record. If not found, it creates a new one. Either way, you get back the opportunity record.

Endpoint Reference

Upsert an opportunity: POST /opportunities/upsert Provide the contact ID, pipeline ID, stage, value, and any other opportunity fields. GHL matches on contact + pipeline to determine create vs. update.

Authentication

Requires a Private Integration Token (PIT) with the opportunities scope enabled.

Key Parameters

Same as Opportunity CRUD creation:

pipelineId — target pipeline
pipelineStageId — target stage
contactId — associated contact
name — deal name
monetaryValue — deal value
status — deal status
assignedTo — deal owner

Important Notes

Matching logic uses the contact ID and pipeline ID combination. If a contact has an existing opportunity in the specified pipeline, it updates that opportunity. If the contact has no opportunity in that pipeline, it creates a new one.

This means a single contact can have one opportunity per pipeline through upsert. If you need multiple opportunities for the same contact in the same pipeline, use direct creation through Opportunity CRUD instead.

The upsert pattern is ideal for webhook-driven integrations where the same event might fire multiple times (retry logic, duplicate webhooks). Multiple upsert calls with the same data result in the same opportunity being updated, not duplicates being created.

Common Questions

How does matching work exactly? Match on contact ID + pipeline ID. One opportunity per contact per pipeline through upsert.

Can I upsert to move a deal to a different stage? Yes. Include the new pipelineStageId in the upsert call. If the opportunity exists, its stage updates.

What if I want multiple deals for the same contact in the same pipeline? Use direct creation via Opportunity CRUD. Upsert enforces one-per-pipeline-per-contact.

Does upsert trigger stage-change workflows? Yes. If the upsert results in a stage change on an existing opportunity, stage-change workflow triggers fire normally.

Opportunity CRUD — Direct create/update when you need more control
Opportunity Search — Find existing opportunities before operations
Status Manager — Manage deal status transitions
Pipeline Getter — Get pipeline and stage IDs for upsert calls
Contact CRUD — Contact upsert follows the same pattern