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 (statusINTERESSENT, external keycrm_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 is400(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;
opportunityis the opportunity created with it. (application/json) - 400 Invalid input (
invalid):fieldnames the first invalid field,details.fieldsevery 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;
codesays why. (application/json) - 422 A referenced record (lead, masterdata address) does not exist in the tenant, or the change is not
possible as sent;
codesays 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 codesMANUAL,WEBSITE,FAIR,IMPORT,REFERRAL,CAMPAIGN,PHONEandOTHER; these are stored in upper case (importbecomesIMPORT), any other value is kept as written. A CSV import without a source column writesIMPORT.status(LeadStatus, required): (one ofNEW,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 whenconsentturns 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 lastvalidateVatIdwith this lead (see itsstatusvalues); 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 arePROSPECTING,QUALIFICATION,PROPOSAL,NEGOTIATION,CLOSED_WONandCLOSED_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}}'