BT Collections XML export reference

Introduction

This is the complete reference of the BT Collections XML export. The XML export is part of the synchronization between your accounting application and BT Collections. The synchronization is done in 3 stages:

  1. Exporting all debtors and active documents/recently archived documents (and if necessary the contacts and representatives) to an XML file (1 for each entity/company). The structure of these files is described here and should be validated by schema.icontroller.eu
  2. Sending the XML file(s) to BT Collections. More information can be found on datalink.icontroller.eu
  3. Sending a notification to BT Collections to indicate that the export is finished and that BT Collections can start importing the data. More information can be found on datalink.icontroller.eu

Please be aware that this is the complete reference of an XML export but in most cases you'll only use a (small) subset of the available functionality. Make sure to always carefully read which fields are required to export and which aren't. Check this BT Collections example export.

XML validation

Before sending your export file to BT Collections you should make sure your export has a valid structure. You can validate your export file on schema.icontroller.eu. If your export file is not valid, this site will give you a list of errors in your export. The validation is based on an XSD schema that you can download.

Basic structure

The basic structure of the export XML is: 

<?xml version="1.0" encoding="UTF-8"?>
<icontroller>
  <debtors>
    <debtor>...</debtor>
    <debtor>...</debtor>
    <debtor>...</debtor>
  </debtors>
  <documents>
    <document>...</document>
    <document>...</document>
    <document>...</document>
  </documents>
</icontroller>

The root XML tag is “<icontroller>”. This tag can have 8 types of children:

  1. representatives (optional)
  2. debtors (required)
  3. representative_debtor_links (optional)
  4. representative_document_links (optional)
  5. contacts (optional)
  6. documents (required)
  7. attachments (optional)
  8. notes (optional)

The XML file is required to be encoded in UTF-8.

Different types used in export

Name Description
Date The date format should be in yyyy-mm-dd. The month and day should always consist out of 2 digits e.g.: 2013-03-23
Numeric boolean Should be either a 0 (meaning “no” or “false”) or 1 (meaning “yes” or “true”)
Email A valid email address e.g.: name@company.com
Phone number Telephone number including country code
Denomination Should be a numeric value without thousand separator, a dot (“.”) as decimal separator and it should always have 2 or 3 digits after dot, e.g.: 12.00 or 45.890 or 123456.47

Exporting representatives

Example: 

<representative>
  <reference>r-2</reference>
  <name>Mike</name>
  <language>DE</language>
  <tel>+32(0)9 337 82 79</tel>
  <mobile_phone>+32(0)4 12 34 56 78</mobile_phone>
  <email>support@icontroller.eu</email>
</representative>
Tag Type Required Description
reference Non empty string Yes The representative reference must be unique for all representatives in the XML file
name Non empty string No
language Uppercase version of ISO 639-1. E.g. DE for German Yes
tel Phone number No Telephone number of the representative
mobile_phone Phone number No
supervisor_representative_reference Non empty string No The reference of the supervisor. The supervisor should also be a representative and should be in the same XML file
fax Phone number No
email Email No Email address of the representative
extra_info String No Additional information about the representative
Additional custom fields

Exporting debtors

Example: 

<debtor>
  <reference>debtor-1</reference>
  <language>NL</language>
  <name>Lizzy</name>
  <tel>09/789 45 23</tel>
  <mobile_phone>09/233 47 19</mobile_phone>
  <fax>09/789 45 24</fax>
  <currency>EUR</currency>
  <address_lines>Hoogpoort Bus 2</address_lines>
  <address_city>Ghent</address_city>
  <address_zip>9000</address_zip>
  <address_country>BE</address_country>
  <fields>
    <string reference="last_dispute_reason">unspecified</string>
    <integer reference="age">5</integer>
  </fields>
</debtor>
Tag Type Required Description
reference Non empty string Yes Debtor reference must be unique for all debtors in the XML file
name Non empty string Yes
address_country ISO 3166-1 Yes Country code of the debtor
language Uppercase version of ISO 639-1. E.g. NL for Dutch Yes Language of the debtor
currency ISO 4217 Yes Primary currency of the debtor, all debtor totals will be displayed in this currency
vat String No e.g. BE0123456789
address_lines String No Multiple address lines, separated by newlines
address_zip String No
address_city String No
address_state String No State in which the debtor is located
tel Phone number No Telephone number debtor
mobile_phone Phone number No
fax Phone number No
email Email No Email address of debtor. This email address wil be used to sent reminders
billing_email Email No Email address of debtor. This email address wil be used to sent invoices
preferred_document_send_method String No Can be either “email” or “postal_mail”. When sending invoices to debtors with e-invoicing module you can choose to send them by email (if a valid email is provided) or by postal mail
credit_limit Denomination No Credit limit of debtor
credit_limit_currency ISO 4217 No Credit limit currency of debtor
debtorgroup String No Name or code of the group this debtor belongs to. When a debtor belongs to a group, information of all other debtors in this group will be displayed alongside this debtors' information
description String No Description of the debtor
payment_center String No All debtors with the same value in the payment_center tag will be grouped in the same payment center. If you have multiple xml files (usually one for each legal entity) the debtors in other xml files with the same value in the payment_center tag will all be grouped in one big payment center. So payment centers are on a level above legal entities.
BE AWARE: make sure you alway have exactly one main contact for a each payment center. You can annotate a debtor as the main contact with the is_payment_center_contact tag.
is_payment_center_contact Numeric boolean No See payment_center tag for more info
company_registration_number String No If the debtor is a company this field contains the official registration number of this company for this debtor's country.
ggs_id String No If Credit Safe is used, GGS ID for this debtor.
duns_number String No If D&B is used, Duns number for this debtor.
graydon_enterprise_id String No If Graydon is used, Graydon enterprise ID for this debtor.
tbi_id String No If TBI is used, TBI ID for this debtor.
coface_easynumber String No If Coface is used, Coface easynumber for this debtor.
experian_bin String No If Experian is used, Experian BIN for this debtor.
Additional custom fields


Exporting links between debtors and representatives

Example: 

<representative_debtor_link>
  <debtor_reference>debtor-8</debtor_reference>
  <representative_reference>r-2</representative_reference>
</representative_debtor_link>
Tag Type Required Description
debtor_reference Non empty string Yes Reference to a debtor present in the same XML file
representative_reference Non empty string Yes Reference to a representative present in the same XML file

Exporting links between documents and representatives

Example: 

<representative_document_link>
  <document_reference>document-5</document_reference>
  <representative_reference>r-2</representative_reference>
</representative_document_link>
Tag Type Required Description
document_reference Non empty string Yes Reference to a document present in the same XML file
representative_reference Non empty string Yes Reference to a representative present in the same XML file

Exporting contacts

Example: 

<contact>
  <reference>contact-2</reference>
  <debtor_reference>debtor-1</debtor_reference>
  <name>Peter</name>
  <function>CEO</function>
  <tel>09/233 12 45</tel>
  <mobile_phone>09/238 47 19</mobile_phone>
  <email>support@icontroller.eu</email>
  <is_standard_recipient>1</is_standard_recipient>
</contact>
Tag Type Required Additional description
reference Non empty string Yes Contact reference must be unique for all contacts in the XML file
debtor_reference Non empty string Yes Reference to a debtor present in the same XML file
name String No The name of the contact. If you use this tag, you cannot use the “first_name” and “last_name” tag
first_name String No The first name of the contact. If you use this tag, you cannot use the “name” tag
last_name String No The last name of the contact. If you use this tag, you cannot use the “name” tag
function String No The function of the contact in the company (eg: accountant)
description String No Description of the contact
tel Phone number No Telephone number of the contact
mobile_phone Phone number No
fax Phone number No
email String No Email address of the contact
address String No Address of the contact. Should contain street and house number
city String No
zip_code String No
countrycode ISO 3166-1 No
state String No State in which the contact is located
language Uppercase version of ISO 639-1. E.g. FR for French No
is_standard_recipient Numeric boolean No When reminders are sent to the debtor linked to this contact or telephone calls are made, the telephone address and email address of this contact is used.

Exporting documents

The following types of documents should be exported:

Only the active documents should be exported (invoices not yet paid, payments for invoices not yet paid). To ensure the correct pay date is known to BT Collections you can also send the documents that were paid in the last 7 days but they should be marked with "<is_archive>1</is_archived>".

There are 2 ways to export denominations. One is simply to supply a denomination and currency tag, as shown in Example 1. The other is to supply following tags: denomination_in_original_currency, denomination_in_base_currency, original_currency and base_currency (Example 2). Under base currency we understand the currency your company operates in, in our case that would be EUR. Original currency is the actual currency of the document itself.

WARNING: do NOT use both methods. Pick one and stick to it.

Example 1: single currency accounting, without custom fields (invoice) 

<document>
  <reference>inv-1</reference>
  <document_number>INV00000002</document_number>
  <debtor_reference>debtor-2</debtor_reference>
  <original_denomination>1000.00</original_denomination>
  <denomination>200.00</denomination>
  <currency>EUR</currency>
  <date>2019-12-25</date>
  <due_date>2020-01-24</due_date>
  <document_type>2</document_type>
  <payment_reference>062200080643</payment_reference>
  <is_archived>0</is_archived>
</document>

Example 2: multiple currency accounting, without custom fields (credit note) 

<document>
  <reference>crd-1</reference>
  <document_number>CRD00000003</document_number>
  <debtor_reference>debtor-2</debtor_reference>
  <original_denomination_in_base_currency>-1123.74</original_denomination_in_base_currency>
  <original_denomination_in_original_currency>-1000.00</original_denomination_in_original_currency>
  <denomination_in_base_currency>-1123.74</denomination_in_base_currency>
  <denomination_in_original_currency>-1000.00</denomination_in_original_currency>
  <base_currency>EUR</base_currency>
  <original_currency>GBP</original_currency>
  <date>2019-12-28</date>
  <due_date>2019-12-28</due_date>
  <document_type>3</document_type>
  <payment_reference>062200080644</payment_reference>
  <is_archived>0</is_archived>
</document>

Example 3: Unallocated payment 

<document>
  <reference>pymnt-1</reference>
  <document_number>ING00000005</document_number>
  <debtor_reference>debtor-2</debtor_reference>
  <original_denomination_in_base_currency>-150.00</original_denomination_in_base_currency>
  <original_denomination_in_original_currency>-150.00</original_denomination_in_original_currency>
  <denomination_in_base_currency>-150.00</denomination_in_base_currency>
  <denomination_in_original_currency>-150.00</denomination_in_original_currency>
  <base_currency>EUR</base_currency>
  <original_currency>EUR</original_currency>
  <date>2020-01-04</date>
  <due_date>2020-01-04</due_date>
  <document_type>1</document_type>
  <payment_reference>062200080646</payment_reference>
  <is_archived>0</is_archived>
</document>
Tag Type Required Description
reference Non empty string Yes The document reference should be unique for all documents in the XML file. This will also be used as document number unless you use the “document_number” tag. The document reference should be consistent for each export, a given reference should always point to the same document. If no unique database field is available to fill this reference, a combination of multiple fields (concatted, hashed) is advised. Do not use an on-the-fly generated number that can change with every export.
document_number Non empty string No The document number as it will appear in BT Collections. If you omit this value the “reference” tag will be used as document number.
debtor_reference Non empty string Yes Reference to a debtor present in the same XML file
denomination Denomination Yes (*) Total of document (gross). This value must be negative for credit notes or incoming payments and positive for invoices and outgoing payments. It must be non-zero. The sum of this denomination and the denomination of all payments linked to it (with payment_for_document_reference) should equal the outstanding amount (the amount the debtor has yet to pay for this document).
original_denomination Denomination Yes (*) Total of document at creation date (gross). This value must be negative for credit notes or incoming payments and positive for invoices and outgoing payments. It must be non-zero. This the total amount the document started out with and should not change when payments to it are made.
currency ISO 4217 Yes (*)
original_denomination_in_original_currency Denomination Yes (**) Can be used instead of the “original_denomination” tag. If you use this tag you'll also want to use the “original_denomination_in_base_currency” tag and the “original_currency” tag and you must drop the “original_denomination” tag. This tag should have as value the original amount (gross) of the document in the original currency of the document. It must be non-zero and this value should not change if the document is partially paid.
original_denomination_in_base_currency Denomination Yes (**) Can be used instead of the “original_denomination” tag. If you use this tag you'll also want to use the “original_denomination_in_original_currency” tag and the “base_currency” tag and you must drop the “original_denomination” tag. This tag should have as value the original amount (gross) of the document in the currency of the accounting software's currency. It must be non-zero and this value should not change if the document is partially paid.
denomination_in_original_currency Denomination Yes (**) Can be used instead of the “denomination” tag. If you use this tag you'll also want to use the “denomination_in_base_currency” tag and the “original_currency” tag and you must drop the “denomination” tag. This tag should have as value the remaining amount (gross) of the document in the original currency of the document. It must be non-zero and if payment_for_document_reference is used then this value should not change if the document is partially paid.
denomination_in_base_currency Denomination Yes (**) Can be used instead of the “denomination” tag. If you use this tag you'll also want to use the “denomination_in_original_currency” tag and the “base_currency” tag and you must drop the “denomination” tag. This tag should have as value the remaining amount (gross) of the document in the currency of the accounting software's currency. It must be non-zero and if payment_for_document_reference is used then this value should not change if the document is partially paid.
original_currency ISO 4217 Yes (**) Original currency of the document.
base_currency ISO 4217 Yes (**) Currency of the accounting software.
date Date Yes Issue date of the document
due_date Date Yes For payments or credit notes the due date should equal the issue date
journal Non empty string No Journal of the document
document_type 1 or 2 or 3 Yes 2 = invoice, 3 = credit note, 1 = other financial documents (e.g. payments, cheques, ...)
description String No External description: could be visible on the reminder
comment String No Internal description: will be visible for the user of BT Collections
is_archived Numeric boolean No When exporting not only the active documents, but also the archive, use this tag to flag non-active documents.
paid_at_date Date No Use this only for documents that are already paid. If the document is not paid yet, don't include this tag.
grouping Non empty string No All documents of a debtor with the same grouping will be visually grouped on the debtor sheet.
payment_for_document_reference Non empty string No This tag should only be included for payments. It refers to the reference of the invoice that has been paid with this payment. The payment_for_document_reference tag must always refer to an existing document of the same debtor present in the XML file.
external_hyperlink Non empty string No External hyperlink to the document: will be visible on the reminder
payment_reference Non empty string No The payment reference of the invoice to easily match payments to this invoice
Additional custom fields

