Nomos Customers API

openapi: 3.0.0
info:
  title: Nomos Authentication Customers API
  version: 2026-05-27.curie
servers:
- url: https://api.nomos.energy
  description: production
tags:
- name: Customers
paths:
  /customers/{id}:
    patch:
      tags:
      - Customers
      summary: Update a customer
      description: Update the editable fields of a customer. Only `first_name` and `last_name` may be changed; both are optional so a request may update just one. Returns the updated customer.
      security:
      - Bearer: []
      parameters:
      - schema:
          type: string
          example: cus_mi4f0oda6x9m7gcsvjk0ole1
        required: true
        name: id
        in: path
      requestBody:
        description: The customer fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomer'
      responses:
        '200':
          description: The updated customer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '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'
    get:
      tags:
      - Customers
      summary: Retrieve a customer
      description: Retrieve customer details by their id
      security:
      - Bearer: []
      parameters:
      - schema:
          type: string
          example: cus_mi4f0oda6x9m7gcsvjk0ole1
        required: true
        name: id
        in: path
      responses:
        '200':
          description: Retrieve the customer details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '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'
  /customers:
    get:
      tags:
      - Customers
      summary: List customers
      description: Retrieve all customers with cursor pagination
      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:**

            - `email` (string)

            - `type` (string)

            - `created_at` (date)


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

          - `email` (string)

          - `type` (string)

          - `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 customers with cursor pagination
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
                  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'
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
    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
    Customer:
      anyOf:
      - type: object
        properties:
          object:
            type: string
            enum:
            - customer
            description: Type of the object, always 'customer'
          id:
            type: string
            description: Unique identifier for the customer
            example: cus_mi4f0oda6x9m7gcsvjk0ole1
          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
          vat_id:
            type: string
            nullable: true
            description: VAT identification number (USt-IdNr.) of the customer
            example: DE123456789
          created_at:
            anyOf:
            - type: string
            - type: string
              format: date-time
            description: Timestamp when the customer was created
            example: '2024-03-14T12:00:00Z'
        required:
        - object
        - id
        - first_name
        - last_name
        - email
        - created_at
        title: Person
      - type: object
        properties:
          object:
            type: string
            enum:
            - customer
            description: Type of the object, always 'customer'
          id:
            type: string
            description: Unique identifier for the customer
            example: cus_mi4f0oda6x9m7gcsvjk0ole1
          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
          vat_id:
            type: string
            nullable: true
            description: VAT identification number (USt-IdNr.) of the customer
            example: DE123456789
          created_at:
            anyOf:
            - type: string
            - type: string
              format: date-time
            description: Timestamp when the customer was created
            example: '2024-03-14T12:00:00Z'
        required:
        - object
        - id
        - type
        - first_name
        - last_name
        - company_name
        - email
        - created_at
        title: Company
    UpdateCustomer:
      type: object
      properties:
        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
        company_name:
          type: string
          minLength: 1
          maxLength: 100
          description: Company name. Only valid for company customers; must be non-empty when provided.
          example: Example GmbH
      example:
        first_name: John
        last_name: Doe
    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:
            - 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
    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
        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_t

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