Import and Result Data formats

Owned by Remco Raaijmakers
Last updated: Jun 13, 2024
19 min read

 

New documentation can be found at Integration Guide | Developer Resources - Alphacomm

Index



Intro

This document is written for project managers, technicians and responsible security officers at the involved departments of our client and/or the parties that are connected. This document contains 2 subjects:

  • Data structure XML, CSV, ODS and XLSX
    Meant for the stakeholders that deliver the data, ie. the selection of data, the collection of data both on query basis or manual delivery.

  • Data transport
    The secure transport of customer data to and from Alphacomm

Intention

The goal of this document is to clarify how Alphacomm’s Collectmaxx platform works, to determine a standard concerning the delivery of data and the importance of transport security of data and to bring your attention to other technical security affairs.

How does Collectmaxx work?

Collectmaxx is a reminder service that can remind people of upcoming events, payments or share important information through phone, text messages (SMS), e-mail or other channels. Go to alphacomm.io/collectmaxx for a demonstration of the possibilities.

With the data format that is described in this document, all services can be directed.



Contact or support

Do you have a question or problem? Please log on to our service desk to create a ticket.

Data structure

To process data correctly it is important that this data is delivered in a reliable way. The content of the data has to be structured correctly to make sure it can be automatically processed. The cleaner (better) the input data is, the better the result of our services.

It is recommended to automate the selection of data - the process that determines which data is send to Alphacomm. This decreases the chance of human errors and makes the dependency of humans to make the export smaller.

All records that are delivered at Alphacomm will be processed automatically with the agreed settings in Alphacomm Live. Don't deliver records that should not be processed.

Input file format

There are five possible file formats to deliver data: CSV, XLSX, XLS, ODS and XML. The information in this document applies all formats. The conversion of this information to the required file format is shown in a required fields matrix. This field matrix is located at the end of this document.

Example files are custom made for you. You will receive a complete custom CSV example from Alphacomm with all the necessary fields and specifications.

Technical specifications XML

  • The file must be encoded in UTF-8.

  • The root-element is <annabel>, every record has to be surrounded by <record>.

  • Every category has to be surrounded by a new element. The fields of these categories are sub-elements. For an example of the element names of the different categories see the table below.

Technical specifications csv-file

  • The file must be encoded in UTF-8.

  • The field are divided by an delimiter. This delimiter has to be an semicolon (;).

Example: “person_familyname”;”contact_phonenumber_1”

  • All fields must be enclosed by an qualifier. This qualifier must be a double quote (“).

Example: “value"

  • Records have to be divided by a newline, according to the UNIX notation, or ASCII code 0x0A, or represented in most program languages by “\n”.

  • Field names have to be exactly the same as described n the documentation below**.

  • Fields cannot have unnecessary tabs and/or spaces. This can be solved with the so called trim() function.

  • Fields cannot be longer than the maximum described value.

  • A phone number can have a + or – sign, spaces are also allowed. It cannot have other alphanumeric signs.

  • Phone numbers must be delivered with a country code.

Technical specifications ODS or XLSX file

  • The first row should contain the field names and have to be exactly the same as described in the documentation below**.

  • Fields cannot be longer than the maximum described value.

  • A phone number can have a + or – sign, spaces are also allowed. It cannot have other alphanumeric signs.

  • Phone numbers must be delivered with a country code.

 

** When creating a file with the required field names is not possible in your situation, we can setup a custom field name mapping. This will be a one-time setup.

File names

Import

The names of the files that are sent to Alphacomm must be unique, even when the content is identical. The prefered format is described below:

20200519-XXXX-1.csv

date (YYYYMMDD) + client number +”-” + number + “.csv”

Results

You can find our result files in our Portal or get them from our SFTP. The result files are created at night for the previous day. So at 6 AM, the results are available from the previous day.

Result files will have the following filename format:

result_20200519-XXXX.csv
Examples:

Daily result files:

result_20220106-acos1001.csv

Monthly result files:

result_20211201_20211231-acos1001.csv

"result_" + date(YYYYMMDD) + “-acos“+ script number + “.csv”

 

 

 



Field specification delivery file

For every message sent by Alphacomm, a separate record must be delivered. Every record contains the necessary information from the specified fields below.

