---
title: "Create a lead"
method: POST
path: "/leads"
tags: ["Leads"]
---

# Create a lead

`POST /leads`

This endpoint can be used to create a secure, pre-filled checkout link. The link (returned in the "link" property) contains all provided customer, address and meter data, allowing the prospect to finalize their signup with only providing the missing payment information, essentially enabling a 2-click checkout experience. Leads are tracked in the Nomos Dashboard for detailed conversion analytics. Leads can be created for both consumption and feed-in plans.

## Request body

- InsertLead
  - `plan` string, required — Plan ID
  - `customer` union
    - object, nullable
      - `type` 'person' — Type of the customer, always 'person'
      - `first_name` string — Customer's first name
      - `last_name` string — Customer's last name
      - `email` string, email — Email address
    - object, nullable
      - `type` 'company' — Type of the customer, always 'company'
      - `first_name` string — First name of the customer
      - `last_name` string — Last name of the customer
      - `company_name` string — Company name
      - `email` string, email — Email address
    - unknown
  - `address` object, required
    - `zip` string, required — ZIP/Postal code
    - `street` string, nullable — Street name of the address
    - `city` string, nullable — City name
    - `house_number` string, nullable — House number including any additions
  - `meter` object, required
    - `estimated_usage` number, required — Estimated yearly consumption in kWh
    - `type` 'smart' | 'analog', nullable — Type of the meter. Must be 'smart' for feed-in plans
    - `number` string, nullable — Meter identification number
  - `payment_method` object, nullable
    - `type` 'sepa_debit' — Type of payment method
    - `sepa_debit` object
      - `iban` string, nullable — IBAN number
      - `account_holder` string, nullable — Name of the account holder
  - `previous_supplier` string, nullable — ID of the previous supplier, possible to obtain via /suppliers. Only supported for consumption plans.
  - `next_possible_start` boolean, nullable — If set to false we will request the cancellation of the previous supplier / grid operator signup to the date provided in intended_start_date. If set to true we will request the next possible date.
  - `intended_start_date` string, date, nullable — Intended start date of the subscription. Must be a date in the future. For feed-in plans it must be the first day of a month, at least one month in the future; when omitted, the next possible production start date is used.
  - `change_reason` 'supplier_change' | 'move_in' — Reason of changing the supplier
  - `created_by` string, nullable — Email of the user who created the lead
  - `metadata` object — Metadata of the lead, can be internal data

## Response `200`

The created lead details

- Lead
  - `object` 'lead', required
  - `id` string, required — Unique identifier for the lead
  - `subscription` string, nullable — ID of the subscription, if the lead is converted to a subscription
  - `subscribed_at` union — Timestamp when the lead was converted to a subscription
    - string
    - string, date-time
    - unknown
  - `link` string, required — URL of the lead
  - `created_at` union, required — Timestamp when the lead was created
    - string
    - string, date-time
  - `created_by` string, nullable — Email of the user who created the lead
  - `last_visited_at` union — Timestamp when the lead was last visited
    - string
    - string, date-time
    - unknown
  - `metadata` object, nullable — Metadata of the lead, can be internal data

## Other responses

- `400` — The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
- `401` — The client must authenticate itself to get the requested response.
- `402` — A higher pricing plan is required to access the resource.
- `403` — The client does not have the necessary permissions to access the resource.
- `404` — The server can't find the requested resource.
- `405` — The request method is not allowed.
- `409` — The request could not be completed due to a conflict mainly due to unique constraints.
- `422` — The request was well-formed but was unable to be followed due to semantic errors.
- `429` — The client has sent too many requests.
- `500` — The server has encountered a situation it doesn't know how to handle.

---

[API](https://skmtc.dev/nomos/apis/nomos-api.md) · [All operations](https://skmtc.dev/nomos/apis/nomos-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nomos/nomos-api/revisions/da60ad83e92f/schema)