> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Convert Lead

> Convert a qualified lead into a customer account

<Note>
  Converting a lead creates an associated customer and/or account record and marks the lead as converted. This action cannot be undone — use the [unconvert endpoint](/api-reference/leads/unconvert) to reverse it.
</Note>

## Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the lead to convert.

  **Example:** `e0901f08-3aa1-43c5-af5c-0a9d2fc64e30`
</ParamField>

## Request Body

<ParamField body="create_account" type="boolean" default="true">
  Whether to create an associated account record during conversion.
</ParamField>

<ParamField body="create_customer" type="boolean" default="true">
  Whether to create an associated customer record during conversion.
</ParamField>

<ParamField body="owner" type="string">
  Override the owner for the newly created account/customer records.
</ParamField>

### Response

<ResponseField name="id" type="string">
  The ID of the converted lead.
</ResponseField>

<ResponseField name="object" type="string">
  Object type. Always `lead`.
</ResponseField>

<ResponseField name="converted" type="boolean">
  Whether the lead was successfully converted.
</ResponseField>

<ResponseField name="status" type="string">
  Updated lead status. Will be `converted`.
</ResponseField>

<ResponseField name="customer_id" type="string">
  The ID of the newly created customer record (if `create_customer` was true).
</ResponseField>

<ResponseField name="account_id" type="string">
  The ID of the newly created account record (if `create_account` was true).
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request POST 'https://api.stateset.com/v1/leads/e0901f08-3aa1-43c5-af5c-0a9d2fc64e30/convert' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data-raw '{
      "create_account": true,
      "create_customer": true
  }'
  ```

  ```graphql GraphQL theme={null}
  mutation convertLead($id: uuid!) {
    leadConvert(id: $id) {
      leads {
        id
        status
      }
      userErrors {
        field
        message
      }
    }
  }
  ```

  ```javascript Node.js theme={null}
  const result = await stateset.leads.convert(
    'e0901f08-3aa1-43c5-af5c-0a9d2fc64e30'
  );
  ```

  ```python Python theme={null}
  result = stateset.leads.convert(
    'e0901f08-3aa1-43c5-af5c-0a9d2fc64e30'
  )
  ```

  ```ruby Ruby theme={null}
  result = Stateset::Lead.convert(
    'e0901f08-3aa1-43c5-af5c-0a9d2fc64e30'
  )
  ```

  ```go Go theme={null}
  result, err := stateset.Leads.Convert(
    "e0901f08-3aa1-43c5-af5c-0a9d2fc64e30",
  )
  ```

  ```java Java theme={null}
  LeadConvertResult result = stateset.leads().convert(
    "e0901f08-3aa1-43c5-af5c-0a9d2fc64e30"
  );
  ```

  ```php PHP theme={null}
  $result = $stateset->leads->convert(
    'e0901f08-3aa1-43c5-af5c-0a9d2fc64e30'
  );
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "e0901f08-3aa1-43c5-af5c-0a9d2fc64e30",
    "object": "lead",
    "converted": true,
    "status": "converted",
    "customer_id": "cust_7b2f4a91-d3e5-4c8a-b1f0-9e6d3c5a7b2f",
    "account_id": "acct_3d1e8f72-a5b6-4c9d-8e0f-1a2b3c4d5e6f"
  }
  ```

  ```json Error Response (404 Not Found) theme={null}
  {
    "error": {
      "code": "RESOURCE_NOT_FOUND",
      "message": "Lead not found",
      "details": {
        "resource": "lead",
        "id": "e0901f08-3aa1-43c5-af5c-0a9d2fc64e30"
      },
      "request_id": "req_abc123def456"
    }
  }
  ```

  ```json Error Response (409 Conflict) theme={null}
  {
    "error": {
      "code": "ALREADY_CONVERTED",
      "message": "This lead has already been converted",
      "details": {
        "lead_id": "e0901f08-3aa1-43c5-af5c-0a9d2fc64e30",
        "converted_at": "2024-06-10T14:30:00.000Z"
      },
      "request_id": "req_abc123def456"
    }
  }
  ```
</ResponseExample>