Customer Migrations Guide: Account Import
This page documents the data import APIs for account creation.
API Endpoints
Overview
Use this endpoint to validate account data before creating an account.
Schema
Loading...
POST https://api.nationalgrid-kraken.energy/v2/data-import/accounts/validate/
Responses
The following responses may be returned from the API.
| Status code | Description |
|---|---|
200 - OK | If the payload is valid, a 200 OK response will be returned with the empty payload as its body. Example:{} |
400 - Bad Request | If there are validation errors a 400 Bad Request response will be returned detailing the errors. To resolve these errors, refer to the field definitions and validation rules. Example:{
"detail": "Could not validate account data.",
"code": "account_failed_validation",
"errors": [
{
"detail": "abcde is not a valid phone number",
"code": "invalid_phone_number",
"attr": "customers.0.landline"
}
]
} |
Payloads
Example National Grid account payload with property details
{
"import_supplier": "<IMPORT_SUPPLIER>",
"external_account_number": "8888888889",
"billing_address": {
"street_address": "3000 Main St",
"locality": "Revere",
"administrative_area": "MA",
"postal_code": "02151",
"country": "US"
},
"metadata": [
{
"key": "metadata_key",
"value": {
"some_data": "some_value"
}
}
],
"customers": [
{
"given_name": "Sarah",
"family_name": "Johnson",
"email": "some.email@example.com",
"mobile": "+15066585252",
"landline": "",
"date_of_birth": "1988-08-08",
"alternative_phone_numbers": [
{
"phone_number": "+15066585251"
}
],
"customer_preferences": {
"opted_into_updates": true,
"opted_into_offers": true,
"opted_into_sms": true
},
"user_details": [
{
"namespace": "external_user_id",
"value": "8888888889"
},
{
"namespace": "middle_name",
"value": "F"
},
{
"namespace": "suffix",
"value": "Jr"
},
{
"namespace": "tax_id",
"value": "012345678"
},
{
"namespace": "driver_license_number",
"value": "0123456789"
},
{
"namespace": "driver_license_state",
"value": "MA"
},
{
"namespace": "experian_pin_id",
"value": "0123456789"
}
]
}
],
"notes": [
{
"created_at": "2024-06-01T12:00:00Z",
"body": "Some important pinned note.",
"is_pinned": true,
"unpin_at": "2024-08-01T12:00:00Z"
},
{
"created_at": "2024-07-01T12:00:00Z",
"body": "Some important note with attachments.",
"document_paths": [
{
"document_path": "some/path/to/a/document.pdf"
},
{
"document_path": "some/other/path/to/a/document.pdf"
}
]
}
],
"ledgers": [
{
"ledger_code": "ENERGY",
"billing_document_type": "ITEM_BASED",
"ledger_balance": "-200",
"last_statement_closing_date": "2026-03-01",
"last_statement_issue_date": "2026-03-01",
"historical_billing_documents": [
{
"billing_document_identifier": "INV-530",
"billing_document_type": "ITEM_BASED",
"issued_date": "2026-02-01",
"transactions": [
{
"transaction_id": "1",
"type": "CHARGE",
"reason": "DATA_IMPORT_BALANCE_TRANSFER",
"amount": "100",
"transaction_date": "2026-02-01"
}
]
},
{
"billing_document_identifier": "INV-430",
"billing_document_type": "ITEM_BASED",
"issued_date": "2026-03-01",
"transactions": [
{
"transaction_id": "2",
"type": "CHARGE",
"reason": "DATA_IMPORT_BALANCE_TRANSFER",
"amount": "100",
"transaction_date": "2026-03-01"
}
]
}
],
"additional_historical_transactions": [],
"current_statement_transactions": []
}
],
"supply_addresses": [
{
"customer_at_supply_address_from_date": "2025-03-01",
"supply_address": {
"street_address": "3000 Main St",
"locality": "Revere",
"administrative_area": "MA",
"postal_code": "02151",
"country": "US"
},
"external_identifier": "NG-SITE-PREM-01",
"property_details": {
"driving_instructions": "Park on the street",
"property_type_specific_details": {
"property_type": "Premise",
"premise_type": "SINGLE_FAMILY",
"entry_instructions": "Key under mat"
}
},
"supply_points": [
{
"supply_type": "ELECTRICITY",
"identifier": "2102",
"operating_company": "MASSACHUSETTS_ELECTRIC",
"supply_start_date": "2025-03-01",
"last_billed_to_date": "2026-03-01",
"agreements": [
{
"effective_from": "2025-03-01",
"tariff_code": "<TARIFF_CODE>",
"characteristics": [
{
"code": "MECO-R1-FixVar",
"value": "FIXED"
}
]
}
],
"supply_details": {
"standard_point_location_code": "WCMASS",
"load_profile_code": "LP001",
"service_drop": {
"external_identifier": "SD-NG-BASE-001",
"distribution_line_style": "underground",
"delivery_voltage": "0 - 2.2 kv",
"metering_type": "primary"
}
},
"meters": [
{
"active_from": "2025-09-01T00:00:00Z",
"serial_number": "MTR123456",
"status": "on",
"service_type": "metered_service_kwh",
"voltage": 240,
"size": 100,
"phase": "Single",
"retrieval_method": "AMI",
"model": "MODEL-X",
"manufacturer": "Duncan-L&G",
"advance_meter_info": "AMI",
"is_net_metered": true,
"registers": [
{
"register_type": "KWH_IMPORT",
"digits": 5,
"multiplier": "1"
}
]
}
]
}
]
}
]
}Overview
Use this endpoint to process account data into an account in Kraken.
Schema
Loading...
POST https://api.nationalgrid-kraken.energy/v2/data-import/accounts/
Responses
The following responses may be returned from the API.
| Status code | Description |
|---|---|
201 | If the payload is valid and an account creation has been scheduled, a 201 Created response will be returned with the empty payload as its body. Example:{} |
400 - Bad Request | If there are validation errors, a 400 Bad Request response will be returned detailing the errors. To resolve these errors, refer to the field definitions and validation rules. Example:{
"code": "import_process_failed_validation",
"detail": "Import process validation failed during account creation. Please validate the import process to get full details of the validation errors.",
"domain": "import_process"
}If an account has already been imported, a 400 Bad Request response will be returned with account_id representing existing Kraken account number. Example:{
"non_field_errors": {
"detail": "The account import process with the account number 1234567890 has already been imported.",
"code": "account_import_process_already_imported"
},
"account_id": "A-12345678"
} |
Payloads
Example National Grid account payload with property details
{
"import_supplier": "<IMPORT_SUPPLIER>",
"external_account_number": "8888888889",
"billing_address": {
"street_address": "3000 Main St",
"locality": "Revere",
"administrative_area": "MA",
"postal_code": "02151",
"country": "US"
},
"metadata": [
{
"key": "metadata_key",
"value": {
"some_data": "some_value"
}
}
],
"customers": [
{
"given_name": "Sarah",
"family_name": "Johnson",
"email": "some.email@example.com",
"mobile": "+15066585252",
"landline": "",
"date_of_birth": "1988-08-08",
"alternative_phone_numbers": [
{
"phone_number": "+15066585251"
}
],
"customer_preferences": {
"opted_into_updates": true,
"opted_into_offers": true,
"opted_into_sms": true
},
"user_details": [
{
"namespace": "external_user_id",
"value": "8888888889"
},
{
"namespace": "middle_name",
"value": "F"
},
{
"namespace": "suffix",
"value": "Jr"
},
{
"namespace": "tax_id",
"value": "012345678"
},
{
"namespace": "driver_license_number",
"value": "0123456789"
},
{
"namespace": "driver_license_state",
"value": "MA"
},
{
"namespace": "experian_pin_id",
"value": "0123456789"
}
]
}
],
"notes": [
{
"created_at": "2024-06-01T12:00:00Z",
"body": "Some important pinned note.",
"is_pinned": true,
"unpin_at": "2024-08-01T12:00:00Z"
},
{
"created_at": "2024-07-01T12:00:00Z",
"body": "Some important note with attachments.",
"document_paths": [
{
"document_path": "some/path/to/a/document.pdf"
},
{
"document_path": "some/other/path/to/a/document.pdf"
}
]
}
],
"ledgers": [
{
"ledger_code": "ENERGY",
"billing_document_type": "ITEM_BASED",
"ledger_balance": "-200",
"last_statement_closing_date": "2026-03-01",
"last_statement_issue_date": "2026-03-01",
"historical_billing_documents": [
{
"billing_document_identifier": "INV-530",
"billing_document_type": "ITEM_BASED",
"issued_date": "2026-02-01",
"transactions": [
{
"transaction_id": "1",
"type": "CHARGE",
"reason": "DATA_IMPORT_BALANCE_TRANSFER",
"amount": "100",
"transaction_date": "2026-02-01"
}
]
},
{
"billing_document_identifier": "INV-430",
"billing_document_type": "ITEM_BASED",
"issued_date": "2026-03-01",
"transactions": [
{
"transaction_id": "2",
"type": "CHARGE",
"reason": "DATA_IMPORT_BALANCE_TRANSFER",
"amount": "100",
"transaction_date": "2026-03-01"
}
]
}
],
"additional_historical_transactions": [],
"current_statement_transactions": []
}
],
"supply_addresses": [
{
"customer_at_supply_address_from_date": "2025-03-01",
"supply_address": {
"street_address": "3000 Main St",
"locality": "Revere",
"administrative_area": "MA",
"postal_code": "02151",
"country": "US"
},
"external_identifier": "NG-SITE-PREM-01",
"property_details": {
"driving_instructions": "Park on the street",
"property_type_specific_details": {
"property_type": "Premise",
"premise_type": "SINGLE_FAMILY",
"entry_instructions": "Key under mat"
}
},
"supply_points": [
{
"supply_type": "ELECTRICITY",
"identifier": "2102",
"operating_company": "MASSACHUSETTS_ELECTRIC",
"supply_start_date": "2025-03-01",
"last_billed_to_date": "2026-03-01",
"agreements": [
{
"effective_from": "2025-03-01",
"tariff_code": "<TARIFF_CODE>",
"characteristics": [
{
"code": "MECO-R1-FixVar",
"value": "FIXED"
}
]
}
],
"supply_details": {
"standard_point_location_code": "WCMASS",
"load_profile_code": "LP001",
"service_drop": {
"external_identifier": "SD-NG-BASE-001",
"distribution_line_style": "underground",
"delivery_voltage": "0 - 2.2 kv",
"metering_type": "primary"
}
},
"meters": [
{
"active_from": "2025-09-01T00:00:00Z",
"serial_number": "MTR123456",
"status": "on",
"service_type": "metered_service_kwh",
"voltage": 240,
"size": 100,
"phase": "Single",
"retrieval_method": "AMI",
"model": "MODEL-X",
"manufacturer": "Duncan-L&G",
"advance_meter_info": "AMI",
"is_net_metered": true,
"registers": [
{
"register_type": "KWH_IMPORT",
"digits": 5,
"multiplier": "1"
}
]
}
]
}
]
}
]
}Overview
Use this endpoint to retrieve the current status of an account import.
GET https://api.nationalgrid-kraken.energy/v2/data-import/accounts/<import-supplier-code>/<external-identifier>/
Responses
The following responses may be returned from the API.
| Status code | Description |
|---|---|
200 - OK |
If the account import process exists, a For example when there is no error in processing: {
"status": "PROCESSED | CANCELLED | IN_PROGRESS | DRY_RUN_SUCCEEDED | PENDING",
"kraken_identifier": null,
"created_at": "2025-10-07T09:00:21.179194+02:00",
"modified_at": "2025-10-07T09:06:38.078396+02:00",
"latest_error": null
}For example when the import process is processed we have an internal kraken id: {
"status": "PROCESSED",
"kraken_identifier": "INTERNAL-KRAKEN-IDENTIFIER",
"created_at": "2025-10-07T09:00:21.179194+02:00",
"modified_at": "2025-10-07T09:06:38.078396+02:00",
"latest_error": null
}For example when there is an error in processing: {
"status": "ERRORED | DRY_RUN_ERRORED",
"kraken_identifier": null,
"created_at": "2025-10-07T09:00:21.179194+02:00",
"modified_at": "2025-10-07T09:06:38.078396+02:00",
"latest_error": {
"code": "some_error_code",
"detail": "A detailed error message",
"domain": "account_import"
}
} |
404 - Not Found |
If the account import process does not exist, a {
"detail": "The requested resource was not found.",
"code": "not_found"
} |