Organization API

Convert one Lead

Converts a Lead into a Customer, Property, and Opportunity using the documented email and placeId identity rules: a placeId reuses the Customer's own Property at that place, and otherwise the Customer gets a new Property. The Opportunity takes the Lead's Originator, returned as result.opportunity.originatorId. On a Property already on file, this organization becomes its primary service provider only when no organization is. Requires Idempotency-Key. Required scope: leads:convert.

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

Convert one Lead. Use an organization API key with leads:convert. Check the response envelope and meta.requestId before triggering dependent workflow steps.

Required scopes

leads:convertIdempotency-Key required

Parameters

Name	In	Type	Description
idrequired	path	string	Lead identifier returned by the Organization API.

Request body

objectrequired

Field	Type	Description
customerrequired	object	Optional unless marked required.
customer.firstNamerequired	string	Optional unless marked required.
customer.lastNamerequired	string	Optional unless marked required.
customer.emailrequired	string	Optional unless marked required.
customer.phone	string \| null	Optional unless marked required.
customer.displayName	string \| null	Optional unless marked required.
propertyrequired	object	Optional unless marked required.
property.addressrequired	string	Optional unless marked required.
property.cityrequired	string	Optional unless marked required.
property.staterequired	string	US state name or abbreviation; normalized by solarOS.
property.zipCoderequired	string	Optional unless marked required.
property.placeId	string \| null	Optional unless marked required.
property.latitude	number \| null	Optional unless marked required.
property.longitude	number \| null	Optional unless marked required.
property.formattedAddress	string \| null	Optional unless marked required.
property.country	string	Optional unless marked required.
opportunityrequired	object	Optional unless marked required.
opportunity.namerequired	string	Optional unless marked required.
opportunity.value	string \| number \| null	Optional unless marked required.
opportunity.expectedCloseDate	string \| null	Optional unless marked required.
opportunity.ownerId	string \| null	Active or draft same-organization Team Member id. When omitted, the API key default owner for this resource is used. Ownership cannot be changed through generic PATCH endpoints.
opportunity.notes	string \| null	Optional unless marked required.
opportunity.salesTypeIds[]	array<string>	Optional unless marked required.

convertleadRequest

{
  "customer": {
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "ada@example.com"
  },
  "property": {
    "address": "1 Market St",
    "city": "San Francisco",
    "state": "CA",
    "zipCode": "94105"
  },
  "opportunity": {
    "name": "Residential solar consultation",
    "salesTypeIds": [
      "sales_type_install"
    ]
  }
}

Responses

201

Lead conversion action envelope

#/components/schemas/OrgApiActionEnvelope

400

Validation or ownership error