Nomos Leads API

openapi: 3.0.0
info:
  title: Nomos Authentication Leads API
  version: 2026-05-27.curie
servers:
- url: https://api.nomos.energy
  description: production
tags:
- name: Leads
paths:
  /leads:
    get:
      tags:
      - Leads
      summary: List leads
      description: Retrieve all leads with cursor pagination. Leads for feed-in plans are only available from the `2026-05-27.curie` API version onwards.
      security:
      - Bearer: []
      parameters:
      - schema:
          type: string
          nullable: true
        required: false
        name: cursor
        in: query
      - schema:
          type: number
          minimum: 1
          maximum: 100
          default: 10
        required: false
        name: limit
        in: query
      - schema:
          nullable: true
          description: '**Filterable fields:**

            - `created_at` (date)


            See [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.'
          example: value
        required: false
        description: '**Filterable fields:**

          - `created_at` (date)


          See [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.'
        name: filter[field][operator]
        in: query
      responses:
        '200':
          description: Retrieve all leads with cursor pagination. Leads for feed-in plans are only available from the `2026-05-27.curie` API version onwards.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Lead'
                  next_page:
                    type: string
                    nullable: true
                    example: eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0=
                  has_more:
                    type: boolean
                    default: false
                required:
                - object
                - items
        '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'
    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. Leads can be created for both consumption and feed-in plans.
      security:
      - Bearer: []
      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'
  /leads/{id}:
    get:
      tags:
      - Leads
      summary: Retrieve a lead
      description: Retrieve lead details by its id
      security:
      - Bearer: []
      parameters:
      - schema:
          type: string
          example: lead_mi4f0oda6x9m7gcsvjk0ole1
        required: true
        name: id
        in: path
      responses:
        '200':
          description: Retrieve the 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'
components:
  schemas:
    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
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                - invalid_type
                - too_big
                - too_small
                - invalid_format
                - not_multiple_of
                - unrecognized_keys
                - invalid_union
                - invalid_key
                - invalid_element
                - invalid_value
                - custom
                - unserviceable_zip
                - ended_subscription
                - duplicate_grid_reduction
                - missing_smart_meter
                - missing_module_1
                - unsupported_product
                - unsupported_meter_order
                - duplicate_meter_order
                - unsupported_meter
                - out_of_period_meter_reading
                - unsupported_meter_reading
                - duplicate_meter_reading
                - implausible_meter_reading
                - duplicate_customer_email
                - invalid_iban
                - upgrade_api_version
                - withdrawal_not_allowed
                - invalid_termination_date
                - subscription_not_started
                example: invalid_type
              field:
                type: string
                example: favoriteNumbers.1
              message:
                type: string
                example: 'Invalid input: expected string, received number'
            required:
            - code
            - field
            - message
          description: Per-field breakdown of a validation or business-rule failure. Omitted for API versions before the structured-errors cutoff.
      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
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                - invalid_type
                - too_big
                - too_small
                - invalid_format
                - not_multiple_of
                - unrecognized_keys
                - invalid_union
                - invalid_key
                - invalid_element
                - invalid_value
                - custom
                - unserviceable_zip
                - ended_subscription
                - duplicate_grid_reduction
                - missing_smart_meter
                - missing_module_1
                - unsupported_product
                - unsupported_meter_order
                - duplicate_meter_order
                - unsupported_meter
                - out_of_period_meter_reading
                - unsupported_meter_reading
                - duplicate_meter_reading
                - implausible_meter_reading
                - duplicate_customer_email
                - invalid_iban
                - upgrade_api_version
                - withdrawal_not_allowed
                - invalid_termination_date
                - subscription_not_started
                example: invalid_type
              field:
                type: string
                example: favoriteNumbers.1
              message:
                type: string
                example: 'Invalid input: expected string, received number'
            required:
            - code
            - field
            - message
          description: Per-field breakdown of a validation or business-rule failure. Omitted for API versions before the structured-errors cutoff.
      required:
      - code
      - message
      - requestId
      - docs
    InsertLead:
      type: object
      properties:
        plan:
          type: string
          description: Plan ID
          example: pln_mi4f0oda6x9m7gcsvjk0ole1
        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
            title: Person
          - 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
            title: Company
          - 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_mi4f0oda6x9m7gcsvjk0ole1
        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
    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
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                - invalid_type
                - too_big
                - too_small
                - invalid_format
                - not_multiple_of
                - unrecognized_keys
                - invalid_union
                - invalid_key
                - invalid_element
                - invalid_value
                - custom
                - unserviceable_zip
                - ended_subscription
                - duplicate_grid_reduction
                - missing_smart_meter
                - missing_module_1
                - unsupported_product
                - unsupported_meter_order
                - duplicate_meter_order
                - unsupported_meter
                - out_of_period_meter_reading
                - unsupported_meter_reading
                - duplicate_meter_reading
                - implausible_meter_reading
                - duplicate_customer_email
                - invalid_iban
                - upgrade_api_version
                - withdrawal_not_allowed
                - invalid_termination_date
                - subscription_not_started
                example: invalid_type
              field:
                type: string
                example: favoriteNumbers.1
              message:
                type: string
                example: 'Invalid input: expected string, received number'
            required:
            - code
            - field
            - message
          description: Per-field breakdown of a validation or business-rule failure. Omitted for API versions before the structured-errors cutoff.
      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
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                - invalid_type
                - too_big
                - too_small
                - invalid_format
                - not_multiple_of
                - unrecognized_keys
                - invalid_union
                - invalid_key
                - invalid_element
                - invalid_value
                - custom
                - unserviceable_zip
                - ended_subscription
                - duplicate_grid_reduction
                - missing_smart_meter
                - missing_module_1
                - unsupported_product
                - unsupported_meter_order
                - duplicate_meter_order
                - unsupported_meter
                - out_of_period_meter_reading
                - unsupported_meter_reading
                - duplicate_meter_reading
                - implausible_meter_reading
                - duplicate_customer_email
                - invalid_iban
                - upgrade_api_version
                - withdrawal_not_allowed
                - invalid_termination_date
                - subscription_not_started
                example: invalid_type
              field:
                type: string
                example: favoriteNumbers.1
              message:
                type: string
                example: 'Invalid input: expected string, received number'
            required:
            - code
            - field
            - message
          description: Per-field breakdown of a validation or business-rule failure. Omitted for API versions before the structured-errors cutoff.
      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
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                - invalid_type
                - too_big
                - too_small
                - invalid_format
                - not_multiple_of
                - unrecognized_keys
                - invalid_union
                - invalid_key
                - invalid_element
                - invalid_value
                - custom
                - unserviceable_zip
                - ended_subscription
                - duplicate_grid_reduction
                - missing_smart_meter
                - missing_module_1
                - unsupported_product
                - unsupported_meter_order
                - duplicate_meter_order
                - unsupported_meter
                - out_of_period_meter_reading
                - unsupported_meter_reading
                - duplicate_meter_reading
                - implausible_meter_reading
                - duplicate_customer_email
                - invalid_iban
                - upgrade_api_version
                - withdrawal_not_allowed
                - invalid_termination_date
                - subscription_not_started
                example: invalid_type
              field:
                type: string
                example: favoriteNumbers.1
              message:
                type: string
                example: 'Invalid input: expected string, received number'
            required:
            - code
            - field
            - message
          description: Per-field breakdown of a validation or business-rule failure. Omitted for API versions before the structured-errors cutoff.
      required:
      - code
      - message
      - requestId
      - docs
    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
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                - invalid_type
                - too_big
                - too_small
                - invalid_format
                - not_multiple_of
                - unrecognized_keys
                - invalid_union
                - invalid_key
                - invalid_element
                - invalid_value
                - custom
                - unserviceable_zip
                - ended_subscription
                - duplicate_grid_reduction
                - missing_smart_meter
                - missing_module_1
                - unsupported_product
                - unsupported_meter_order
                - duplicate_meter_order
                - unsupported_meter
                - out_of_period_meter_reading
                - unsupported_meter_reading
                - duplicate_meter_reading
                - implausible_meter_reading
                - duplicate_customer_email
                - invalid_iban
                - upgrade_api_version
                - withdrawal_not_allowed
                - invalid_termination_date
                - subscription_not_started
                example: invalid_type
              field:
                type: string
                example: favoriteNumbers.1
              message:
                type: string
                example: 'Invalid input: expected string, received number'
            required:
       

# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nomos/refs/heads/main/openapi/nomos-leads-api-openapi.yml