> ## Documentation Index > Fetch the complete documentation index at: https://docs.nomos.energy/llms.txt > Use this file to discover all available pages before exploring further. # Create a lead > 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. Feed-in plans are only available from the `2026-05-27.curie` API version onwards; creating a lead for one returns `400 BAD_REQUEST`. ## OpenAPI ````yaml /openapi/openapi.batman.json post /leads openapi: 3.0.0 info: title: Nomos API version: 2025-12-16.batman servers: - url: http://localhost description: test security: [] tags: - name: Plans - name: Leads - name: Subscriptions - name: Customers - name: Usage - name: Prices - name: Invoices - name: Market Partners - name: Events - name: Authentication paths: /leads: post: tags: - Leads summary: Create a lead description: >- 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. Feed-in plans are only available from the `2026-05-27.curie` API version onwards; creating a lead for one returns `400 BAD_REQUEST`. requestBody: description: The lead to create required: true content: application/json: schema: $ref: '#/components/schemas/InsertLead' responses: '200': description: The created lead details content: application/json: schema: $ref: '#/components/schemas/Lead' '400': description: >- 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). content: application/json: schema: $ref: '#/components/schemas/ErrBadRequest' '401': description: The client must authenticate itself to get the requested response. content: application/json: schema: $ref: '#/components/schemas/ErrUnauthorized' '402': description: A higher pricing plan is required to access the resource. content: application/json: schema: $ref: '#/components/schemas/ErrPaymentRequired' '403': description: >- The client does not have the necessary permissions to access the resource. content: application/json: schema: $ref: '#/components/schemas/ErrForbidden' '404': description: The server can't find the requested resource. content: application/json: schema: $ref: '#/components/schemas/ErrNotFound' '405': description: The request method is not allowed. content: application/json: schema: $ref: '#/components/schemas/ErrMethodNotAllowed' '409': description: >- The request could not be completed due to a conflict mainly due to unique constraints. content: application/json: schema: $ref: '#/components/schemas/ErrConflict' '422': description: >- The request was well-formed but was unable to be followed due to semantic errors. content: application/json: schema: $ref: '#/components/schemas/ErrUnprocessableEntity' '429': description: The client has sent too many requests. content: application/json: schema: $ref: '#/components/schemas/ErrTooManyRequests' '500': description: >- The server has encountered a situation it doesn't know how to handle. content: application/json: schema: $ref: '#/components/schemas/ErrInternalServerError' security: - Bearer: [] components: schemas: InsertLead: type: object properties: plan: type: string description: Plan ID example: pln_ customer: anyOf: - type: object nullable: true properties: type: type: string enum: - person default: person description: Type of the customer, always 'person' first_name: type: string minLength: 1 maxLength: 100 description: Customer's first name example: John last_name: type: string minLength: 1 maxLength: 100 description: Customer's last name example: Doe email: type: string format: email description: Email address example: john.doe@example.com - type: object nullable: true properties: type: type: string enum: - company description: Type of the customer, always 'company' first_name: type: string minLength: 1 maxLength: 100 description: First name of the customer example: John last_name: type: string minLength: 1 maxLength: 100 description: Last name of the customer example: Doe company_name: type: string minLength: 1 maxLength: 100 description: Company name example: Example GmbH email: type: string format: email description: Email address example: gmbh@example.com - nullable: true address: type: object properties: zip: type: string minLength: 5 description: ZIP/Postal code example: '10115' street: type: string nullable: true minLength: 1 description: Street name of the address example: Torstraße city: type: string nullable: true minLength: 1 description: City name example: Berlin house_number: type: string nullable: true minLength: 1 description: House number including any additions example: '119' required: - zip meter: type: object properties: estimated_usage: type: number minimum: 100 description: Estimated yearly consumption in kWh example: 2500 type: type: string nullable: true enum: - smart - analog description: Type of the meter. Must be 'smart' for feed-in plans example: smart number: type: string nullable: true minLength: 1 description: Meter identification number example: 1APA0195124010 required: - estimated_usage payment_method: type: object nullable: true properties: type: type: string enum: - sepa_debit default: sepa_debit description: Type of payment method example: sepa_debit sepa_debit: type: object properties: iban: type: string nullable: true pattern: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$ description: IBAN number example: DE68500105178297336485 account_holder: type: string nullable: true minLength: 1 description: Name of the account holder example: John Doe previous_supplier: type: string nullable: true description: >- ID of the previous supplier, possible to obtain via /suppliers. Only supported for consumption plans. example: mp_ next_possible_start: type: boolean nullable: true description: >- 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. example: true intended_start_date: type: string nullable: true format: date description: >- 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. example: '2024-01-01' change_reason: type: string enum: - supplier_change - move_in description: Reason of changing the supplier example: supplier_change created_by: type: string nullable: true description: Email of the user who created the lead example: john.doe@example.com metadata: type: object additionalProperties: type: string description: Metadata of the lead, can be internal data example: utm_source: google utm_campaign: campaign_name user_id: '1234567890' required: - plan - address - meter Lead: type: object properties: object: type: string enum: - lead id: type: string description: Unique identifier for the lead example: lead_ subscription: type: string nullable: true description: ID of the subscription, if the lead is converted to a subscription example: sub_ subscribed_at: anyOf: - type: string - type: string format: date-time - nullable: true description: Timestamp when the lead was converted to a subscription example: '2024-03-14T12:00:00Z' link: type: string description: URL of the lead example: https://nomos.checkout.energy/?id=lead_a8n8ol7yd4h0wohx824f0bui created_at: anyOf: - type: string - type: string format: date-time description: Timestamp when the lead was created example: '2024-03-14T12:00:00Z' created_by: type: string nullable: true description: Email of the user who created the lead example: john.doe@example.com last_visited_at: anyOf: - type: string - type: string format: date-time - nullable: true description: Timestamp when the lead was last visited example: '2024-03-14T12:00:00Z' metadata: type: object nullable: true additionalProperties: nullable: true description: Metadata of the lead, can be internal data example: utm_source: google utm_campaign: campaign_name user_id: '1234567890' required: - object - id - link - created_at ErrBadRequest: type: object properties: code: type: string enum: - BAD_REQUEST description: The error code related to the status code. example: BAD_REQUEST message: type: string description: A human readable message describing the issue. example: 'invalid_type in ''end'': Required' requestId: type: string description: The request id to be used for debugging and error reporting. example: 37a04f8f-e791-491c-81e1-86cd304649bb docs: type: string description: The docs related to the error code. example: https://docs.nomos.energy/api-references/errors/BAD_REQUEST required: - code - message - requestId - docs ErrUnauthorized: type: object properties: code: type: string enum: - UNAUTHORIZED description: The error code related to the status code. example: UNAUTHORIZED message: type: string description: A human readable message describing the issue. example: Invalid or malformed token requestId: type: string description: The request id to be used for debugging and error reporting. example: 37a04f8f-e791-491c-81e1-86cd304649bb docs: type: string description: The docs related to the error code. example: https://docs.nomos.energy/api-references/errors/UNAUTHORIZED required: - code - message - requestId - docs ErrPaymentRequired: type: object properties: code: type: string enum: - PAYMENT_REQUIRED description: The error code related to the status code. example: PAYMENT_REQUIRED message: type: string description: A human readable message describing the issue. example: Payment required requestId: type: string description: The request id to be used for debugging and error reporting. example: 37a04f8f-e791-491c-81e1-86cd304649bb docs: type: string description: The docs related to the error code. example: https://docs.nomos.energy/api-references/errors/PAYMENT_REQUIRED required: - code - message - requestId - docs ErrForbidden: type: object properties: code: type: string enum: - FORBIDDEN description: The error code related to the status code. example: FORBIDDEN message: type: string description: A human readable message describing the issue. example: You are not allowed to access this resource requestId: type: string description: The request id to be used for debugging and error reporting. example: 37a04f8f-e791-491c-81e1-86cd304649bb docs: type: string description: The docs related to the error code. example: https://docs.nomos.energy/api-references/errors/FORBIDDEN required: - code - message - requestId - docs ErrNotFound: type: object properties: code: type: string enum: - NOT_FOUND description: The error code related to the status code. example: NOT_FOUND message: type: string description: A human readable message describing the issue. example: Resource not found requestId: type: string description: The request id to be used for debugging and error reporting. example: 37a04f8f-e791-491c-81e1-86cd304649bb docs: type: string description: The docs related to the error code. example: https://docs.nomos.energy/api-references/errors/NOT_FOUND required: - code - message - requestId - docs ErrMethodNotAllowed: type: object properties: code: type: string enum: - METHOD_NOT_ALLOWED description: The error code related to the status code. example: METHOD_NOT_ALLOWED message: type: string description: A human readable message describing the issue. example: Method not allowed requestId: type: string description: The request id to be used for debugging and error reporting. example: 37a04f8f-e791-491c-81e1-86cd304649bb docs: type: string description: The docs related to the error code. example: https://docs.nomos.energy/api-references/errors/METHOD_NOT_ALLOWED required: - code - message - requestId - docs ErrConflict: type: object properties: code: type: string enum: - CONFLICT description: The error code related to the status code. example: CONFLICT message: type: string description: A human readable message describing the issue. example: Resource already exists requestId: type: string description: The request id to be used for debugging and error reporting. example: 37a04f8f-e791-491c-81e1-86cd304649bb docs: type: string description: The docs related to the error code. example: https://docs.nomos.energy/api-references/errors/CONFLICT required: - code - message - requestId - docs ErrUnprocessableEntity: type: object properties: code: type: string enum: - UNPROCESSABLE_ENTITY description: The error code related to the status code. example: UNPROCESSABLE_ENTITY message: type: string description: A human readable message describing the issue. example: >- invalid_enum_value in 'status': Invalid enum value. Expected 'pending' | 'active' | 'ended' requestId: type: string description: The request id to be used for debugging and error reporting. example: 37a04f8f-e791-491c-81e1-86cd304649bb docs: type: string description: The docs related to the error code. example: https://docs.nomos.energy/api-references/errors/UNPROCESSABLE_ENTITY required: - code - message - requestId - docs ErrTooManyRequests: type: object properties: code: type: string enum: - TOO_MANY_REQUESTS description: The error code related to the status code. example: TOO_MANY_REQUESTS message: type: string description: A human readable message describing the issue. example: Wait 30 seconds before retrying. requestId: type: string description: The request id to be used for debugging and error reporting. example: 37a04f8f-e791-491c-81e1-86cd304649bb docs: type: string description: The docs related to the error code. example: https://docs.nomos.energy/api-references/errors/TOO_MANY_REQUESTS required: - code - message - requestId - docs ErrInternalServerError: type: object properties: code: type: string enum: - INTERNAL_SERVER_ERROR description: The error code related to the status code. example: INTERNAL_SERVER_ERROR message: type: string description: A human readable message describing the issue. example: Internal Server Error requestId: type: string description: The request id to be used for debugging and error reporting. example: 37a04f8f-e791-491c-81e1-86cd304649bb docs: type: string description: The docs related to the error code. example: >- https://docs.nomos.energy/api-references/errors/INTERNAL_SERVER_ERROR required: - code - message - requestId - docs securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ````