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.uktegp-kraken.systems/v2/data-import/accounts/validate/
Responses
The following responses may be returned from the API.
| Status code | Description |
|---|---|
200 - OK | The payload was validated successfully. Account validation success response:If the payload is valid, a 200 OK response will be returned with the empty payload as its body. {} |
400 - Bad Request | Validation errors occurred while processing the request. Account validation error response: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. {
"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 payload
{
"payload": {
"import_supplier": "TENTACLE_ENERGY",
"external_account_number": "EXTERNAL-1234",
"customers": [
{
"title": "Mr",
"given_name": "Robert",
"family_name": "Terwilliger",
"email": "bob@terwilliger.com",
"mobile": "07123456789",
"landline": "",
"date_of_birth": "1989-01-11",
"user_details": [
{
"namespace": "external_user_id",
"value": "1A2B3C4D5E6F7G8H9I"
}
],
"customer_preferences": {
"opted_into_sms": true,
"opted_into_recommended": true,
"opted_into_updates": true,
"opted_into_third_parties": true,
"opted_into_offers": true,
"is_user_psr_consent_obtained": true
}
}
],
"business": {
"business_contracts": [
{
"identifier": "C-1234"
}
]
},
"portfolio": {
"portfolio_references": [
{
"namespace": "external-portfolio-reference-id",
"value": "EXT-1111111111"
}
]
},
"billing_name": "Bob Industries",
"billing_address1": "123 Fake Street",
"billing_address2": "",
"billing_address3": "",
"billing_address4": "",
"billing_address5": "",
"billing_postcode": "W1F 9DE",
"unknown_occupier": false,
"account_type": "BUSINESS",
"sales_channel": "DIRECT",
"sales_subchannel": "",
"supply_addresses": [
{
"supply_address1": "123 Fake Street",
"supply_address2": "",
"supply_address3": "",
"supply_address4": "",
"supply_address5": "",
"supply_postcode": "W1F 9DE",
"is_landlord": false,
"customer_at_supply_address_from_date": "2019-01-01",
"meter_points": [
{
"identifier": "1200060176720",
"supply_type": "ELECTRICITY",
"agreements": [
{
"tariff_code": "ELEC-1234",
"effective_from": "2019-08-01"
}
],
"charge_exemptions": [
{
"proportion": 0.5,
"code": "test-charge-1",
"valid_from": "2024-08-01",
"valid_to": "2025-07-31",
"reference": "exemption-certificate-1"
}
],
"mpid": "TEGP",
"supply_start_date": "2019-01-01",
"profile_class": 3,
"ssc": "0058",
"meters": [
{
"meter_serial_number": "Z16N389556",
"installed_on": "2001-01-01",
"registers": [
{
"register_id": "1",
"tpr": "00001",
"number_of_digits": 5,
"last_billed_to_date": "2019-08-01"
},
{
"register_id": "X",
"tpr": "00043",
"number_of_digits": 5,
"is_settlement": false
}
],
"transfer_readings": [
{
"register_id": "1",
"reading_date": "2019-08-01",
"reading_value": "1000.00",
"reading_type": "CUSTOMER"
}
],
"reading_history": [
{
"register_id": "1",
"reading_date": "2019-06-20",
"reading_value": "980.00",
"reading_type": "CUSTOMER",
"billed": true
},
{
"register_id": "1",
"reading_date": "2019-05-20",
"reading_value": "960.00",
"reading_type": "ROUTINE",
"billed": true
}
]
}
],
"et_in_progress": false,
"dr_in_progress": false,
"eac_history": [
{
"effective_from": "2019-10-01",
"tpr": "00001",
"consumption": "1500",
"source": "D0019"
},
{
"effective_from": "2019-09-01",
"tpr": "00001",
"consumption": "1300",
"source": "D0019"
}
]
},
{
"identifier": "9353824109",
"supply_type": "GAS",
"agreements": [
{
"tariff_code": "GAS-1234",
"effective_from": "2019-08-01"
}
],
"mpid": "AAS",
"shipper_mpid": "TCL",
"supply_start_date": "2019-04-10",
"meters": [
{
"meter_serial_number": "54BV",
"installed_on": "2002-01-01",
"gas_number_of_digits": 5,
"smart_type": "SMETS1",
"last_billed_to_date": "2019-08-01",
"transfer_readings": [
{
"reading_date": "2019-08-01",
"reading_value": "500.00",
"reading_type": "CUSTOMER"
}
]
}
],
"et_in_progress": false,
"dr_in_progress": false,
"aq_history": [
{
"effective_from": "2019-01-01",
"consumption": "8720"
},
{
"effective_from": "2018-01-01",
"effective_to": "2018-12-31",
"consumption": "8712"
},
{
"effective_from": "2017-01-01",
"effective_to": "2017-12-31",
"consumption": "8716"
}
]
}
]
}
],
"ledgers": [
{
"ledger_code": "TOTALENERGIES_UK_ENERGY",
"last_statement_balance": 30,
"last_statement_closing_date": "2019-08-01",
"last_statement_issue_date": "2019-08-04",
"ledger_balance": 60,
"current_statement_transactions": [
{
"transaction_id": "4",
"transaction_date": "2019-08-05",
"amount": 10,
"type": "REPAYMENT",
"reason": "FULL_CREDIT_REFUND",
"payment_type": "CHEQUE"
},
{
"transaction_id": "5",
"transaction_date": "2019-08-03",
"amount": 20,
"type": "PAYMENT",
"reason": "ACCOUNT_CHARGE_PAYMENT",
"payment_type": "DD_FINAL_COLLECTION"
},
{
"transaction_id": "6",
"transaction_date": "2019-08-02",
"amount": 20,
"type": "CREDIT",
"reason": "IMPORTED_CREDIT"
}
],
"historical_statement_transactions": [
{
"transaction_id": "1",
"transaction_date": "2019-07-15",
"amount": 10,
"type": "CREDIT",
"reason": "IMPORTED_CREDIT"
},
{
"transaction_id": "2",
"transaction_date": "2019-06-01",
"amount": 10,
"type": "PAYMENT",
"reason": "ACCOUNT_CHARGE_PAYMENT",
"payment_type": "CREDIT_CARD"
},
{
"transaction_id": "3",
"transaction_date": "2019-05-01",
"amount": 10,
"type": "PAYMENT",
"reason": "ACCOUNT_CHARGE_PAYMENT",
"payment_type": "DEBIT_CARD"
}
]
}
],
"payment_schedules": [
{
"amount": "60.00",
"day_of_month": 2,
"frequency": "MONTHLY",
"means": "DD",
"start_date": "2018-01-01"
}
],
"payment_instructions": [
{
"vendor": "GOCARDLESS",
"type": "DIRECT_DEBIT",
"reference": "ABCD-1234-5678-EFGH",
"valid_from": "2022-06-15"
}
],
"billing_frequency_specification": [
{
"operation_type": "CHARGE_TARGET_AND_ISSUE_INVOICE",
"target_type": "ACCOUNT",
"frequency": "MONTHLY",
"multiplier": 1,
"trigger_at_start_day": 1,
"trigger_at_start_month": 5,
"temporal_params": [
{
"param_key": "charge_to",
"start_day": 1,
"start_month": 5
}
]
}
],
"references": [
{
"namespace": "tentacle-energy.some-unique-reference-number",
"value": "1234567890"
}
],
"notes": [
{
"created_at": "2018-10-10T10:20:00Z",
"body": "This is a note",
"document_paths": [
{
"document_path": "/notes/1234/attachment.jpg"
}
]
}
],
"statements": [
{
"bill_period_from_date": "2019-06-01",
"bill_period_to_date": "2019-07-01",
"statement_path": "/EXTERNAL-1234/2019-06-01-to-2019-07-01.pdf",
"statement_id": "54321"
},
{
"bill_period_from_date": "2019-07-01",
"bill_period_to_date": "2019-08-01",
"statement_path": "/EXTERNAL-1234/2019-07-01-to-2019-08-01.pdf",
"statement_id": "12345"
}
],
"account_campaigns": [
{
"slug": "super_account",
"campaign_note": "Campaign note"
}
],
"metadata": [
{
"key": "metadata_key",
"value": {
"some_data": "some_value"
}
}
]
}
}Overview
Use this endpoint to process account data into an account in Kraken.
Schema
Loading...
POST https://api.uktegp-kraken.systems/v2/data-import/accounts/
Responses
The following responses may be returned from the API.
| Status code | Description |
|---|---|
201 - Created | The payload has been successfully scheduled. Schedule account creation success response: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. {} |
400 - Bad Request | Validation errors occurred while processing the request. Schedule account creation error response (Validation Error):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. {
"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. {
"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 payload
{
"payload": {
"import_supplier": "TENTACLE_ENERGY",
"external_account_number": "EXTERNAL-1234",
"customers": [
{
"title": "Mr",
"given_name": "Robert",
"family_name": "Terwilliger",
"email": "bob@terwilliger.com",
"mobile": "07123456789",
"landline": "",
"date_of_birth": "1989-01-11",
"user_details": [
{
"namespace": "external_user_id",
"value": "1A2B3C4D5E6F7G8H9I"
}
],
"customer_preferences": {
"opted_into_sms": true,
"opted_into_recommended": true,
"opted_into_updates": true,
"opted_into_third_parties": true,
"opted_into_offers": true,
"is_user_psr_consent_obtained": true
}
}
],
"business": {
"business_contracts": [
{
"identifier": "C-1234"
}
]
},
"portfolio": {
"portfolio_references": [
{
"namespace": "external-portfolio-reference-id",
"value": "EXT-1111111111"
}
]
},
"billing_name": "Bob Industries",
"billing_address1": "123 Fake Street",
"billing_address2": "",
"billing_address3": "",
"billing_address4": "",
"billing_address5": "",
"billing_postcode": "W1F 9DE",
"unknown_occupier": false,
"account_type": "BUSINESS",
"sales_channel": "DIRECT",
"sales_subchannel": "",
"supply_addresses": [
{
"supply_address1": "123 Fake Street",
"supply_address2": "",
"supply_address3": "",
"supply_address4": "",
"supply_address5": "",
"supply_postcode": "W1F 9DE",
"is_landlord": false,
"customer_at_supply_address_from_date": "2019-01-01",
"meter_points": [
{
"identifier": "1200060176720",
"supply_type": "ELECTRICITY",
"agreements": [
{
"tariff_code": "ELEC-1234",
"effective_from": "2019-08-01"
}
],
"charge_exemptions": [
{
"proportion": 0.5,
"code": "test-charge-1",
"valid_from": "2024-08-01",
"valid_to": "2025-07-31",
"reference": "exemption-certificate-1"
}
],
"mpid": "TEGP",
"supply_start_date": "2019-01-01",
"profile_class": 3,
"ssc": "0058",
"meters": [
{
"meter_serial_number": "Z16N389556",
"installed_on": "2001-01-01",
"registers": [
{
"register_id": "1",
"tpr": "00001",
"number_of_digits": 5,
"last_billed_to_date": "2019-08-01"
},
{
"register_id": "X",
"tpr": "00043",
"number_of_digits": 5,
"is_settlement": false
}
],
"transfer_readings": [
{
"register_id": "1",
"reading_date": "2019-08-01",
"reading_value": "1000.00",
"reading_type": "CUSTOMER"
}
],
"reading_history": [
{
"register_id": "1",
"reading_date": "2019-06-20",
"reading_value": "980.00",
"reading_type": "CUSTOMER",
"billed": true
},
{
"register_id": "1",
"reading_date": "2019-05-20",
"reading_value": "960.00",
"reading_type": "ROUTINE",
"billed": true
}
]
}
],
"et_in_progress": false,
"dr_in_progress": false,
"eac_history": [
{
"effective_from": "2019-10-01",
"tpr": "00001",
"consumption": "1500",
"source": "D0019"
},
{
"effective_from": "2019-09-01",
"tpr": "00001",
"consumption": "1300",
"source": "D0019"
}
]
},
{
"identifier": "9353824109",
"supply_type": "GAS",
"agreements": [
{
"tariff_code": "GAS-1234",
"effective_from": "2019-08-01"
}
],
"mpid": "AAS",
"shipper_mpid": "TCL",
"supply_start_date": "2019-04-10",
"meters": [
{
"meter_serial_number": "54BV",
"installed_on": "2002-01-01",
"gas_number_of_digits": 5,
"smart_type": "SMETS1",
"last_billed_to_date": "2019-08-01",
"transfer_readings": [
{
"reading_date": "2019-08-01",
"reading_value": "500.00",
"reading_type": "CUSTOMER"
}
]
}
],
"et_in_progress": false,
"dr_in_progress": false,
"aq_history": [
{
"effective_from": "2019-01-01",
"consumption": "8720"
},
{
"effective_from": "2018-01-01",
"effective_to": "2018-12-31",
"consumption": "8712"
},
{
"effective_from": "2017-01-01",
"effective_to": "2017-12-31",
"consumption": "8716"
}
]
}
]
}
],
"ledgers": [
{
"ledger_code": "TOTALENERGIES_UK_ENERGY",
"last_statement_balance": 30,
"last_statement_closing_date": "2019-08-01",
"last_statement_issue_date": "2019-08-04",
"ledger_balance": 60,
"current_statement_transactions": [
{
"transaction_id": "4",
"transaction_date": "2019-08-05",
"amount": 10,
"type": "REPAYMENT",
"reason": "FULL_CREDIT_REFUND",
"payment_type": "CHEQUE"
},
{
"transaction_id": "5",
"transaction_date": "2019-08-03",
"amount": 20,
"type": "PAYMENT",
"reason": "ACCOUNT_CHARGE_PAYMENT",
"payment_type": "DD_FINAL_COLLECTION"
},
{
"transaction_id": "6",
"transaction_date": "2019-08-02",
"amount": 20,
"type": "CREDIT",
"reason": "IMPORTED_CREDIT"
}
],
"historical_statement_transactions": [
{
"transaction_id": "1",
"transaction_date": "2019-07-15",
"amount": 10,
"type": "CREDIT",
"reason": "IMPORTED_CREDIT"
},
{
"transaction_id": "2",
"transaction_date": "2019-06-01",
"amount": 10,
"type": "PAYMENT",
"reason": "ACCOUNT_CHARGE_PAYMENT",
"payment_type": "CREDIT_CARD"
},
{
"transaction_id": "3",
"transaction_date": "2019-05-01",
"amount": 10,
"type": "PAYMENT",
"reason": "ACCOUNT_CHARGE_PAYMENT",
"payment_type": "DEBIT_CARD"
}
]
}
],
"payment_schedules": [
{
"amount": "60.00",
"day_of_month": 2,
"frequency": "MONTHLY",
"means": "DD",
"start_date": "2018-01-01"
}
],
"payment_instructions": [
{
"vendor": "GOCARDLESS",
"type": "DIRECT_DEBIT",
"reference": "ABCD-1234-5678-EFGH",
"valid_from": "2022-06-15"
}
],
"billing_frequency_specification": [
{
"operation_type": "CHARGE_TARGET_AND_ISSUE_INVOICE",
"target_type": "ACCOUNT",
"frequency": "MONTHLY",
"multiplier": 1,
"trigger_at_start_day": 1,
"trigger_at_start_month": 5,
"temporal_params": [
{
"param_key": "charge_to",
"start_day": 1,
"start_month": 5
}
]
}
],
"references": [
{
"namespace": "tentacle-energy.some-unique-reference-number",
"value": "1234567890"
}
],
"notes": [
{
"created_at": "2018-10-10T10:20:00Z",
"body": "This is a note",
"document_paths": [
{
"document_path": "/notes/1234/attachment.jpg"
}
]
}
],
"statements": [
{
"bill_period_from_date": "2019-06-01",
"bill_period_to_date": "2019-07-01",
"statement_path": "/EXTERNAL-1234/2019-06-01-to-2019-07-01.pdf",
"statement_id": "54321"
},
{
"bill_period_from_date": "2019-07-01",
"bill_period_to_date": "2019-08-01",
"statement_path": "/EXTERNAL-1234/2019-07-01-to-2019-08-01.pdf",
"statement_id": "12345"
}
],
"account_campaigns": [
{
"slug": "super_account",
"campaign_note": "Campaign note"
}
],
"metadata": [
{
"key": "metadata_key",
"value": {
"some_data": "some_value"
}
}
]
}
}Overview
Use this endpoint to retrieve the current status of an account import.
GET https://api.uktegp-kraken.systems/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": "PENDING | DRY_RUN_SUCCEEDED | PROCESSED | CANCELLED | IN_PROGRESS",
"kraken_identifier": null,
"created_at": "2025-10-07T09:00:21.179194+02:00",
"modified_at": "2025-10-07T09:06:38.078396+02:00",
"latest_event": {
"event": "EVENT_ACCOUNT_IMPORT_PROCESS_CREATED",
"occurred_at": "2025-10-07T09:00:21.179194+02:00",
"data": null
},
"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_event": {
"event": "EVENT_ACCOUNT_IMPORT_PROCESS_PROCESSED",
"occurred_at": "2025-10-07T09:06:38.078396+02:00",
"data": null
},
"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_event": {
"event": "EVENT_ACCOUNT_IMPORT_PROCESS_ERRORED",
"occurred_at": "2025-10-07T09:06:38.078396+02:00",
"data": {
"code": "some_error_code",
"detail": "A detailed error message",
"domain": "import_process"
}
},
"latest_error": {
"code": "some_error_code",
"detail": "A detailed error message",
"domain": "import_process"
}
} |
404 - Not Found |
If the account import process does not exist, a {
"detail": "The requested resource was not found.",
"code": "not_found"
} |