Every category can be delivered once or more times per record. This is mentioned in the header of every category. When an entity can be delivered more than once in a category it is required to number the entities by a '_X' suffix.

Example:

CONTACT_PHONENUMBER_1, CONTACT_PHONENUMBER_2

Identification (IDENTIFICATION)

The IDENTIFIER field is used to make sure that every record can be identified as unique. When there are 2 records containing the same IDENTIFIER the system will treat it as one (only the last one will be used). Therefore it is important that this identifier is unique, not only in a single file but in all your delivery history.

Field

Description

Format (Max.)

IDENTIFIER

A unique string that identifies the record. This is the identifier in our result file.
In our API this field is called “reference“.

(VARCHAR) 255

 

This identifier has to be unique overall history of sending. To ensure this it can be composed of a file number or customer number in combination with the present date.

Person (PERSON)

Describes the customer.

Field

Description

Format (Max.)

FAMILYNAME

Last name. Also contains inserts.

(VARCHAR) 100

GIVENNAME

First name(s)

(VARCHAR) 100

GENDER

Gender. Valid values are: M/F/U

M = Male, F = Female, U = Unknown

(VARCHAR) 1

BIRTHDAY

Birthday

Example: 1975-01-01

(DATE) yyyy-mm-dd

IDENTIFIER

Client number / debtor number / patient number / etc.

(VARCHAR) 100

HONORIFICPREFIX

Title of customer (prefix)

Example: Drs. Ing.

(VARCHAR) 100

HONORIFICSUFFIX

Title of customer (suffix)

Example: MSc.

(VARCHAR) 100

 

 



Address (ADDRESS)

Describes an address.

Field

Description

Format (Max.)

STREET

Street name

(VARCHAR) 100

HOUSENUMBER

House number (an extension can be added when it cannot be split to EXTENSION)

(VARCHAR) 50

EXTENSION

House number extension

(VARCHAR) 50

ZIPCODE

Zip code

(VARCHAR) 15

CITY

City

(VARCHAR) 100

COUNTRY

2-digit ISO3611 land code

Example: NL

(VARCHAR) 2

 

Contact (CONTACT)

Contains all contact information from 1 person. It is possible to add multiple phone numbers for a record. The maximum is 3. To add multiple phone numbers simply add a number to the column name, for example:

CONTACT_PHONENUMBER_1;CONTACT_PHONENUMBER_2;CONTACT_PHONENUMBER_3

Field

Description

Format (Max.)

PHONENUMBER_x

Phone number in E.164 international format.

Example: 31107989525

(VARCHAR) 20

EMAIL_x

Email address

(VARCHAR) 100

 

 

 

Invoice information (INVOICE)

All information that concerns a specific payment.

Field

Description

Format (Max.)

NUMBER

Invoice number, can also be a dossier number

(VARCHAR) 100

DATE

Invoice date

Example: 2021-01-01

(DATE) yyyy-mm-dd

DUEDATE

Last payment date (should always be a date in the future)
This wil be the last day a PayLink could be paid.

Example: 2021-01-01

(DATE) yyyy-mm-dd

CURRENCY

3-digit ISO 4217 code of the currency.

Example: EUR

(VARCHAR) 3

AMOUNT

Total amount of the invoice (in cents)

Example: 10000 (= €100,00)

(INT)

TAX

Total amount of the VAT (in cents).

(INT)

DESCRIPTION

Description of the invoice

(VARCHAR) 255

REFERENCE

Reference of the invoice


When using iDEAL
[a-zA-Z0-9]{1,35}

SERIAL

Serial number of the invoice (first invoice, first reminder, etc.)

Example: 1

(INT)

 

Payment arrangement (INVOICE_ARRANGEMENT)

All fields that concern a payment arrangement of a specific invoice.

Field

Description

Format (Max.)

DESCRIPTION

Description of the payment

(VARCHAR) 255

TOTALTERMS

Total amount of terms of the arrangement

INT

TERM

Current term of the arrangement

INT

STARTDATE

Start date of payment arrangement

Example: 2021-01-01

(DATE) yyyy-mm-dd

DUEDATE

Last payment date (always use future date)

Example: 2021-01-01

(DATE) yyyy-mm-dd

CURRENCY

3-digit ISO 4217 code of the currency

Example: EUR

(VARCHAR) 3

AMOUNT

Amount of the arrangement (in cents).

Example: 10000 (= €100,00)

(INT)

REMAINING

Total amount that remains of the arrangement.

(INT)

Invoice lines (maximum 3) (INVOICELINES)

Describes the individual lines of an invoice. Use the '_X' suffix for multiple lines, for example:

INVOICELINES_1_DESCRIPTION

Field

Description

Format (Max.)

DESCRIPTION

Description of the invoice line

(VARCHAR) 255

UNITS

Amount of units of this product or service

(INT)

UNITPRICE

Price per unit (in cents).

Example: 10000 (= €100,00)

(INT)

TOTAL

Total amount for this line (in cents).

Example: 10000 (= €100,00)

(INT)

TAX

VAT for this line (in cents).

Example: 10000 (= €100,00)

(INT)

 

Emandate information (EMANDATE)

The fields are used to generate an Emandate.

Field

Description

Format (Max.)

IDENTIFIER

The number of the Emandate

(VARCHAR) 35

PURCHASEID

The number of the transaction

(VARCHAR) 35

REASON

The reason of the transaction

(VARCHAR) 70

DEBTORID

The Debtor identification number

VARCHAR) 35

VISIBLEUNTIL

The date when the request expires.

(DATE) yyyy-mm-dd

Contract information (CONTRACT)

These fields describe the value of products or contracts.

Field

Description

Format (Max.)

IDENTIFIER

The number of the contract or product

(VARCHAR) 25

TYPE

The category of the contract or product

Example: damage insurance

(VARCHAR) 100

NAME

The name of the contract or product

(VARCHAR) 100

STARTDATE

The start date of the contract or product

(DATE) yyyy-mm-dd

ENDDATE

The end date of the contract or product

(DATE) yyyy-mm-dd

Contractor information (CONTRACT_CONTACT)

These fields are used to present the contact information of the company for a specific contract or product.

Field

Description

Format (Max.)

FAMILYNAME

The last name of the contact person

(VARCHAR) 100

GIVENNAME

The first name of the contact person

(VARCHAR) 100

GENDER

The gender of the contact person

M = Male, F = Female, U = Unknown

(VARCHAR) 1

PHONENUMBER

The phone number of the contact person in E.164 international format.

Example: 31107989525

(VARCHAR) 20

EMAIL

The email address of the contact person

(VARCHAR) 100



Alphacomm control elements (CONTROL)

These fields are used to control the messages that are send by Alphacomm.

Field

Description

Format (Max.)

SUPPLIER

Identifier or name of a supplier. A mapping will be agreed with Alphacomm when used with Voice message.

(VARCHAR) 100

FLOWID

Identification of the Alphacomm script (campaign).

(VARCHAR) 10

Used services (SERVICES)

Field

Description

Format (Max.)

ENRICHMENT

Set this field to 1 when you want this record to be enriched. This only works when configured for your account.

(BOOLEAN) 0/1




Field specification result files

General result file

For the result files the same rules apply as for the input file. This means that the result file also contains field names to indicate the various results. Because of the dynamic character of the results, there can be no guarantee about the location of the different fields.

Each result contains these fields. When there are 2 phone numbers given, but when we used only one number to reach your customer, there is only 1 call result mentioned. This concerns all fields that can occur more than once.



Identification (IDENTIFICATION)

Field

Description

Format (Max.)

IDENTIFIER

Unique number that identifies a record. It is identical to the identifier from the input file.

(VARCHAR) 255

Callresult (multiple occurrences possible) (CALLRESULTS_CALL)

These fields contain all information concerning the result of the call actions. For each called phone number these fields are reported.

Field

Description

Format (Max.)

ATTEMPTS

Amount of attempts for this phone number.

(INT)

NUMBER

Phone number in E.164 international format.

example: 31107989525

(VARCHAR) 16

RESULT

Result code for the first phone number. See the table in the next paragraph.

(INT)

TIME

Date and time of the last attempt for this phone number

Example: 2014-02-12T15:19:21+00:00

(DATETIME)
Date and time in ISO 8601 format.

DURATION

Duration of the connection in seconds.

(INT)

VOICEMAIL

States the presence of a voicemail

(BOOLEAN) 0/1

DIRECTION

Direction of the call, inbound or outbound.

(VARCHAR) 20

CUSTOM

Client specific result codes (when agreed)

(VARCHAR) 100

Possible result codes for ‘RESULT’

Result code

Description

0

Not called

1

Reached, disconnected before succespoint

2

Succespoint reached, disconnected before the end of the message

3

Succespoint reached and completed call

4

No answer

5

Number busy

6

Call rejected

7

Number (temporarily) unavailable

8

Invalid number

9

Put through. Call is forwarded to your call centre

10

Not reached within calling period

11

No calls, unknown supplier

12

Voice mail message delivered (only with active detection)

13

The person who received the call indicated they are not the mentioned individual.

14

Completed call, but no success point was reached

 



SMS Results (SMSRESULTS_SMS)

These fields contain all information about the sent text messages. For each phone number we send a text message to, there is one result record.

Field

Description

Format (Max.)

NUMBER

Phone number in E.164 international format.

Example: 31107989525

(VARCHAR) 16

RESULT

Result code for the first phone number. Result codes are described in the table in the next paragraph.

(INT)

TIME

Date and time of the last attempt for this phone number.

Example: 2014-02-12T15:19:21+00:00

(DATETIME) Date and time in ISO 8601 format.

Result codes for SMS results

Result code

Description

0

Not (yet) delivered

1

Delivered

2

Not delivered

 





(Pay)mail results (multiple occurrences possible) (PAYMAILRESULTS_EMAIL_1)

These fields contain information about the sent emails. For each email address there is one record.

Field

Description

Format (Max.)

EMAIL

The address the email is send to.

(VARCHAR) 255

RESULT

Result code for the email address. Result codes are described in the table in the next paragraph.

(INT)

TIME

Date and time of the last update

Example: 2014-02-12T15:19:21+00:00

(DATETIME)
Date and time in ISO 8601 format.



Result codes for (pay)mail results

Result code

Description

0

Email has been draught

1

Email is send

2

Email is opened by receiver

3

The receiver has clicked on a link in the email

4

Email is returned (temporary soft-bounce)

5

Email is returned (definitive hard-bounce)

6

Spam complaint

7

Error, email is not send

8

Status unknown*

* the email is send by us, but we cannot confirm the delivery of the message. This status can be temporary and can change in time.

 

 

PayMail PayLink results (PAYMAILRESULTS_PAYLINK_1)

These fields contain information about the PayLink sent with the email. For each PayLink there is one record.

Field

Description

Format (Max.)

RESULT

Result code for the Paylink

(INT / STRING)

TIME

Date and time of the last check for this Paylink.

Example: 2014-02-12T15:19:21+00:00

(DATETIME) Date and time in ISO 8601 format.

 

Result codes for the PayLink sent with a PayMail

PayLink results v1

The original result codes are in integers.

Result code

Description

0

Paylink has been draught

1

Receiver has visited the landing page

2

Receiver started transaction

3

Receiver has arrived in bank environment, transaction is open.

4

Partial payment

5

Payment

6

Transaction overdue (session)*

7

Transaction cancelled (session)*

8

Error

9

Delay payment, requested by debtor



PayLink results v2

Results in text, active for new customers since Q4 2019. Available by request for all customers.

Result name

Description

created

PayLink has been draught

visited

Receiver has visited the landing page

started

Receiver started transaction

transaction_open

Receiver has arrived in bank environment

transaction_canceled

Transaction cancelled (session)*

transaction_expired

Transaction expired (session)*

paid

Payment completed

partially_paid

Payment completed on part of the amount

delayed

Delay payment, requested by debtor

error

Error occurred during creation or payment

 

PayMail Partial Paylink results (PAYMAILRESULTS_PARTIALPAYLINK_1)

These fields contain information about a Paylink when it is possible to partially pay it. For each PayLink there is one record.

Field

Description

Format (Max.)

CHOSEN_TERMS

The terms the customer has chosen.

(INT)

TRANSACTION_AMOUNT

The amount that is paid for the first term.

(INT) in cents

 

PayMail Payment method (PAYMAILRESULTS_PAYMENTMETHOD_1)

When configured for your reporting files.

Field

Description

Format (Max.)

NAME

