The Kraken data-import REST APIs are authenticated using a token obtained using the ObtainKrakenToken GraphQL Mutation . This can be authenticated with the Organisation API key provided to you by the Kraken Tech team. When you have your token, you can set the Authorization header in the client you are using to make the request. The header should be set to the value of your token. For example, if your token is 12345, you would set the Authorization header to 12345:

Some fields in the payload are optional, as specified in the field definitions tables.

• If a field is optional and you do not wish to provide data for it, then it should be omitted from the payload entirely.

• If an optional object or array field is provided, the fields within the object/array must be provided if they are required.

• If an optional field is provided, it must adhere to its relevant validation rules, and the validation rules of any sub-objects in the case of nested fields.

Certain endpoints accept dates or datetimes as fields in the payload. These should adhere to the ISO 8601 format.

For example:

Some endpoints allow for the inclusion of document paths as fields in the payload. These paths are used to reference documents stored in Amazon S3 (Kraken's storage backend). Paths in the payload should be provided relative to the path specified in the data-import configuration. The data-import config is set on a per import supplier basis. See section on import suppliers for more information.

Each instance of Kraken is set up with an S3 bucket for storing production files. For the sake of this example, let's say your production files are stored in a bucket called tentacle-production-files. If the import config specifies a root location of sftp/migratedfiles and the payload points to a path like:

then the document would be expected to be located at

This method of specifying document paths allows for flexibility in splitting up documents into different "folders" in S3. For example, you could have a path each for note documents and PDF statements, each split by date.

Many of the APIs detailed in this guide perform detailed validation on the payloads they receive. If a payload fails validation, the API will return a 400 Bad Request response detailing what went wrong. Here's an example response:

Each item in the errors array corresponds to an error object with the same three keys:

• detail is a human-readable description of the error. The exact wording may change over time, so please don't parse it or build any logic around it.
• code is a machine-readable identifier for the error type. It will not change over time, so feel free to use in data analytics or other logic.
• attr is a dot-delimited path that specifies which part of the input data caused the error. String components of the path refer to the names of fields within an object, while numeric components refer to the index of an item within an array, with 0 representing the first item in the array.

This API will evolve over time. Future updates to the API may include new endpoints or additions to existing endpoints. In order to preserve backward compatibility, the behaviour and return values of existing endpoints will not change without notice. The exception to this is fields that are currently undocumented, which may be given specific meaning in the future. Care should be taken when constructing payloads and requests to ensure that only documented fields are included.

The import supplier is used to group migrated accounts, allowing for the configuration of specific behaviours during account migration, such as sending automated customer emails upon migration. We will set up an initial import supplier for you and together determine your desired configuration.

Additional import suppliers for specific customer cohorts may also be created, addressing unique needs like migrating long-standing debt customers without initial communications. If you think you might need another import supplier, have a chat with us and we’ll assess whether it's the best solution.