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

# Initialise site and assets

> Initialise a site with one or more assets.

This endpoint upserts the site and assets (creating them if they don't exist, or filling in missing fields if they do), and returns eligibility information.

**No enrollment side effects**: Use the `/enrol` endpoint to commit to enrollment.



## OpenAPI

````yaml POST /entities/site/initialise
openapi: 3.1.0
info:
  title: Axle API Docs
  description: >-
    For full documentation please see our official docs at <a
    href='http://docs.axle.energy'>docs.axle.energy</a>
  version: 1.4.6
servers:
  - url: https://api-sandbox.axle.energy
security: []
tags:
  - name: 1. Authentication
    description: Authenticate yourself with the Axle API
  - name: 2. Meters
    description: Find key info about your sites
  - name: 3. Sites
    description: Register your sites with Axle; configure market participation
  - name: 4. Assets
    description: Register your assets with Axle
  - name: 5. Data
    description: Send asset metrics to Axle, for analysis and optimisation purposes
  - name: 6. Rewards
    description: >-
      Determine how much your users have earned by participating with Axle;
      allow balance withdrawal
  - name: 7. Validation
    description: Validate structured data against Axle's rules
  - name: 8. Examples
    description: Get example data for testing
paths:
  /entities/site/initialise:
    post:
      tags:
        - 3. Sites
      summary: Initialise Site
      description: >-
        Initialise a site with one or more assets.


        This endpoint upserts the site and assets (creating them if they don't
        exist, or filling in missing fields if they do), and returns eligibility
        information.


        **No enrollment side effects**: Use the `/enrol` endpoint to commit to
        enrollment.
      operationId: initialise_site_entities_site_initialise_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitialiseRequest'
        required: true
      responses:
        '200':
          description: Successfully initialised site and assets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitialiseResponse'
        '400':
          description: Invalid request (e.g. missing boundary meter consent T&Cs)
        '404':
          description: Referenced entity not found
        '409':
          description: >-
            Asset conflict (e.g. asset type mismatch or asset registered to a
            different site)
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Server error during initialisation
      security:
        - OAuth2PasswordBearer: []
components:
  schemas:
    InitialiseRequest:
      properties:
        site:
          allOf:
            - $ref: '#/components/schemas/SiteRequest'
          title: Site
          description: Site information
          examples:
            - mpan: '1234567890123'
              postcode: SW1A 1AA
              street_address: 10 Downing Street
              email: resident@example.com
              gave_boundary_meter_consent_at: '2026-01-15T10:30:00Z'
        assets:
          items:
            $ref: '#/components/schemas/OnboardingAssetRequest'
          type: array
          title: Assets
          description: One or more assets to register at the site
          examples:
            - - external_id: charger-001
                type: charger
                asset_model: zappi
                installation_date: '2025-06-15'
                properties:
                  power_kw: 7.4
      type: object
      required:
        - site
        - assets
      title: InitialiseRequest
      description: |-
        Request model for initialising a site with one or more assets.

        Upserts the site and assets, returning eligibility information.
        No enrollment side effects (no dispatch consent, no bonus, no email).
    InitialiseResponse:
      properties:
        site:
          allOf:
            - $ref: '#/components/schemas/InitialiseSiteResult'
          title: Site
          description: Site result metadata
        assets:
          items:
            $ref: '#/components/schemas/InitialiseAssetResult'
          type: array
          title: Assets
          description: Per-asset result metadata
        eligibility:
          allOf:
            - $ref: '#/components/schemas/SiteEligibilityDetail'
          title: Eligibility
          description: Eligibility information for the site and its assets
      type: object
      required:
        - site
        - assets
        - eligibility
      title: InitialiseResponse
      description: Response model for the initialise endpoint.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SiteRequest:
      properties:
        mpan:
          type: string
          title: Mpan
          description: Meter Point Administration Number
        postcode:
          type: string
          title: Postcode
          description: UK postcode for the site
        street_address:
          type: string
          title: Street Address
          description: Street address for the site
        email:
          type: string
          title: Email
          description: >-
            Email address for the site. Include to enable 2FA for payment
            withdrawals.
        gave_boundary_meter_consent_at:
          type: string
          format: date-time
          title: Gave Boundary Meter Consent At
          description: >-
            Timezone-aware ISO 8601 timestamp (e.g. '2026-01-01T12:34:56Z')
            indicating when the household gave consent for Axle to access
            readings from their boundary meter, if consent was given.
      type: object
      required:
        - mpan
        - postcode
      title: SiteRequest
      description: Request model for creating a new site.
    OnboardingAssetRequest:
      properties:
        external_id:
          type: string
          title: External Id
          description: Vendor-specific identifier for the asset
          examples:
            - charger-001
        type:
          allOf:
            - $ref: '#/components/schemas/CreatableAssetType'
          description: Type of asset being created
          examples:
            - charger
        properties:
          allOf:
            - $ref: '#/components/schemas/AssetProperties'
          title: Properties
          description: Optional asset properties
          examples:
            - power_kw: 7.4
        asset_model:
          type: string
          title: Asset Model
          description: >-
            Name of the AssetModel to assign (looked up by name). Required for
            CoP11 eligibility.
          examples:
            - axle_charger_v1
        installation_date:
          type: string
          format: date
          title: Installation Date
          description: >-
            Date when the asset was installed. Required alongside asset_model
            for CoP11 eligibility.
          examples:
            - '2025-06-15'
      type: object
      required:
        - external_id
        - type
      title: OnboardingAssetRequest
      description: Request model for creating an asset during onboarding (without site_id).
    InitialiseSiteResult:
      properties:
        site_id:
          type: string
          format: uuid
          title: Site Id
          description: Axle's internal UUID for the site
        site_created:
          type: boolean
          title: Site Created
          description: True if the site was newly created, False if it was upserted
        fields_updated:
          items:
            type: string
          type: array
          title: Fields Updated
          description: List of site fields that were updated on upsert
        warnings:
          items:
            type: string
          type: array
          title: Warnings
          description: Site-level warnings generated during initialisation
      type: object
      required:
        - site_id
        - site_created
      title: InitialiseSiteResult
      description: Result metadata for a site after upsert.
    InitialiseAssetResult:
      properties:
        asset_id:
          type: string
          format: uuid
          title: Asset Id
          description: Axle's internal UUID for the asset
        external_id:
          type: string
          title: External Id
          description: Vendor-specific identifier for the asset
        asset_created:
          type: boolean
          title: Asset Created
          description: True if the asset was newly created, False if it was upserted
        fields_updated:
          items:
            type: string
          type: array
          title: Fields Updated
          description: List of fields that were updated on upsert
        warnings:
          items:
            type: string
          type: array
          title: Warnings
          description: Per-asset warnings generated during initialisation
      type: object
      required:
        - asset_id
        - external_id
        - asset_created
      title: InitialiseAssetResult
      description: Result metadata for a single asset after upsert.
    SiteEligibilityDetail:
      properties:
        eligible_propositions:
          items:
            type: string
            enum:
              - limited_pause
              - full_asset_schedule_control
          type: array
          title: Eligible Propositions
          default: []
        site_id:
          type: string
          format: uuid
          title: Site Id
          examples:
            - a1b2c3d4-e5f6-7890-abcd-ef1234567890
        site_properties:
          allOf:
            - $ref: '#/components/schemas/SiteProperties'
          title: Site Properties
          examples:
            - is_half_hourly_settled: false
              has_meter_consent: true
        assets:
          items:
            $ref: '#/components/schemas/AssetEligibilityDetail'
          type: array
          title: Assets
          default: []
      type: object
      required:
        - site_id
        - site_properties
      title: SiteEligibilityDetail
      description: Eligibility detail for a site's proposition eligibility check.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    CreatableAssetType:
      type: string
      enum:
        - charger
        - battery
        - heat pump
        - electric_vehicle
        - hot water tank
      title: CreatableAssetType
      description: Asset types that can be created through the API.
    AssetProperties:
      properties:
        power_kw:
          type: number
          minimum: 0
          title: Power Kw
          description: Power rating in kW
        capacity_kwh:
          type: number
          minimum: 0
          title: Capacity Kwh
          description: Capacity in kWh
      type: object
      title: AssetProperties
      description: Optional properties for an asset.
    SiteProperties:
      properties:
        is_half_hourly_settled:
          type: boolean
          title: Is Half Hourly Settled
        has_meter_consent:
          type: boolean
          title: Has Meter Consent
      type: object
      required:
        - is_half_hourly_settled
        - has_meter_consent
      title: SiteProperties
      description: Site-level properties relevant to eligibility evaluation.
    AssetEligibilityDetail:
      properties:
        asset_id:
          type: string
          format: uuid
          title: Asset Id
          examples:
            - b2c3d4e5-f6a7-8901-bcde-f23456789012
        external_id:
          type: string
          title: External Id
          examples:
            - charger-001
        propositions:
          items:
            $ref: '#/components/schemas/PropositionEligibility'
          type: array
          title: Propositions
          default: []
      type: object
      required:
        - asset_id
        - external_id
      title: AssetEligibilityDetail
      description: Eligibility detail for a single asset across all propositions.
    PropositionEligibility:
      properties:
        proposition:
          type: string
          enum:
            - limited_pause
            - full_asset_schedule_control
          title: Proposition
          examples:
            - limited_pause
        is_eligible:
          type: boolean
          title: Is Eligible
        issues:
          items:
            $ref: '#/components/schemas/EligibilityCode'
          type: array
          default: []
      type: object
      required:
        - proposition
        - is_eligible
      title: PropositionEligibility
      description: Eligibility detail for a single proposition.
    EligibilityCode:
      type: string
      enum:
        - asset_model_not_set
        - asset_model_not_found
        - asset_model_not_cop11_qualified
        - asset_installation_date_not_set
        - asset_model_enrol_eligibility_override
        - non_domestic_site
      title: EligibilityCode
      description: Codes identifying specific eligibility issues for an asset.
  securitySchemes:
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: auth/token-form

````