---
title: "Onboard"
method: POST
path: "/entities/site/onboard"
tags: ["3. Sites"]
---

# Onboard

`POST /entities/site/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.

## Request body

- OnboardRequest — Request model for the onboard endpoint.
  - `site` SiteRequest, required — Request model for creating a new site.
    - `mpan` string, required — Meter Point Administration Number
    - `postcode` string, required — UK postcode for the site
    - `street_address` string — Street address for the site
    - `email` string — Email address for the site. Include to enable 2FA for payment withdrawals.
    - `gave_boundary_meter_consent_at` string, date-time — 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.
  - `assets` OnboardingAssetRequest[], required — One or more assets to register at the site
    - `external_id` string, required — Vendor-specific identifier for the asset
    - `type` 'charger' | 'battery' | 'heat pump' | 'electric_vehicle' | 'hot water tank', required — Asset types that can be created through the API.
    - `properties` AssetProperties — Optional properties for an asset.
      - `power_kw` number — Power rating in kW
      - `capacity_kwh` number — Capacity in kWh
    - `asset_model` string — Name of the AssetModel to assign (looked up by name). Required for CoP11 eligibility.
    - `installation_date` string, date — Date when the asset was installed. Required alongside asset_model for CoP11 eligibility.
  - `proposition` 'limited_pause' | 'full_asset_schedule_control', required — Proposition to enrol the site in
  - `override_withdrawal` boolean — Set to true to re-enrol regardless of previous withdrawals.

## Response `200`

Site and assets persisted, site enrolled in proposition

- OnboardResponse — Response model for the onboard endpoint.
  - `site` InitialiseSiteResult, required — Result metadata for a site after upsert.
    - `site_id` string, uuid, required — Axle's internal UUID for the site
    - `site_created` boolean, required — True if the site was newly created, False if it was upserted
    - `fields_updated` string[] — List of site fields that were updated on upsert
    - `warnings` string[] — Site-level warnings generated during initialisation
  - `assets` InitialiseAssetResult[], required — Per-asset result metadata
    - `asset_id` string, uuid, required — Axle's internal UUID for the asset
    - `external_id` string, required — Vendor-specific identifier for the asset
    - `asset_created` boolean, required — True if the asset was newly created, False if it was upserted
    - `fields_updated` string[] — List of fields that were updated on upsert
    - `warnings` string[] — Per-asset warnings generated during initialisation
  - `enrolment` EnrolResponse, required — Outcome of an enrolment attempt.
    - `site_id` string, uuid, required — ID of the enrolled site
    - `status` 'enrolled' | 'already_enrolled', required — Outcome of the enrolment attempt. Both `enrolled` and `already_enrolled` indicate success.

## Other responses

- `400` — Invalid request (missing meter consent, invalid email, etc.)
- `404` — Referenced entity not found
- `409` — Asset conflict (e.g. asset type mismatch or asset registered to a different site)
- `422` — Eligibility prerequisites not met or previously withdrew consent
- `500` — Server error

---

[API](https://skmtc.dev/axle/apis/axle-api-docs.md) · [All operations](https://skmtc.dev/axle/apis/axle-api-docs/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/axle/axle-api-docs/revisions/75be7f9a952f/schema)