ConnectCloud Developers

List opportunities (tenant:crm:read)

GET /api/crm/v1/opportunities

Module: CRM · operationId: listOpportunities · Tag: Opportunities · Auth: access token (Authorization: Bearer <accessToken>)

Parameters

Name In Type Required Description
stage query string Only opportunities in this stage (key, see listStages). (max length 64)
phase query string Only opportunities in a stage of this phase. (one of open, won, lost)
addressId query string (uuid) Only opportunities for this masterdata address.
leadId query string (uuid) Only opportunities of this lead.
owner query string Only records of this owner (e-mail address), or me for the calling person. (max length 255)
closeFrom query string (date-time) Only opportunities closed (closedAt) at or after this time (RFC 3339).
closeTo query string (date-time) Only opportunities closed (closedAt) before this time (RFC 3339).
search query string Case-insensitive substring of title or notes. (max length 255)
sort query string Sort order: a field for ascending, -field for descending. Fields: createdAt, updatedAt, title, value, probability, expectedCloseDate, closedAt, stage. Default -createdAt. Unknown values answer 400 (invalid_sort). (max length 32)
limit query integer Page size, 1–200 (default 50); any other value is 400 invalid. (default 50; max 200)
cursor query string nextCursor of the previous page; leave out for the first page. Keep sort and the filters unchanged while paging: a cursor of another sort or an altered one is 400 invalid (field: cursor). (max length 1024)

Responses

  • 200 A page of opportunities and the total number of matching opportunities (application/json)
  • 400 Invalid input (invalid): field names the first invalid field, details.fields every one (JSON paths for bodies, parameter names for the query). Some refusals have their own code (invalid_sort, invalid_stages, invalid_custom_fields, convert_target_required, invalid_csv, …). (application/json)
  • 401 Missing, invalid or expired token (no body).
  • 403 The token lacks the permission (insufficient permissions) or has no active tenant. (application/json)
  • 500 Unexpected error; details are only logged. (application/json)

Fields of the 200 answer:

  • items (array of Opportunity, required): One page of opportunities.
    • createdAt (string (date-time), required): Creation time.
    • customerNo (string, required): Customer number of the tenant.
    • id (string (uuid), required): Id of the opportunity.
    • probability (integer, required): Win probability in percent. (max 100)
    • stage (OpportunityStage, required): Key of a stage of the tenant (listStages). The defaults are PROSPECTING, QUALIFICATION, PROPOSAL, NEGOTIATION, CLOSED_WON and CLOSED_LOST. (max length 64)
    • tenantName (string, required): Tenant name.
    • title (string, required): Title of the opportunity.
    • updatedAt (string (date-time), required): Time of the last change.
    • value (number (double), required): Expected value.
    • addressId (string (uuid)): Masterdata address; omitted when not set.
    • closedAt (string (date-time), read-only): Set by the server when the opportunity enters a won or lost stage, cleared when it leaves.
    • customFields (object): Values of the tenant's opportunity fields by field key.
    • expectedCloseDate (string (date-time)): Omitted when not set.
    • leadId (string (uuid)): Omitted when not set.
    • lostReason (string): Required in a lost stage, cleared when the opportunity leaves it; omitted when not set.
    • notes (string): Omitted when not set.
    • ownerEmail (string): Employee responsible for the opportunity; omitted when not set.
  • total (integer, required): Number of all records matching the filters.
  • nextCursor (string): Cursor of the next page (pass it as cursor); missing on the last page.

Example 200 answer:

{
  "items": [
    {
      "addressId": "0e2a4c6e-8a1b-4d3f-9b5d-7f9b1d3f5a7b",
      "createdAt": "2026-11-04T09:15:00Z",
      "customFields": {
        "budget-freigegeben": true,
        "entscheider": "Eva Gaßner"
      },
      "customerNo": "99999",
      "expectedCloseDate": "2026-12-15T00:00:00Z",
      "id": "7d9f1b3d-5e7a-4c9b-8f1d-5c7e9a1b3d5f",
      "leadId": "5b7d9f1a-3c5e-4a7b-9d1f-3a5c7e9b1d3f",
      "notes": "Acht Access Points, Controller und Ausleuchtung; Montage in der Betriebspause.",
      "ownerEmail": "lena.vogel@muster-it.example",
      "probability": 50,
      "stage": "PROPOSAL",
      "tenantName": "DEMO",
      "title": "WLAN Sudhaus und Lager",
      "updatedAt": "2026-11-12T16:40:00Z",
      "value": 18400
    }
  ],
  "total": 1
}

Example request

curl -X GET 'https://api.mbcom.cloud/api/crm/v1/opportunities' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

View as Markdown · Interactive reference · OpenAPI