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

Creates a Change of Supplier process for one MPAN (v2).

Compared with v1, v2 supports additional optional nested payload sections for automation:

• ms_appointment_request
• ds_appointment_request
• psr_details
• contact_details

Request

Method and path:

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

Headers:

• X-API-KEY (required): string (UUID format).
• X-IDEMPOTENCY-KEY (required): string.

Path parameters:

• mpid (required): string supplier MPID.

Body schema:

• CosRequestSchemaV2

{
  "mpan_core": 1234567890123,
  "supply_start_date": "2026-03-20T00:00:00+00:00",
  "ofaf_ref": "OFAF-1234",
  "domestic_indicator": true,
  "is_initial_registration": false,
  "change_of_occupancy_indicator": false,
  "erroneous_switch_resolution_indicator": false,
  "supplier_reference": "SUP-REF-001",
  "ms_appointment_request": {
    "metering_service_mpid": "ABCD",
    "contract_reference": "MS-REF-001"
  },
  "ds_appointment_request": {
    "data_service_mpid": "ABCD",
    "contract_reference": "DS-REF-001",
    "mdr_mpid": "WXYZ",
    "consent_granularity": "H",
    "fall_back_read_frequency": "M"
  },
  "psr_details": {
    "primary_psr_contact_name": "Jane Doe",
    "primary_psr_phone_number_1": "07123456789",
    "primary_psr_phone_number_2": null,
    "alternate_psr_contact_name": "John Doe",
    "alternate_psr_phone_number_1": "+44 7123 456789",
    "alternate_psr_phone_number_2": null,
    "psr_address_line_1": "Flat 1",
    "psr_address_line_2": "10 High Street",
    "psr_address_line_3": null,
    "psr_address_line_4": null,
    "psr_address_line_5": null,
    "psr_address_line_6": null,
    "psr_address_line_7": null,
    "psr_address_line_8": null,
    "psr_address_line_9": null,
    "psr_postcode": "AB1 2CD",
    "lawful_basis_for_sharing": true,
    "psr_details": [
      {
        "psr_category": "01",
        "psr_expiry_date": null,
        "additional_information": null
      },
      {
        "psr_category": "29",
        "psr_expiry_date": "20270401",
        "additional_information": null
      }
    ]
  },
  "contact_details": [
    {
      "customer_name": "Jane Smith",
      "additional_information": "Prefers SMS after 6pm",
      "customer_password": "BLUE10",
      "customer_password_efd": "2026-03-20",
      "special_access": "Rear gate access",
      "max_power_req": 120,
      "delete_address_data": false,
      "mailing_address_1": "Flat 1",
      "mailing_address_2": "10 High Street",
      "mailing_address_3": null,
      "mailing_address_4": null,
      "mailing_address_5": null,
      "mailing_address_6": null,
      "mailing_address_7": null,
      "mailing_address_8": null,
      "mailing_address_9": null,
      "mailing_address_postcode": "AB1 2CD",
      "contacts": [
        {
          "contact_name": "Jane Smith",
          "preferred_contact_method": "E",
          "telephones": [
            {
              "telephone_number": "07123456789",
              "fax_number": null
            }
          ],
          "emails": [
            {
              "email_address": "jane.smith@example.com"
            }
          ]
        }
      ]
    }
  ]
}

Nested schema details (v2-only fields)

psr_details object

Field	Required	Type	Constraints
primary_psr_contact_name	Yes	string	Max 50 chars
primary_psr_phone_number_1	Conditionally required	string or null	UK phone regex: `^(?:0
primary_psr_phone_number_2	No	string or null	Same phone regex as above
alternate_psr_contact_name	No	string or null	Max 50 chars
alternate_psr_phone_number_1	No	string or null	Same phone regex as above
alternate_psr_phone_number_2	No	string or null	Same phone regex as above
psr_address_line_1 .. psr_address_line_9	Conditionally required	string or null	Max 40 chars each; at least one address line or primary_psr_phone_number_1 must be provided
psr_postcode	Conditionally required	string or null	Max 10 chars; required when any address line is present
lawful_basis_for_sharing	Yes	boolean	true or false
psr_details	Yes	array	Must be non-empty

psr_details[] item fields:

Field	Required	Type	Constraints
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_expiry_date	Conditional	string or null	Required for categories 29,32,33,34; format YYYYMMDD; must be a future date
additional_information	Conditional	string or null	Required for category 17; max 200 chars

contact_details array

contact_details is an array of customer contact records.

Customer object fields:

Field	Required	Type	Constraints
customer_name	Yes	string	Max 20 chars
additional_information	No	string or null	Max 200 chars
customer_password	No	string or null	Max 10 chars
customer_password_efd	No	string(datetime) or datetime or null	If string, format YYYY-MM-DD
special_access	No	string or null	Max 40 chars
max_power_req	No	integer or null	Integer, >= 0, max 6 digits
delete_address_data	No	boolean or null	true or false
mailing_address_1 .. mailing_address_9	No	string or null	Max 40 chars each
mailing_address_postcode	No	string or null	Max 10 chars
contacts	Yes	array	Must be a list of contact objects

contacts[] object fields:

Field	Required	Type	Constraints
contact_name	Yes	string	Max 30 chars
preferred_contact_method	No	string(enum) or null	Allowed values: E, H, L, T, W
telephones	Yes	array	Must be non-empty
emails	Yes	array	Must be a list (can be empty)

contacts[].telephones[] fields:

Field	Required	Type	Constraints
telephone_number	Yes	string	UK phone regex: `^(?:0
fax_number	No	string or null	Same regex as telephone_number

contacts[].emails[] fields:

Field	Required	Type	Constraints
email_address	No	string or null	If provided: valid email format and max 100 chars

Response

Success:

• 202 Accepted
• Body type: CoSProcessResponseSchema (same shape as v1)

Other documented responses:

• 401 Unauthorized
• 409 Conflict
• 422 Validation error
• 428 Missing X-IDEMPOTENCY-KEY

Field-level constraints:

• Schema Reference