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

# Describe a user's household

> Fills in the address and owner of the dwelling. Only the fields you send change; a field sent as `null` is cleared.

`country` accepts a country code (`BE`) or name in any language (`Belgium`, `België`). An unknown country returns a 400.

A household is shared between consumers: what one consumer sets, others see too. The latest update wins.



## OpenAPI

````yaml /api-docs/connect/openapi-connect.json patch /households
openapi: 3.1.0
info:
  title: NOX Connections API
  version: 1.0.0
  description: >-
    Connect a user's account at a provider (a device brand or a utility) to NOX
    Energy, and manage that access.
servers:
  - url: https://api.connect.nox.energy/v1
    description: Production
security:
  - apiKey: []
tags:
  - name: Connections
    description: Creating, listing and revoking connections.
  - name: Households
    description: The dwelling a person's connections belong to.
paths:
  /households:
    patch:
      tags:
        - Households
      summary: Describe a user's household
      description: >-
        Fills in the address and owner of the dwelling. Only the fields you send
        change; a field sent as `null` is cleared.


        `country` accepts a country code (`BE`) or name in any language
        (`Belgium`, `België`). An unknown country returns a 400.


        A household is shared between consumers: what one consumer sets, others
        see too. The latest update wins.
      parameters:
        - name: user_id
          in: query
          required: true
          description: Your internal user ID.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HouseholdRequest'
      responses:
        '200':
          description: The household as it now stands.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Household'
        '400':
          description: >-
            The request was rejected; `error` says which field, rule or
            provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or unknown API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Nothing matched.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: A bug on our side; `code` is `unexpected`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKey: []
components:
  schemas:
    HouseholdRequest:
      additionalProperties: false
      description: >-
        Nothing is required: a PATCH names the fields it changes, the rest keep
        their value,

        and a field sent as null is cleared.
      properties:
        location:
          anyOf:
            - $ref: '#/components/schemas/Location'
            - type: 'null'
          default: null
        owner:
          anyOf:
            - $ref: '#/components/schemas/Owner'
            - type: 'null'
          default: null
      title: HouseholdRequest
      type: object
    Household:
      additionalProperties: false
      properties:
        location:
          $ref: '#/components/schemas/Location'
        owner:
          $ref: '#/components/schemas/Owner'
      required:
        - location
        - owner
      title: Household
      type: object
    Error:
      type: object
      properties:
        error:
          type: string
          description: What went wrong, in full.
        code:
          $ref: '#/components/schemas/ConnectFailureCode'
          description: >-
            Present when the failure has one: the same closed set the connect UI
            translates.
      required:
        - error
    Location:
      additionalProperties: false
      properties:
        country:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Country
        city:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: City
        postal_code:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Postal Code
        street:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Street
        number:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Number
        coordinates:
          anyOf:
            - $ref: '#/components/schemas/Coordinates'
            - type: 'null'
          default: null
      title: Location
      type: object
    Owner:
      additionalProperties: false
      properties:
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: First Name
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Last Name
      title: Owner
      type: object
    ConnectFailureCode:
      description: Ported from what the legacy authenticator-api tells users.
      enum:
        - no_devices
        - unsupported_device
        - invalid_credentials
        - unsupported_country
        - not_account_owner
        - multiple_users
        - missing_site_id
        - invalid_ean
        - invalid_site_id
        - onboarding_failed
        - registration_failed
        - missing_permissions
        - hybrid_inverter_not_allowed
        - session_not_found
        - session_expired
        - authorization_spent
        - provider_unavailable
        - rate_limited
        - invalid_request
        - unexpected
      title: ConnectFailureCode
      type: string
    Coordinates:
      additionalProperties: false
      properties:
        latitude:
          maximum: 90
          minimum: -90
          title: Latitude
          type: number
        longitude:
          maximum: 180
          minimum: -180
          title: Longitude
          type: number
      required:
        - latitude
        - longitude
      title: Coordinates
      type: object
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Your consumer API key.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.