Change of Supplier Schema Reference

Headers and Parameters

Field	Location	Required	Type	Format / Constraints
X-API-KEY	Header	Yes	string	UUID format
X-IDEMPOTENCY-KEY	Header (POST)	Yes	string	Non-empty string
X-TEST-MODE	Header (v1 POST)	No	string	Optional; "true" enables test mode
mpid	Path	Yes	string	Supplier MPID

v1 Request Schema (CoSRequestSchema)

Field	Required	Type	Format / Constraints
mpan_core	Yes	integer	Exactly 13 digits, numeric (^\d{13}$)
supply_start_date	Yes	string(datetime)	ISO 8601 with timezone; must be midnight; cannot be in the past; cannot be > 28 days ahead; min lead-time: 1 working day (domestic), 2 working days (non-domestic)
ofaf_ref	No	string or null	If provided: length 1-50
domestic_indicator	Yes	boolean	true or false
is_initial_registration	Yes	boolean	true or false
change_of_occupancy_indicator	No	boolean or null	If provided: true or false; defaults false
erroneous_switch_resolution_indicator	No	boolean or null	If provided: true or false; cannot be true when is_initial_registration is true; defaults false
supplier_reference	No	string or null	If provided: length 1-50

Additional validation:

• Extra/unknown fields are rejected.

v2 Request Schema (CosRequestSchemaV2)

CosRequestSchemaV2 includes all fields from CoSRequestSchema plus the fields below.

Field	Required	Type	Format / Constraints
ms_appointment_request	No	object or null	Optional object
ms_appointment_request.metering_service_mpid	No	string or null	Subject to appointment-request business validation
ms_appointment_request.contract_reference	No	string or null	Subject to appointment-request business validation
ds_appointment_request	No	object or null	Optional object
ds_appointment_request.data_service_mpid	No	string or null	Subject to appointment-request business validation
ds_appointment_request.contract_reference	No	string or null	Subject to appointment-request business validation
ds_appointment_request.mdr_mpid	No	string or null	Subject to appointment-request business validation
ds_appointment_request.consent_granularity	No	string or null	Subject to appointment-request business validation
ds_appointment_request.fall_back_read_frequency	No	string or null	Subject to appointment-request business validation
psr_details	No	object or null	Optional object
psr_details.primary_psr_contact_name	Yes (when object provided)	string	Max 50 chars
psr_details.primary_psr_phone_number_1	Conditional	string or null	UK phone regex `^(?:0
psr_details.primary_psr_phone_number_2	No	string or null	Same phone regex
psr_details.alternate_psr_contact_name	No	string or null	Max 50 chars
psr_details.alternate_psr_phone_number_1	No	string or null	Same phone regex
psr_details.alternate_psr_phone_number_2	No	string or null	Same phone regex
psr_details.psr_address_line_1 .. psr_details.psr_address_line_9	Conditional	string or null	Max 40 chars each; at least one address line or primary_psr_phone_number_1 must be provided
psr_details.psr_postcode	Conditional	string or null	Max 10 chars; required when any PSR address line is present
psr_details.lawful_basis_for_sharing	Yes (when object provided)	boolean	true or false
psr_details.psr_details	Yes (when object provided)	array	Must be non-empty
psr_details.psr_details[].psr_category	Yes	string	Exactly 2 chars; allowed values: 01,02,03,04,08,09,10,12,14,15,17,18,19,20,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37
psr_details.psr_details[].psr_expiry_date	Conditional	string or null	Required for categories 29,32,33,34; format YYYYMMDD; must be a future date
psr_details.psr_details[].additional_information	Conditional	string or null	Required for category 17; max 200 chars
contact_details	No	array or null	Optional list of ContactCustomerRequestSchema objects
contact_details[].customer_name	Yes	string	Max 20 chars
contact_details[].additional_information	No	string or null	Max 200 chars
contact_details[].customer_password	No	string or null	Max 10 chars
contact_details[].customer_password_efd	No	string(date) or datetime or null	If string, format YYYY-MM-DD
contact_details[].special_access	No	string or null	Max 40 chars
contact_details[].max_power_req	No	integer or null	Integer, >= 0, max 6 digits
contact_details[].delete_address_data	No	boolean or null	true or false
contact_details[].mailing_address_1 .. contact_details[].mailing_address_9	No	string or null	Max 40 chars each
contact_details[].mailing_address_postcode	No	string or null	Max 10 chars
contact_details[].contacts	Yes	array	List of contact records
contact_details[].contacts[].contact_name	Yes	string	Max 30 chars
contact_details[].contacts[].preferred_contact_method	No	string(enum) or null	Allowed values: E, H, L, T, W
contact_details[].contacts[].telephones	Yes	array	Must be non-empty
contact_details[].contacts[].telephones[].telephone_number	Yes	string	UK phone regex `^(?:0
contact_details[].contacts[].telephones[].fax_number	No	string or null	Same phone regex
contact_details[].contacts[].emails	Yes	array	Must be a list (can be empty)
contact_details[].contacts[].emails[].email_address	No	string or null	If provided: valid email format and max 100 chars

Additional validation:

• Extra/unknown fields are rejected.

Common Response Schema (CoSProcessResponseSchema)

Used by:

• POST /change-of-supplier/v1/{mpid}
• POST /change-of-supplier/v2/{mpid}

Field	Required	Type	Format / Constraints
request_id	Yes	string	UUID
request_type	Yes	string	Process type name
request_status	Yes	string(enum)	Pending, Success, Failed
description	No	string or null	Process type description
created_at	Yes	string(datetime)	ISO 8601 datetime
last_updated_at	Yes	string(datetime)	ISO 8601 datetime
mpan_core	Yes	integer	MPAN core
css_reg_id	No	string or null	CSS registration ID
css_reg_status	No	string or null	CSS registration status