ConnectCloud Developers

Convert a lead into a customer (tenant:crm:write)

POST /api/crm/v1/leads/{id}/convert

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

Links the lead to a masterdata address of the same tenant and sets its status to CONVERTED. Send exactly one of addressId (an existing address, checked with the masterdata module) or createAddress (masterdata creates the company address with status INTERESSENT, the lead's contact as contact person; once per lead, a retry reuses the address); otherwise 400 (code: convert_target_required). opportunity creates a first opportunity of the lead and address; it is checked before masterdata is called, so a refusal creates no address: a stageKey that is no active stage of the tenant returns 400 (code: unknown_stage, field opportunity.stageKey), an invalid custom field 400 with the field opportunity.customFields.<key>. An unknown address returns 422, an unreachable masterdata module 502. A lead that is already converted returns 409 (code: lead_converted), also when two conversions run at the same time; an anonymised lead returns 409 (code: lead_anonymized). Emits crm.lead.converted (and crm.opportunity.created).

Parameters

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

Request body

application/json (required)

  • addressId (string (uuid)): Existing masterdata address of the tenant.
  • createAddress (ConvertAddress): The company address masterdata creates (status INTERESSENT, external key crm_lead).
    • companyName (string, required): Company name of the new address. (max length 255)
    • city (string): City. (max length 128)
    • country (string): ISO 3166-1 alpha-2. (max length 2)
    • email (string (email)): E-mail address. (max length 255)
    • phone (string): Phone number. (max length 64)
    • street (string): Street with house number. (max length 255)
    • vatId (string): VAT ID. (max length 32)
    • website (string): Website. (max length 512)
    • zip (string): Postal code. (max length 16)
  • opportunity (ConvertOpportunity): The first opportunity created with the conversion (linked to the lead and the address).
    • title (string, required): Title of the opportunity. (max length 255)
    • customFields (object): Values of the tenant's opportunity fields by key; validated against the definitions before the address is created, a missing required field is 400 (opportunity.customFields.<key>) and creates nothing.
    • expectedCloseDate (string (date-time)): Expected close date.
    • stageKey (string): Active stage; default the first open stage. (max length 64)
    • value (number (double)): Expected value. (max 9999999999)

Example:

{
  "createAddress": {
    "city": "Mallersdorf-Pfaffenberg",
    "companyName": "Brauerei Gaßner GmbH \u0026 Co. KG",
    "country": "DE",
    "email": "eva.gassner@brauerei-gassner.example",
    "phone": "+49 9441 50070",
    "street": "Brauhausstraße 4",
    "vatId": "DE999000231",
    "website": "https://www.brauerei-gassner.example",
    "zip": "84066"
  },
  "opportunity": {
    "expectedCloseDate": "2026-12-15T00:00:00Z",
    "stageKey": "PROPOSAL",
    "title": "WLAN Sudhaus und Lager",
    "value": 18400
  }
}

Responses

  • 200 The converted lead; opportunity is the opportunity created with it. (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)
  • 422 A referenced record (lead, masterdata address) does not exist in the tenant, or the change is not possible as sent; code says why (lost_reason_required). (application/json)
  • 500 Unexpected error; details are only logged. (application/json)
  • 502 An upstream service (masterdata, VAT check) failed, is switched off or is not configured. (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.
  • opportunity (Opportunity)
    • 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.

Example 200 answer:

{
  "company": "Brauerei Gaßner GmbH \u0026 Co. KG",
  "consent": true,
  "contactName": "Eva Gaßner",
  "convertedAddressId": "0e2a4c6e-8a1b-4d3f-9b5d-7f9b1d3f5a7b",
  "createdAt": "2026-07-19T15:40:00Z",
  "customerNo": "99999",
  "email": "eva.gassner@brauerei-gassner.example",
  "id": "5b7d9f1a-3c5e-4a7b-9d1f-3a5c7e9b1d3f",
  "marketingOptOut": false,
  "opportunity": {
    "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
  },
  "ownerEmail": "lena.vogel@muster-it.example",
  "phone": "+49 9441 50070",
  "score": 80,
  "source": "FAIR",
  "status": "CONVERTED",
  "tenantName": "DEMO",
  "updatedAt": "2026-11-04T09:15:00Z"
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/crm/v1/leads/3f2b8c1e-6d4a-4f7b-9a2e-1c5d7e9f0a12/convert' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"createAddress":{"city":"Mallersdorf-Pfaffenberg","companyName":"Brauerei Gaßner GmbH \u0026 Co. KG","country":"DE","email":"eva.gassner@brauerei-gassner.example","phone":"+49 9441 50070","street":"Brauhausstraße 4","vatId":"DE999000231","website":"https://www.brauerei-gassner.example","zip":"84066"},"opportunity":{"expectedCloseDate":"2026-12-15T00:00:00Z","stageKey":"PROPOSAL","title":"WLAN Sudhaus und Lager","value":18400}}'

View as Markdown · Interactive reference · OpenAPI