Used payment method for PayLink payment.

See list of payment methods.

(STRING)


Current Payment methods

SMS PayLink results (SMSRESULTS_PAYLINK_1)

These fields contain information about the PayLink. For each PayLink there is one record.

Field

Description

Format (Max.)

RESULT

Result code for the PayLink

(INT / STRING)

TIME

Date and time of the result for this PayLink.

Example: 2014-02-12T15:19:21+00:00

(DATETIME) Date and time in ISO 8601 format.

 

 

Result codes for the PayLink sent with an SMS

PayLink results v1

The original result codes are in integers.

Result code

Description

0

PayLink has been draught

1

Error

2

Receiver started transaction

3

Transaction cancelled (session)*

4

Payment

5

Partial payment

6

Delay payment, requested by debtor

7

Receiver has visited the landing page

8

Transaction overdue (session)*

 

PayLink results v2

Results in text, active for new customers since Q4 2019. Available by request for all customers.

Result name

Description

created

PayLink has been draught

visited

Receiver has visited the landing page

started

Receiver started transaction

transaction_open

Receiver has arrived in bank environment

transaction_canceled

Transaction cancelled (session)*

transaction_expired

Transaction expired (session)*

paid

Payment completed

partially_paid

Payment completed on part of the amount

delayed

Delay payment, requested by debtor

error

Error occurred during creation or payment

 

SMS Partial Paylink results (SMSRESULTS_PARTIALPAYLINK_1)

These fields contain information about a Paylink when it is possible to partially pay it. For each PayLink there is one record.

Field

Description

Format (Max.)

CHOSEN_TERMS

The terms the customer has chosen.

(INT)

TRANSACTION_AMOUNT

The amount that is paid for the first term.

(INT) in cents

SMS Payment method (SMSRESULTS_PAYMENTMETHOD_1)

When configured for you reporting files.

Field

Description

Format (Max.)

NAME

Used payment method for PayLink payment.

See list of payment methods.

(STRING)

 

Emandate results (PAYMAILRESULTS_EMANDATE_1)

These fields contain all information concerning the sent Emandates. For each Emandate there is one record with the following fields.

Field

Description

Format (Max.)

RESULT

Result code of the Emandate

(INT)

TIME

Date and time of the last check

Example: 2014-02-12T15:19:21+00:00

(DATETIME)
Date and time in ISO 8601 format.

ID

Identification number of the Emandate

(VARCHAR) 35

DEBTOR_IBAN

Het IBAN number of the debtor

(IBAN)

DEBTOR_NAME

De name of the debtor

(VARCHAR) 70

DATE_OF_SIGNATURE

Date time of the given Emandate

(DATETIME)

SIGNATURE

Digital signature of the customer

(VARCHAR) 35

 

Result codes for Emandate sent with a PayMail

Result code

Description

0

Emandate has been draught

1

Receiver has visited the landing page

2

Receiver started transaction

3

Receiver has arrived in bank environment

4

Emandate awaits signature

5

Emandate given

6

Transaction overdue (session)*

7

Transaction cancelled (session)*

8

Error

* whenever a transaction is started in the bank environment we speak of a session. This session expires after some time. When a session is expired a customer can still start a new session to complete the process.



Enrichment results (multiple occurrences possible) (ENRICHMENTRESULTS_PHONENUMBER)

These fields contain the enriched phone numbers and the associated quality of the enrichment.

Field

Description

Format (Max.)

NUMBER

Phone number in E.164 international format.

Example: 31107989525

(VARCHAR) 16

QUALITY

Quality of the phone number. Scale of 1 (absolutely incorrect) to 100 (absolutely correct).

(INT)

LAST_VERIFIED

Date of the last verification.

(DATETIME)
Date and time in ISO 8601 Format.

Custom results (multiple occurrences possible) (CUSTOMRESULTS_CUSTOM)

These fields contain specific results and can differ between customers. These fields are only included when this is agreed in advance.

Field

Description

Format (Max.)

IDENTIFIER

The agreed code which can be used to identify a specific question in the script.

(INT)

VALUE

The input value of the customer.

(VARCHAR) 10

SERVICE

The specific service for which this result is reported.

(VARCHAR) 100

 

Payment methods

The name of the payment method used in our reporting.

Reported as</