ConnectCloud Developers

List leads (tenant:crm:read)

GET /api/crm/v1/leads

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

Parameters

Name In Type Required Description
status query LeadStatus (one of NEW, CONTACTED, QUALIFIED, LOST, CONVERTED)
addressId query string (uuid) Only leads converted to this masterdata address.
search query string Substring of company, contact name, email, phone, website or VAT ID; ignores case and accents (Muller finds Müller). (max length 255)
campaignId query string (uuid) Only leads of this campaign.
owner query string Only records of this owner (e-mail address), or me for the calling person. (max length 255)
consent query boolean Only leads with (true) or without (false) GDPR consent.
sort query string Sort order: a field for ascending, -field for descending. Fields: createdAt, updatedAt, company, contactName, score, status. 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 leads and the total number of matching leads (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 Lead, required): One page of leads.
    • company (string, required): Company name.
    • contactName (string, required): Name of the contact person.
    • createdAt (string (date-time), required): Creation time.
    • customerNo (string, required): Customer number of the tenant.
    • id (string (uuid), required): Id of the lead.
    • score (integer, required): Lead score 0–100. (max 100)
    • source (string, required): Free text. The portal offers the codes MANUAL, WEBSITE, FAIR, IMPORT, REFERRAL, CAMPAIGN, PHONE and OTHER; these are stored in upper case (import becomes IMPORT), any other value is kept as written. A CSV import without a source column writes IMPORT.
    • status (LeadStatus, required): (one of NEW, CONTACTED, QUALIFIED, LOST, CONVERTED)
    • tenantName (string, required): Tenant name.
    • updatedAt (string (date-time), required): Time of the last change.
    • anonymizedAt (string (date-time), read-only): Set when the retention job removed the personal data; omitted otherwise.
    • campaignId (string (uuid)): Campaign the lead comes from; omitted when not set.
    • consent (boolean): GDPR consent to be contacted.
    • consentAt (string (date-time), read-only): Set by the server when consent turns true.
    • consentSource (string): Where the consent was given; omitted when not set.
    • convertedAddressId (string (uuid)): Masterdata address after conversion; omitted before.
    • customFields (object): Values of the tenant's lead fields by field key (CRMSettings.customFields.lead).
    • email (string): Omitted when not set.
    • marketingOptOut (boolean): The person objected to marketing.
    • notes (string): Omitted when not set.
    • ownerEmail (string): Employee responsible for the lead (lower-case e-mail); omitted when not set.
    • phone (string): Omitted when not set.
    • vatCheckedAt (string (date-time), read-only): Time of that check.
    • vatId (string): Omitted when not set.
    • vatStatus (string, read-only): Status of the last validateVatId with this lead (see its status values); omitted before.
    • website (string): 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": [
    {
      "campaignId": "2a4c6e8a-0b2d-4f4a-8c6e-8a0c2e4a6c8e",
      "company": "Brauerei Gaßner GmbH \u0026 Co. KG",
      "consent": true,
      "consentAt": "2026-07-19T15:40:00Z",
      "consentSource": "Visitenkarte am Messestand",
      "contactName": "Eva Gaßner",
      "createdAt": "2026-07-19T15:40:00Z",
      "customFields": {
        "branche": "gastronomie",
        "mitarbeitende": 45
      },
      "customerNo": "99999",
      "email": "eva.gassner@brauerei-gassner.example",
      "id": "5b7d9f1a-3c5e-4a7b-9d1f-3a5c7e9b1d3f",
      "marketingOptOut": false,
      "notes": "Hat am Messestand nach WLAN für Sudhaus und Lager gefragt. Termin vor Ort hat stattgefunden, Angebot in Arbeit.",
      "ownerEmail": "lena.vogel@muster-it.example",
      "phone": "+49 9441 50070",
      "score": 80,
      "source": "FAIR",
      "status": "QUALIFIED",
      "tenantName": "DEMO",
      "updatedAt": "2026-10-28T10:20:00Z",
      "vatCheckedAt": "2026-10-28T10:02:14Z",
      "vatId": "DE999000231",
      "vatStatus": "OFFICIALLY_CONFIRMED",
      "website": "https://www.brauerei-gassner.example"
    }
  ],
  "total": 1
}

Example request

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

View as Markdown · Interactive reference · OpenAPI