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.

A 200 response always means the site and assets exist and the site is enrolled; enrolment.status only distinguishes a new enrolment from an existing one. Any failure returns an HTTP error with nothing persisted, so fix the cause and send the same request again.

POST /entities/site/onboard

Onboard

cURL

curl --request POST \
  --url https://api-sandbox.axle.energy/entities/site/onboard \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "site": {
    "email": "[e-mail]",
    "gave_boundary_meter_consent_at": "2026-01-15T10:30:00Z",
    "mpan": "1234567890123",
    "postcode": "SW1A 1AA",
    "street_address": "10 Downing Street"
  },
  "assets": [
    {
      "asset_model": "charger-model",
      "external_id": "charger-001",
      "installation_date": "2025-06-15",
      "properties": {
        "power_kw": 7.4
      },
      "type": "charger"
    }
  ],
  "proposition": "limited_pause",
  "override_withdrawal": false
}
'

200

{
  "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"
  }
}

Already integrated against /onboard-site-and-asset? It’s still supported, but we’d recommend migrating to /onboard when convenient.

Handling failures

A 200 response always means the site and assets were stored and the site is enrolled. enrolment.status only tells you whether the enrolment was new (enrolled) or already in place (already_enrolled).

An unsuccessful onboarding returns an HTTP error instead. The call is atomic, so on any error nothing is persisted: no site, no assets, no enrolment. Fix the cause and send the same request again.

Status	Meaning	What to do
400	Invalid request: missing gave_boundary_meter_consent_at, an invalid email, or no boundary consent terms registered for your organisation. detail is a plain message.	Correct the request. If the message mentions terms and conditions, contact Axle.
404	A referenced entity (such as an asset_model) doesn’t exist or isn’t visible to your organisation.	Check the identifiers.
409	An asset with this external_id already exists. detail.message says why and detail.existing_asset_id identifies it.	Registered to a different site: offboard the old site first, or use a different external_id. Different type, or owned by another organisation: contact Axle.
422 with detail.eligibility	The site or assets don’t meet the proposition’s prerequisites. detail.eligibility holds the per-site and per-asset breakdown.	Resolve the missing prerequisite, or use check eligibility up front.
422 with detail.code: "previously_withdrew"	The site previously withdrew from this proposition, for example via unenrol.	Resend with override_withdrawal: true. Recommended whenever the user asked to re-enrol.
500	Something went wrong on our side.	Retry; if it persists, contact Axle.

Rate limiting and request-body validation errors behave as on every other endpoint.

Authorizations

Authorization · string · header · required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

Request model for the onboard endpoint.

site · SiteRequest · object · required

Site information

Show child attributes

Example:

{
  "email": "[e-mail]",
  "gave_boundary_meter_consent_at": "2026-01-15T10:30:00Z",
  "mpan": "1234567890123",
  "postcode": "SW1A 1AA",
  "street_address": "10 Downing Street"
}

assets · OnboardingAssetRequest · object[] · required

One or more assets to register at the site

Show child attributes

Example:

[
  {
    "asset_model": "charger-model",
    "external_id": "charger-001",
    "installation_date": "2025-06-15",
    "properties": { "power_kw": 7.4 },
    "type": "charger"
  }
]

proposition · enum<string> · required

Proposition to enrol the site in

Available options: limited_pause, full_asset_schedule_control, price_curve

Example:

"limited_pause"

override_withdrawal · boolean · default: false

Set to true to re-enrol regardless of previous withdrawals.

Example:

false

Response

200

application/json

Site and assets persisted, site enrolled in proposition

Response model for the onboard endpoint.

site · InitialiseSiteResult · object · required

Site result metadata

Show child attributes

assets · InitialiseAssetResult · object[] · required

Per-asset result metadata

Show child attributes

enrolment · EnrolResponse · object · required

Enrolment result

Show child attributes