ConnectCloud Developers

Update a lead (tenant:crm:write)

PUT /api/crm/v1/leads/{id}

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

Partial update: only the fields sent change. status may be sent unchanged (also CONVERTED, as a form sends it). Setting CONVERTED on a lead that is not converted is refused with 400 (code: lead_convert_required; use convertLead), changing the status of a converted lead with 409 (code: lead_converted). An anonymised lead is read-only: 409 (code: lead_anonymized). ownerEmail: "" removes the owner. The score is recomputed when lead scoring is on and no score is sent. Emits crm.lead.updated (and crm.lead.assigned when the owner changes).

Parameters

Name In Type Required Description
id path string (uuid) yes Record ID (UUID).

Request body

application/json (required)

  • campaignId (string): An empty string removes the campaign. (max length 36)
  • company (string): Company name. (max length 255)
  • consent (boolean): GDPR consent to be contacted.
  • consentSource (string): Where the consent was given. (max length 255)
  • contactName (string): Name of the contact person. (max length 255)
  • customFields (object): Values by field key.
  • email (string (email)): E-mail address. (max length 255)
  • marketingOptOut (boolean): The person objected to marketing.
  • notes (string): Notes. (max length 10000)
  • ownerEmail (string): An empty string removes the owner. (max length 255)
  • phone (string): Phone number. (max length 64)
  • score (integer): Lead score 0–100. (max 100)
  • source (string): Lead source. (max length 64)
  • status (string): CONVERTED is accepted only unchanged (a converted lead keeps it); converting is convertLead. (one of NEW, CONTACTED, QUALIFIED, LOST, CONVERTED)
  • vatId (string): VAT ID. (max length 32)
  • website (string): Website. (max length 512)

Example:

{
  "notes": "Angebot für Q1 angefragt.",
  "score": 80,
  "status": "QUALIFIED"
}

Responses

  • 200 The updated lead (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)
  • 404 The record does not exist in the token's tenant. (application/json)
  • 409 The state of the record (or the tenant's settings) does not allow the request; code says why. (application/json)
  • 500 Unexpected error; details are only logged. (application/json)

Fields of the 200 answer:

  • 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.

Example 200 answer:

{
  "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"
}

Example request

curl -X PUT 'https://api.mbcom.cloud/api/crm/v1/leads/3f2b8c1e-6d4a-4f7b-9a2e-1c5d7e9f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"notes":"Angebot für Q1 angefragt.","score":80,"status":"QUALIFIED"}'

View as Markdown · Interactive reference · OpenAPI