Data import

The data import defines the flow of data from your side into the collectAI system. Our standard integration requires the following definitions to be fulfilled.

note

If the standard import format and fields are difficult for you to provide, a custom import could be developed. Please reach out to our onboarding team to define a customized process with you.

caution

Once the file exchange has been fully agreed up on, it is important that the format, fields, file names etc. do not change anymore. Adjustments can be made in cooperation with our onboarding Team in order to avoid breaking the integration.

File formats

By default, we do support the following file formats:

• Excel (.xls, .xlsx)
• Comma-separated Values (.csv)
• Text (.txt)
• Extensible Markup Language (.xml)
• JavaScript Object Notation (.json)

File naming rules

File Names have to follow the following rules:

• Name contains date and description, example: 20200122_Import.xls
• Date and description are separated by underscore
• File name contains only 0-9a-zA-Z._- and no other characters
• File name contains no spaces

When using a single file to provide the initial import and the following updates, the file name can stay the same, however if the update comes in different file (format, specification) from the initial import, then the file names have to reflect this change, example:

• 20200122_Import.xls
• 20200125_Update.xls

Field definitions (Category A)

There are several categories of data information that collectAI requires in order to perform the reminder processes. Some of these categories are very important for the process to work, grouped under Category A.

Customer data information

Defines customer related information like the customer number, gender, birthday etc.

Field	Mandatory	Format	Field Values	Description
referenceNumber	Yes	string	AB1234567	Unique key in the collectAI system. One reference number is a record (claim) in the collectAI system. This can be a invoice number, a contract number etc.
firstName	Yes	string	Max	First name of the end customer (if a person) or the company name
lastName	Yes	String	Mustermann	Last name of the end customer (if a person) or the company name.
customerNumber	No	string	KD-5454	The customer number of the end customer.
title	No	string	Dr.	The academic title of the end customer.
gender	No	string	male/female	The gender of the end customer. This field helps to have proper salutations in place. If the end customer is a company, it can be left empty.
birthday	No	date	YYYY-MM-DD	The date of birth of the end customer.
language	No	String ISO 639-1	de-DE	Language in which the end customer has to be addressed. Needs to be filled if the communication strategy includes multiple languages.

Communication channel information

Defines customer contact details to send payment reminders to.

Field	Mandatory	Format	Field Values	Description
email	No	string	support@collect.ai	The email address of the end customer. This field needs to be filled if the communication strategy consists of email
mobileNumber	No	string (‘+’,country code)	+491731234567	The mobile number of the end customer. This field needs to be filled if the communication strategy consists of SMS.
addressStreet	No	string	Am Sandtorkai 50	The street of the end customer. This field needs to be filled if the communication strategy contains letters.
addressZip	No	string	20457	The zip code of the end customer. This field needs to be filled if the communication strategy contains letters.
addressCity	No	string	Hamburg	The city of the end customer. This field needs to be filled if the communication strategy contains letters.
addressCountryCode	No	string	DE	The country of the end customer provided in ISO 3166-1 alpha-2 format. This field needs to be filled if the communication strategy contains letters.
addressCountry	No	string	Deutschland	Deprecated. The country of the end customer provided as free text. Only use when unable to provide addressCountryCode - in that case there will be an attempt to guess it from the addressCountry on the best effort basis during claim creation. Ambiguous country information may cause disruptions with payment and communication providers.

Open payment information

Defines information about the open payments aggregated as a balance or as an open item list (depending on the use case), such as due dates.

Field	Mandatory	Format	Field Values	Description
dueDate	Yes	date	YYYY-MM-DD	The due date of the open payment. This field can define the start of the reminder process. Can be visible to the end customer, depending on your setup.
itemReference	Yes	string	your-item-id	The reference of the specific item that compose a claim. Not visible to the end customer.
position	No	string	01	The position of the specific item, needed if the item number is not unique. Not visible to the end customer.
itemDescription	No	string	Monthly Rate Electricity/Gas Invoice	The description of the specific item. This field can be customised depending on the industry in order for the end customer to get the correct description of the open payment. Visible to the end customer.
itemDate	Yes	date	YYYY-MM-DD	The date where the specific item (invoice, rate etc.) was issued. Can be visible to the end customer, depending on your setup.
value	Yes	Number	123,45	The value of the item.
currency	No	ISO 4217	EUR	The currency of the item. Needed if open payments are in different currencies.

Lifecycle information

Defines claim lifecycle information like payments, partial payments, pausing and archiving, more details can be found in the claim management section.

Field	Mandatory	Format	Field Values	Description
Payments/Partial Payments	Yes	Number	123,45	This information can be provided by updating the value field. If full payment, the item can disappear from the list or explicitly (for example by column paid, or any other flags). If partial payment, the item gets a new value.
Pause	No	string	deferment	A field needed if collectAI needs to pause the escalation till further information.
Archive	No	string	inactive	A field needed if collectAI needs to fully archive a running claim.

Field definitions (Category B)

The secondary fields define enhanced communication and process customization use cases. Please see the following sessions for detailed description of all the fields belonging to specific categories.

Scenario allocation information

In case the setup is defined to have multiple scenarios, then information fields/attributes are needed to make this allocation correctly

Field	Mandatory	Format	Field Values	Description
Scenario	No	string	scenarioName	In case there are multiple scenarios in use, this field can be used to define the scenario that this specific claim should be allocated to.

Additional information for customization/AI

For further customization in the communication process, additional fields can be used.

Field	Mandatory	Format	Field Values	Description
additionalField	No	string		This extra field can be used for any other information that can be used for enriching the complete process of solving the open payments/ or for AI related information.

Example

The file example containing most of the fields described above can be downloaded here.