Skip to main content
POST
/
cot-events
Submit a Change of Tenancy Event
curl --request POST \
  --url https://api.central.consent/v1/cot-events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "mpxn": "1234567890123",
  "effective-date": "2026-04-01",
  "source-reference": "MPAS-COT-2026-03-00142"
}
'
{
  "response": {
    "resource": "/v1/access-records/ak_691df0c788ca043403b7fa90",
    "timestamp": "2026-03-11T12:00:00Z",
    "transaction-id": "tid_691df0c788ca043403b7fa90"
  },
  "mpxn": "1234567890123",
  "effective-date": "2026-04-01",
  "source-reference": "MPAS-COT-2026-03-00142",
  "active-records-affected": 2,
  "data-users-notified": [
    "duid_691df0c788ca043403b7fa90",
    "duid_aabbcc112233445566778899"
  ]
}

Authorizations

​
Authorization
string
header
required

JWT from GET /auth/token. Pass as Authorization: Bearer <token>. Expires after 7200s.

Body

application/json

A Change of Tenancy notification submitted by the DCC. Triggers tenancy.change webhooks to all Data Users with active access records on the affected MPxN.

​
mpxn
string
required

Meter Point Administration Number (MPAN) or Meter Point Reference Number (MPRN).

Pattern: ^(?:[0-9A-HJ-NPR-Z]{2}[0-9]{8,10}|[0-9]{10})$
Example:

"1234567890123"

​
effective-date
string<date>
required

The date on which the change of occupancy takes effect. Data access registered on behalf of the previous occupant should cease no later than this date.

Example:

"2026-04-01"

​
source-reference
string
required

The MPAS or DCC internal reference for this CoT notification. Used for idempotency and audit traceability. Submitting the same mpxn + effective-date + source-reference a second time returns 200 without re-firing webhooks.

Maximum string length: 255
Example:

"MPAS-COT-2026-03-00142"

Response

Duplicate event — same mpxn, effective-date, and source-reference already recorded. No webhooks re-fired.

Returned after a Change of Tenancy event is recorded. Summarises the Data Users notified and the number of records affected.

​
response
object
required
​
mpxn
string
required

Meter Point Administration Number (MPAN) or Meter Point Reference Number (MPRN).

Pattern: ^(?:[0-9A-HJ-NPR-Z]{2}[0-9]{8,10}|[0-9]{10})$
Example:

"1234567890123"

​
effective-date
string<date>
required
Example:

"2026-04-01"

​
source-reference
string
required
Example:

"MPAS-COT-2026-03-00142"

​
active-records-affected
integer
required

Number of ACTIVE access records across all Data Users on this MPxN at the time the event was processed.

Example:

2

​
data-users-notified
string[]
required

DUIDs of Data Users that received a tenancy.change webhook. Each entry had at least one ACTIVE access record on the MPxN.

Unique identifier for a registered Data User organisation, issued by the register at onboarding.

Pattern: ^duid_[0-9a-f]{24}$
Example:
[
  "duid_691df0c788ca043403b7fa90",
  "duid_aabbcc112233445566778899"
]
Last modified on March 25, 2026