Opportunities & Pipelines

An opportunity tracks a deal as it moves through a pipeline, from first contact to won or lost. Each opportunity sits in one pipeline stage, can link back to a contact, and carries a monetary value you can report on.

Base URL: https://services.smbcrm.com · Version header: v3 · Scopes: opportunities.readonly (read), opportunities.write (create/update/delete). See Scopes.

Pipelines

GET/opportunities/pipelines

List every pipeline in your account, with its stages in order.

scope opportunities.readonlyauth Location token or PIT

locationId is required as a query parameter. Pipelines and stages are built in the SMBcrm UI. This endpoint just reads them, so you know which IDs to use when you create or move an opportunity.

curl "https://services.smbcrm.com/opportunities/pipelines?locationId=<location_id>" \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "pipelines": [
    {
      "id": "<pipeline_id>",
      "name": "Sales Pipeline",
      "stages": [
        { "id": "<pipeline_stage_id>", "name": "New Lead", "position": 0 },
        { "id": "<pipeline_stage_id>", "name": "Contacted", "position": 1 },
        { "id": "<pipeline_stage_id>", "name": "Proposal Sent", "position": 2 },
        { "id": "<pipeline_stage_id>", "name": "Won", "position": 3 }
      ]
    }
  ]
}

Tip

Pipelines and stages rarely change. Fetch this once, cache the pipelineId and pipelineStageId values you need, and refresh occasionally instead of calling it before every write.

Create an opportunity

POST/opportunities/

Create an opportunity in a pipeline stage.

scope opportunities.writeauth Location token or PIT

pipelineId, locationId, name, status, and contactId are required — every opportunity needs a pipeline, a location, a name, a starting status, and a linked contact. pipelineStageId is optional and places the deal in a specific stage; use the IDs from Pipelines above. monetaryValue is the deal size in your account’s currency. status accepts open, won, lost, or abandoned.

curl -X POST https://services.smbcrm.com/opportunities/ \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{
    "pipelineId": "<pipeline_id>",
    "locationId": "<location_id>",
    "pipelineStageId": "<pipeline_stage_id>",
    "name": "Website redesign - Acme Co.",
    "status": "open",
    "contactId": "<contact_id>",
    "monetaryValue": 4200
  }'

201 Created

{
  "opportunity": {
    "id": "<opportunity_id>",
    "name": "Website redesign - Acme Co.",
    "pipelineId": "<pipeline_id>",
    "pipelineStageId": "<pipeline_stage_id>",
    "locationId": "<location_id>",
    "status": "open",
    "contactId": "<contact_id>",
    "monetaryValue": 4200,
    "createdAt": "2026-07-08T15:04:00.000Z"
  }
}

Retrieve an opportunity

GET/opportunities/{id}

Fetch a single opportunity by ID.

scope opportunities.readonlyauth Location token or PIT

curl https://services.smbcrm.com/opportunities/<opportunity_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "opportunity": {
    "id": "<opportunity_id>",
    "name": "Website redesign - Acme Co.",
    "pipelineId": "<pipeline_id>",
    "pipelineStageId": "<pipeline_stage_id>",
    "locationId": "<location_id>",
    "status": "open",
    "contactId": "<contact_id>",
    "monetaryValue": 4200,
    "createdAt": "2026-07-08T15:04:00.000Z"
  }
}

Search opportunities

GET/opportunities/search

Search opportunities by pipeline, stage, status, contact, or free text.

scope opportunities.readonlyauth Location token or PIT

Query parameter	Description
locationId	Your account/location ID. Required.
pipelineId	Limit results to one pipeline.
pipelineStageId	Limit results to one stage.
status	Filter by status: open, won, lost, abandoned, or all.
contactId	Limit results to opportunities linked to one contact.
assignedTo	Limit results to opportunities assigned to one user.
q	Free-text search against the opportunity name.
limit	Maximum number of results to return.

curl "https://services.smbcrm.com/opportunities/search?locationId=<location_id>&pipelineId=<pipeline_id>&status=open&limit=20" \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "opportunities": [
    {
      "id": "<opportunity_id>",
      "name": "Website redesign - Acme Co.",
      "pipelineId": "<pipeline_id>",
      "pipelineStageId": "<pipeline_stage_id>",
      "status": "open",
      "contactId": "<contact_id>",
      "monetaryValue": 4200,
      "createdAt": "2026-07-08T15:04:00.000Z"
    }
  ],
  "meta": {
    "total": 1
  }
}

Update & delete

PUT/opportunities/{id}

Update fields on an existing opportunity, including moving it to a different stage or pipeline.

scope opportunities.writeauth Location token or PIT

curl -X PUT https://services.smbcrm.com/opportunities/<opportunity_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website redesign - Acme Co. (Phase 2)",
    "pipelineStageId": "<pipeline_stage_id>",
    "monetaryValue": 6800
  }'

PUT/opportunities/{id}/status

Update only an opportunity's status, the quickest way to mark a deal won, lost, or abandoned.

scope opportunities.writeauth Location token or PIT

status is required — open, won, lost, or abandoned. When you set it to lost, pass lostReasonId too so the deal records why it was lost. See Lost reasons below for valid IDs.

curl -X PUT https://services.smbcrm.com/opportunities/<opportunity_id>/status \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{ "status": "won" }'

200 OK

{ "succeded": true, "success": true }

succeded is spelled that way in the response — not a documentation typo.

DELETE/opportunities/{id}

Permanently delete an opportunity.

scope opportunities.writeauth Location token or PIT

curl -X DELETE https://services.smbcrm.com/opportunities/<opportunity_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{ "succeded": true, "success": true }

Lost reasons

GET/opportunities/lost-reason

List the lost reasons configured for your account.

scope opportunities.readonlyauth Location token or PIT

locationId is required. The id of each reason is what you pass as lostReasonId when you set an opportunity’s status to lost.

curl "https://services.smbcrm.com/opportunities/lost-reason?locationId=<location_id>" \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "lostReasons": [
    {
      "id": "<lost_reason_id>",
      "name": "Went with a competitor",
      "locationId": "<location_id>",
      "createdAt": "2026-01-04T10:00:00.000Z",
      "updatedAt": "2026-01-04T10:00:00.000Z"
    }
  ],
  "total": 1
}

Related

• Contacts. The contactId on an opportunity points to a contact record.
• Conversations & Messages. Follow up with the contact tied to a deal.
• Scopes — the permissions your token needs for each endpoint, including opportunities.readonly and opportunities.write.