background

How to import existing agreements

Tags:agreementsmandatescontractsimportimporteermandatenincassocontractencsv
Show me

Importing existing mandates can be done via the upload of a CSV file or via our API's.

Importing existing mandates via CSV file

Step 1 : Download the CSV file

To ensure all fields are imported correctly, your file must follow the structure of our file. The header fields must match exactly.
A detailed description of each header and the expected format is provided below.

Step 2 : Fill in the CSV file

Field NameDescriptionNotes & Constraints
customerNumber(*)Unique customer identifierReference/add to an existing customer. If not found, a new customer is created. Must appear only once in the file.
email(*)Customer email addressReference/add to an existing customer. If missing and no customerNumber exists, a new customer is created.
contractNumber(*)Contract number of the agreementIf empty, the profile’s default contract reference is used.
companyName(*)Name of the companyLeave empty if the invoiced entity is a person.
lLanguage / locale for communicationsAccepted: en, nl, nl_nl, fr, fr_fr, de, it, es, pt. Defaults to English if missing or unrecognized.
mandateNumberMandate referenceBy default generated automatically. Custom numbers must be unique and cannot start with the profile’s mandate prefix.
lastnameCustomer’s last name
firstnameCustomer’s first name
mobilePhone numberUse international format (e.g., +31, +32, +33).
cocCoC or VAT numberLeave empty for individuals.
addressStreet and number
cityCity
zipPostal code
countryISO country code (2 letters)Example: BE, NL, FR. See ISO 3166
ibanIBAN number
bicBICRecommended for foreign IBANs
campaignAssign agreement to a campaignDefault campaign name: uploadYYYYMMDD

(*) - Required fields : At least one value is required for the import to succeed.

Custom headers:
Any custom attribute defined on the selected profile can be included in the CSV. Values are stored in the agreement’s extra attributes and can be used in emails or for internal reference.

Step 3 : Import the CSV file

The import function is accessible at the top of your Twikey environment on all pages.

  1. Click the orange New button
  2. Select **import
  3. Select agreements
  4. Choose
    Type : Agreements
    Source : CSV
    Profile to use : Select the profile you wish to use
    Options: Check the box to mark the imported mandates as signed so they can be used immediatly.
    • mandateNumber and IBAN are required.
    • BIC is recommended for foreign IBAN accounts.
    • signDate is optional. If omitted, the current import date is used.
      For B2B mandates, some banks require the mandate signature date to match their records; otherwise, collections may be refused.
Twikey does not take any responsibility for the validity of the imported mandate
After importing the file, it is also possible to add a PDF. But this cannot be done in bulk.
Existing customer records are not updated when importing agreements. To update customers, use the customer import function, update manually, or delete the customer before importing.
Last Update: 2026-02-19