> ## 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.
# Onboard
> Initialise a site and its assets, and enrol them in a proposition in a single call.
This endpoint will:
1. Upsert the site and asset(s)
2. Enrol in the relevant flex proposition
The response returns the site and asset IDs you'll use in subsequent calls, and the enrolment outcome.
Onboarding is idempotent and atomic — sending the same site or asset returns the existing record with any new fields merged in; if enrolment fails, nothing is stored.
Already integrated against [`/onboard-site-and-asset`](./onboard-site-and-asset)?
It's still supported, but we'd recommend migrating to `/onboard` when convenient.
## OpenAPI
````yaml POST /entities/site/onboard
openapi: 3.1.0
info:
title: Axle API Docs
description: >-
For full documentation please see our official docs at docs.axle.energy
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/onboard:
post:
tags:
- 3. Sites
summary: Onboard
description: >-
Initialise a site and its assets, and enrol them in a proposition in a
single call.
This endpoint will:
1. Upsert the site and asset(s)
2. Enrol in the relevant flex proposition
The response returns the site and asset IDs you'll use in subsequent
calls, and the enrolment outcome.
Onboarding is idempotent and atomic — sending the same site or asset
returns the existing record with any new fields merged in; if enrolment
fails, nothing is stored.
operationId: onboard_entities_site_onboard_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OnboardRequest'
required: true
responses:
'200':
description: Site and assets persisted, site enrolled in proposition
content:
application/json:
schema:
$ref: '#/components/schemas/OnboardResponse'
example:
site:
site_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
site_created: true
fields_updated: []
warnings: []
assets:
- asset_id: b2c3d4e5-f6a7-8901-bcde-f23456789012
external_id: charger-001
asset_created: true
fields_updated: []
warnings: []
enrolment:
site_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
status: enrolled
'400':
description: Invalid request (missing meter consent, invalid email, etc.)
'404':
description: Referenced entity not found
'409':
description: >-
Asset conflict (e.g. asset type mismatch or asset registered to a
different site)
'422':
description: Eligibility prerequisites not met or previously withdrew consent
'500':
description: Server error
security:
- OAuth2PasswordBearer: []
components:
schemas:
OnboardRequest:
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
proposition:
type: string
enum:
- limited_pause
- full_asset_schedule_control
title: Proposition
description: Proposition to enrol the site in
override_withdrawal:
type: boolean
title: Override Withdrawal
description: Set to true to re-enrol regardless of previous withdrawals.
default: false
examples:
- false
type: object
required:
- site
- assets
- proposition
title: OnboardRequest
description: Request model for the onboard endpoint.
OnboardResponse:
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
enrolment:
allOf:
- $ref: '#/components/schemas/EnrolResponse'
title: Enrolment
description: Enrolment result
type: object
required:
- site
- assets
- enrolment
title: OnboardResponse
description: Response model for the onboard endpoint.
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.
EnrolResponse:
properties:
site_id:
type: string
format: uuid
title: Site Id
description: ID of the enrolled site
examples:
- a1b2c3d4-e5f6-7890-abcd-ef1234567890
status:
type: string
enum:
- enrolled
- already_enrolled
title: Status
description: >-
Outcome of the enrolment attempt. Both `enrolled` and
`already_enrolled` indicate success.
examples:
- enrolled
type: object
required:
- site_id
- status
title: EnrolResponse
description: Outcome of an enrolment attempt.
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.
securitySchemes:
OAuth2PasswordBearer:
type: oauth2
flows:
password:
scopes: {}
tokenUrl: auth/token-form
````