* Only if the first method of exporting denominations is used
** Only if the second method of exporting denominations is used

Exporting attachments

If you are using e-invoicing or you want to view a PDF of an invoice or credit note you can send them using the “attachment” tags. There are 3 types of attachments:

If you are using e-invoicing you are required to send main attachments for each invoice/credit note. In the XML you only send the link to the attachment, the actual attachment should be send to BT Collections using the datalink.

Example: 

<attachments>
  <attachment>
    <reference>att-1</reference>
    <document_reference>inv-2</document_reference>
    <filename>main-attachment.pdf</filename>
    <type>main</type>
  </attachment>
</attachments>
Tag Type Required Description
reference Non empty string Yes The attachment reference should be unique for all attachments in the XML file. This is only used for export purposes and will never be visible in BT Collections
document_reference Non empty string Yes Refers to the reference of the document of this attachment.
filename Non empty string Yes The filename of the the attachment you have sent to BT Collections using the datalink
type String: “main” or “external” or “internal” Yes main attachments: This should be the actual PDF of your invoice/credit note. External attachments: Any attachment (can also be PDF files) that will be visible for you customer. Internal attachments: Any attachment (can also be PDF files) that will only be visible for the internal staff of your company.

Exporting notes

If your accounting software has additional notes, logs, ... associated with debtors you can add them to the export so they are available for users in BT Collections 

<note>
  <reference>note-9</reference>
  <debtor_reference>debtor-1</debtor_reference>
  <date>2018-02-15</date>
  <content>Lorem ipsum dolor sit amet</content>
</note>
Tag Type Required Additional description
reference Non empty string Yes Note reference must be unique for all notes in the XML file
debtor_reference Non empty string Yes Reference to a debtor present in the same XML file
date Any date-time value Yes Use YYYY-MM-DD hh:mm:ss format, e.g. 2018-09-02 15:59:23
content String Yes The note visible for the user

Custom fields

The following tags can have custom fields:

These fields can be used to add non-standard data to these tags, e.g.: 

<document>
  <reference>inv-1</reference>
  <document_number>INV00000002</document_number>
  <debtor_reference>debtor-2</debtor_reference>
  <original_denomination>1000.00</original_denomination>
  <denomination>200.00</denomination>
  <currency>EUR</currency>
  <date>2019-12-25</date>
  <due_date>2020-01-24</due_date>
  <document_type>2</document_type>
  <is_archived>0</is_archived>
  <fields>
    <string reference="can_be_any_name">can be any string value</string>
    <integer reference="can_be_any_other_name">123</integer>
    <boolean reference="can_be_any_unique_name">0</boolean>
    <double reference="can_be_any_reference">0.00</double>
    <date reference="can_be_any_date_name">2022-01-01</date>
  </fields>
</document>

These fields can have the following types:

Name Description
string Any string value
integer Any integer (positive or negative) without thousand separator, e.g.: -895
boolean Any boolean (must have value 0 or 1)
double Any double value. No thousand separator and a dot as decimal separator. E.g.: 52.2357
date Any date value. Use YYYY-MM-DD format. E.g.: 2017-08-29
date_time Any date & time value. Use YYYY-MM-DD hh:mm:ss format. E.g.: 2017-08-29 15:36:48

Custom fields are not deleted when they are not sent in the xml. If you want to unset a custom field, you should send it again without a value. E.g.: 

  ...
  <fields>
    <string reference="can_be_any_name" />
    <integer reference="can_be_any_other_name"></integer>
  </fields>
  ...