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.frteegf-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. The warnings field is omitted when deprecation warnings are disabled. Account validation success response:If the payload is valid, a 200 OK response will be returned with a warnings array when deprecation warnings are enabled. {
"warnings": []
}The warnings field is omitted when deprecation warnings are disabled. {} |
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
Domestic account
{
"payload": {
"external_account_number": "EXTERNAL-1234",
"import_supplier": "TENTACLE_ENERGY",
"billing_address1": "126 Rue de l'Université",
"billing_address2": "",
"billing_address3": "",
"billing_address4": "Paris",
"billing_postcode": "75007",
"sales_channel": "DIRECT",
"sales_subchannel": "Website",
"last_billed_to_date": "2022-08-14",
"customers": [
{
"title": "M.",
"given_name": "Robert",
"family_name": "Terwilliger",
"email": "robert.terwilliger@gmail.com",
"mobile": "+33809685772",
"landline": "",
"date_of_birth": "1957-10-11",
"deceased": "",
"customer_preferences": {
"opted_into_updates": true,
"opted_into_sms": false,
"opted_into_offers": true,
"opted_into_recommended": false
}
}
],
"supply_addresses": [
{
"supply_address1": "126 Rue de l'Université",
"supply_address2": "",
"supply_address3": "",
"supply_address4": "Paris",
"supply_postcode": "75007",
"customer_at_supply_address_from_date": "2019-04-01",
"supply_points": [
{
"identifier": "46147259228742",
"supply_type": "ELECTRICITY",
"supply_start_date": "2021-07-29",
"payment_schedules": [
{
"amount": 60.0,
"day_of_month": 2,
"frequency": "MONTHLY",
"means": "DD",
"start_date": "2022-01-01"
}
],
"payment_instructions": [
{
"vendor": "GOCARDLESS",
"reference": "SUPPLIER-ELEC-1234",
"type": "DIRECT_DEBIT",
"valid_from": "2022-06-15"
}
],
"billing_frequency": 12,
"agreements": [
{
"tariff_code": "ELEC-123",
"agreed_at": "2021-07-25T10:03:00+02:00",
"effective_from": "2021-08-01",
"effective_to": "2022-08-01",
"addons": [
{
"band": "GREEN_POWER_50"
}
]
},
{
"tariff_code": "ELEC-456",
"agreed_at": "2022-07-25T10:03:00+02:00",
"effective_from": "2022-08-01",
"effective_to": "2023-08-01",
"addons": [
{
"band": "GREEN_POWER_55"
}
]
},
{
"tariff_code": "ELEC-789",
"agreed_at": "2023-07-21T14:05:00+02:00",
"effective_from": "2023-08-01",
"addons": [
{
"band": "CARBON_OFFSET_50"
}
]
}
],
"consent_data": {
"ELEC_CURVES": true,
"ELEC_INDEXES": false
}
},
{
"identifier": "35438560738869",
"supply_type": "GAS",
"supply_start_date": "2021-07-29",
"payment_schedules": [
{
"amount": 55.0,
"day_of_month": 2,
"frequency": "MONTHLY",
"means": "DD",
"start_date": "2022-01-01"
}
],
"payment_instructions": [
{
"vendor": "GOCARDLESS",
"reference": "SUPPLIER-GAS-12345",
"type": "DIRECT_DEBIT",
"valid_from": "2022-06-15"
}
],
"billing_frequency": 12,
"agreements": [
{
"tariff_code": "GAS-123",
"agreed_at": "2021-07-25T10:03:00+02:00",
"effective_from": "2021-08-01",
"effective_to": "2022-08-01"
},
{
"tariff_code": "GAS-456",
"agreed_at": "2022-07-25T10:03:00+02:00",
"effective_from": "2022-08-01",
"effective_to": "2023-08-01"
},
{
"tariff_code": "GAS-789",
"agreed_at": "2023-07-21T14:05:00+02:00",
"effective_from": "2023-08-01"
}
],
"consent_data": {
"GAS_INDEXES": true
}
}
]
}
],
"statements": [
{
"bill_period_from_date": "2021-01-01",
"bill_period_to_date": "2022-01-01",
"statement_path": "EXTERNAL-1234/2021-01-01-to-2022-01-01-electricity.pdf",
"statement_id": "1"
}
],
"supplementary_ledgers": [
{
"ledger_code": "ENERGY_CHEQUE_LEDGER",
"energy_cheques": [
{
"number": "1232542",
"protection_from": "2023-01-01",
"protection_to": "2023-06-01",
"source": "PAPERLESS",
"asp_remittance_ref": "abcdefg-1234567",
"amount": 1234,
"valid_to": "2023-06-01",
"status": "VALID"
}
]
}
],
"notes": [
{
"created_at": "2018-10-10T10:20:00Z",
"body": "This is a note",
"document_paths": [
{
"document_path": "/notes/1234/attachment.jpg"
}
]
}
],
"account_campaigns": [
{
"slug": "super_account",
"campaign_note": "Campaign note"
}
],
"metadata": [
{
"key": "metadata_key",
"value": {
"some_data": "some_value"
}
}
]
}
}Business account
{
"payload": {
"external_account_number": "EXTERNAL-1234",
"import_supplier": "TENTACLE_ENERGY",
"account_type": "BUSINESS",
"business": {
"business_type": "EURL",
"siret": "60487647400494",
"details": [
{
"key": "siren",
"value": "60487647400494"
}
]
},
"billing_address1": "126 Rue de l'Université",
"billing_address2": "",
"billing_address3": "",
"billing_address4": "Paris",
"billing_postcode": "75007",
"sales_channel": "DIRECT",
"sales_subchannel": "Website",
"last_billed_to_date": "2022-08-14",
"account_contracts": [
{
"valid_from_date": "2023-01-01",
"signed_at_date": "2023-01-01",
"versions": [
{
"applicable_at_date": "2023-01-01",
"terms": [
{
"term_type": "CONTRACT_METADATA",
"metadata": {
"cee_formula_type": "standard"
}
},
{
"term_type": "PRODUCT_RATE_OVERRIDE_SCHEDULE",
"schedules": [
{
"effective_from": "2023-01-01",
"items": [
{
"price_per_unit": "0.2",
"rate_band": "CONSUMPTION_STANDARD",
"product_code": "ELEC-BUSINESS"
}
]
}
]
},
{
"term_type": "TERMINATION_FEE",
"market_configs": [
{
"amount": 100.0,
"supply_type": "ELECTRICITY",
"fee_type": "FLAT"
}
]
},
{
"term_type": "ISSUANCE_FREQUENCY",
"frequency": "MONTHLY",
"multiplier": 2,
"period_start_day": 1,
"period_start_month": 1
},
{
"term_type": "GUARANTEE_OF_ORIGIN_CONFIGURATION",
"guarantee_of_origin_percentage": 100,
"is_variable": true
},
{
"term_type": "PAYS_BY_DIRECT_DEBIT",
"pays_by_direct_debit": true
},
{
"term_type": "DELAYER_DAYS",
"strategy": "FIXED",
"days": 5
},
{
"term_type": "RATE_GROUP_ELIGIBILITY",
"time_series_specification_schedules": [],
"schedules": [
{
"effective_period": {
"start_date": "2023-01-01"
},
"product_code": "ELEC-BUSINESS",
"rate_group_code": "BUSINESS_RATE_GROUP",
"is_eligible": true
}
]
},
{
"term_type": "CHARACTERISTIC_OVERRIDE",
"overrides": [
{
"characteristic_code": "size",
"override_value": "100"
}
]
}
]
}
],
"identifier": "ABC"
}
],
"customers": [
{
"title": "M.",
"given_name": "Robert",
"family_name": "Terwilliger",
"email": "robert.terwilliger@gmail.com",
"mobile": "+33809685772",
"date_of_birth": "1957-10-11"
}
],
"supply_addresses": [
{
"supply_address1": "126 Rue de l'Université",
"supply_address2": "",
"supply_address3": "",
"supply_address4": "Paris",
"supply_postcode": "75007",
"customer_at_supply_address_from_date": "2019-04-01",
"supply_points": [
{
"identifier": "46147259228742",
"supply_type": "ELECTRICITY",
"supply_start_date": "2021-07-29",
"payment_schedules": [
{
"amount": 60.0,
"day_of_month": 2,
"frequency": "MONTHLY",
"means": "DD",
"start_date": "2022-01-01"
}
],
"payment_instructions": [
{
"vendor": "GOCARDLESS",
"reference": "SUPPLIER-ELEC-1234",
"type": "DIRECT_DEBIT",
"valid_from": "2022-06-15"
}
],
"billing_frequency": 12,
"agreements": [
{
"tariff_code": "ELEC-BUSINESS",
"agreed_at": "2023-07-21T14:05:00+02:00",
"effective_from": "2023-01-01"
}
],
"consent_data": {
"ELEC_CURVES": true,
"ELEC_INDEXES": false
}
}
]
}
]
}
}Overview
Use this endpoint to process account data into an account in Kraken.
Schema
Loading...
POST https://api.frteegf-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 a warnings array when deprecation warnings are enabled. {
"warnings": []
}The warnings field is omitted when deprecation warnings are disabled. {} |
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
Domestic account
{
"payload": {
"external_account_number": "EXTERNAL-1234",
"import_supplier": "TENTACLE_ENERGY",
"billing_address1": "126 Rue de l'Université",
"billing_address2": "",
"billing_address3": "",
"billing_address4": "Paris",
"billing_postcode": "75007",
"sales_channel": "DIRECT",
"sales_subchannel": "Website",
"last_billed_to_date": "2022-08-14",
"customers": [
{
"title": "M.",
"given_name": "Robert",
"family_name": "Terwilliger",
"email": "robert.terwilliger@gmail.com",
"mobile": "+33809685772",
"landline": "",
"date_of_birth": "1957-10-11",
"deceased": "",
"customer_preferences": {
"opted_into_updates": true,
"opted_into_sms": false,
"opted_into_offers": true,
"opted_into_recommended": false
}
}
],
"supply_addresses": [
{
"supply_address1": "126 Rue de l'Université",
"supply_address2": "",
"supply_address3": "",
"supply_address4": "Paris",
"supply_postcode": "75007",
"customer_at_supply_address_from_date": "2019-04-01",
"supply_points": [
{
"identifier": "46147259228742",
"supply_type": "ELECTRICITY",
"supply_start_date": "2021-07-29",
"payment_schedules": [
{
"amount": 60.0,
"day_of_month": 2,
"frequency": "MONTHLY",
"means": "DD",
"start_date": "2022-01-01"
}
],
"payment_instructions": [
{
"vendor": "GOCARDLESS",
"reference": "SUPPLIER-ELEC-1234",
"type": "DIRECT_DEBIT",
"valid_from": "2022-06-15"
}
],
"billing_frequency": 12,
"agreements": [
{
"tariff_code": "ELEC-123",
"agreed_at": "2021-07-25T10:03:00+02:00",
"effective_from": "2021-08-01",
"effective_to": "2022-08-01",
"addons": [
{
"band": "GREEN_POWER_50"
}
]
},
{
"tariff_code": "ELEC-456",
"agreed_at": "2022-07-25T10:03:00+02:00",
"effective_from": "2022-08-01",
"effective_to": "2023-08-01",
"addons": [
{
"band": "GREEN_POWER_55"
}
]
},
{
"tariff_code": "ELEC-789",
"agreed_at": "2023-07-21T14:05:00+02:00",
"effective_from": "2023-08-01",
"addons": [
{
"band": "CARBON_OFFSET_50"
}
]
}
],
"consent_data": {
"ELEC_CURVES": true,
"ELEC_INDEXES": false
}
},
{
"identifier": "35438560738869",
"supply_type": "GAS",
"supply_start_date": "2021-07-29",
"payment_schedules": [
{
"amount": 55.0,
"day_of_month": 2,
"frequency": "MONTHLY",
"means": "DD",
"start_date": "2022-01-01"
}
],
"payment_instructions": [
{
"vendor": "GOCARDLESS",
"reference": "SUPPLIER-GAS-12345",
"type": "DIRECT_DEBIT",
"valid_from": "2022-06-15"
}
],
"billing_frequency": 12,
"agreements": [
{
"tariff_code": "GAS-123",
"agreed_at": "2021-07-25T10:03:00+02:00",
"effective_from": "2021-08-01",
"effective_to": "2022-08-01"
},
{
"tariff_code": "GAS-456",
"agreed_at": "2022-07-25T10:03:00+02:00",
"effective_from": "2022-08-01",
"effective_to": "2023-08-01"
},
{
"tariff_code": "GAS-789",
"agreed_at": "2023-07-21T14:05:00+02:00",
"effective_from": "2023-08-01"
}
],
"consent_data": {
"GAS_INDEXES": true
}
}
]
}
],
"statements": [
{
"bill_period_from_date": "2021-01-01",
"bill_period_to_date": "2022-01-01",
"statement_path": "EXTERNAL-1234/2021-01-01-to-2022-01-01-electricity.pdf",
"statement_id": "1"
}
],
"supplementary_ledgers": [
{
"ledger_code": "ENERGY_CHEQUE_LEDGER",
"energy_cheques": [
{
"number": "1232542",
"protection_from": "2023-01-01",
"protection_to": "2023-06-01",
"source": "PAPERLESS",
"asp_remittance_ref": "abcdefg-1234567",
"amount": 1234,
"valid_to": "2023-06-01",
"status": "VALID"
}
]
}
],
"notes": [
{
"created_at": "2018-10-10T10:20:00Z",
"body": "This is a note",
"document_paths": [
{
"document_path": "/notes/1234/attachment.jpg"
}
]
}
],
"account_campaigns": [
{
"slug": "super_account",
"campaign_note": "Campaign note"
}
],
"metadata": [
{
"key": "metadata_key",
"value": {
"some_data": "some_value"
}
}
]
},
"task_params": {
"is_dry_run": false
}
}Business account
{
"payload": {
"external_account_number": "EXTERNAL-1234",
"import_supplier": "TENTACLE_ENERGY",
"account_type": "BUSINESS",
"business": {
"business_type": "EURL",
"siret": "60487647400494",
"details": [
{
"key": "siren",
"value": "60487647400494"
}
]
},
"billing_address1": "126 Rue de l'Université",
"billing_address2": "",
"billing_address3": "",
"billing_address4": "Paris",
"billing_postcode": "75007",
"sales_channel": "DIRECT",
"sales_subchannel": "Website",
"last_billed_to_date": "2022-08-14",
"account_contracts": [
{
"valid_from_date": "2023-01-01",
"signed_at_date": "2023-01-01",
"versions": [
{
"applicable_at_date": "2023-01-01",
"terms": [
{
"term_type": "CONTRACT_METADATA",
"metadata": {
"cee_formula_type": "standard"
}
},
{
"term_type": "PRODUCT_RATE_OVERRIDE_SCHEDULE",
"schedules": [
{
"effective_from": "2023-01-01",
"items": [
{
"price_per_unit": "0.2",
"rate_band": "CONSUMPTION_STANDARD",
"product_code": "ELEC-BUSINESS"
}
]
}
]
},
{
"term_type": "TERMINATION_FEE",
"market_configs": [
{
"amount": 100.0,
"supply_type": "ELECTRICITY",
"fee_type": "FLAT"
}
]
},
{
"term_type": "ISSUANCE_FREQUENCY",
"frequency": "MONTHLY",
"multiplier": 2,
"period_start_day": 1,
"period_start_month": 1
},
{
"term_type": "GUARANTEE_OF_ORIGIN_CONFIGURATION",
"guarantee_of_origin_percentage": 100,
"is_variable": true
},
{
"term_type": "PAYS_BY_DIRECT_DEBIT",
"pays_by_direct_debit": true
},
{
"term_type": "DELAYER_DAYS",
"strategy": "FIXED",
"days": 5
},
{
"term_type": "RATE_GROUP_ELIGIBILITY",
"time_series_specification_schedules": [],
"schedules": [
{
"effective_period": {
"start_date": "2023-01-01"
},
"product_code": "ELEC-BUSINESS",
"rate_group_code": "BUSINESS_RATE_GROUP",
"is_eligible": true
}
]
},
{
"term_type": "CHARACTERISTIC_OVERRIDE",
"overrides": [
{
"characteristic_code": "size",
"override_value": "100"
}
]
}
]
}
],
"identifier": "ABC"
}
],
"customers": [
{
"title": "M.",
"given_name": "Robert",
"family_name": "Terwilliger",
"email": "robert.terwilliger@gmail.com",
"mobile": "+33809685772",
"date_of_birth": "1957-10-11"
}
],
"supply_addresses": [
{
"supply_address1": "126 Rue de l'Université",
"supply_address2": "",
"supply_address3": "",
"supply_address4": "Paris",
"supply_postcode": "75007",
"customer_at_supply_address_from_date": "2019-04-01",
"supply_points": [
{
"identifier": "46147259228742",
"supply_type": "ELECTRICITY",
"supply_start_date": "2021-07-29",
"payment_schedules": [
{
"amount": 60.0,
"day_of_month": 2,
"frequency": "MONTHLY",
"means": "DD",
"start_date": "2022-01-01"
}
],
"payment_instructions": [
{
"vendor": "GOCARDLESS",
"reference": "SUPPLIER-ELEC-1234",
"type": "DIRECT_DEBIT",
"valid_from": "2022-06-15"
}
],
"billing_frequency": 12,
"agreements": [
{
"tariff_code": "ELEC-BUSINESS",
"agreed_at": "2023-07-21T14:05:00+02:00",
"effective_from": "2023-01-01"
}
],
"consent_data": {
"ELEC_CURVES": true,
"ELEC_INDEXES": false
}
}
]
}
]
},
"task_params": {
"is_dry_run": false
}
}Overview
Use this endpoint to retrieve the current status of an account import.
GET https://api.frteegf-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": "IN_PROGRESS | PROCESSED | DRY_RUN_SUCCEEDED | PENDING | CANCELLED",
"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"
} |