API imports


Questo articolo è attualmente disponibile in inglese e spagnolo. Puoi fare riferimento a questa documentazione mentre arriva nella tua lingua.

Connectif allows you to automate massive imports of contacts, products, and coupons through the Import API.

In this article, you will learn how to import information about your contacts, your product catalog, and your shopping coupons through the Connectif API.


This article is part of the guide to creating a custom integration.
If your integration is via module, this tag will be automatically inserted into your eCommerce.


Before you start: use cases

This API covers the following use cases:

  • If you want to automate periodically (daily, weekly...) the synchronization of all or a large part of my contacts or products.
  • If you want to import coupons into a coupon set.

This API does not cover the importation of purchase events but can serve as a starting point. To set up purchases, check the documentation of the Connectif API.


STEP 1. Creation of the API key

1. Go to your Connectif account and navigate to the API Keys section.



2. Click the   Create new API Key button.



3. In the Imports section of the creation panel, enable permissions for Read, Write, and Delete on a massive scale.



4. Save the changes to register the API key.

5. Copy the API key to later use it in your automation script.



STEP 2. Creation of the import


To create the import, you will need to make a HTTP POST multipart/form-data request, which will send the CSV file and various metadata (such as the delimiter, the type of import, etc.).

6. Create and ensure your CSV import file meets the following conditions:

  • UTF-8 encoding.
  • The first row should contain the names of the headers for each field.
  • The headers of the file for contacts must match the IDs of the Contact Fields of Connectif, which you can find in your account, in "Contacts > Contact Fields".



The following CSV is an example where _email, _name, and _points correspond with the system field identifiers Email, Name, and Points.



  • Data for products must match the field names as outlined in this article.
  • The import of coupons must contain a single header "code".

7. Create the script and include the generated API key in it from step 1.




The following example shows a basic script in Node.js to automate the importation of contacts.

Once the import is created, it will look like this:

const fetch = require('node-fetch');
const fs = require('fs');
const FormData = require('form-data');

const apiKey = process.env.API_KEY;
const filePath = process.env.FILE_PATH;

async function main() {
    const form = new FormData();
    form.append('type', 'contacts')
    form.append('delimiter', ',')
    form.append('overrideExisting', 'true')
    form.append('updateOnlyEmptyFields', 'false')
    form.append('file', fs.createReadStream(filePath));

    const response = await fetch('https://api.connectif.cloud/imports', {
        method: 'POST',
        headers: {
            'Authorization': `apiKey ${apiKey}`,
        body: form

    if (!response.ok) {
        console.error(response.status, await response.json());

    const { id, total } = await response.json();

    while(true) {
        const getResponse = await fetch(`https://api.connectif.cloud/imports/${id}`, {
            method: 'GET',
            headers: {

': `apiKey ${apiKey}`
        const { success, errors, status } = await getResponse.json();
        console.log(`completed ${success + errors} of ${total}`);

        if (status === 'finished') {
            console.log('Success 🎉 🎉 🎉 🎉 🎉 🎉 🎉');
        await new Promise(resolve => setTimeout(resolve, 2000));

main().catch(error => {

The script creates an import from a CSV file whose path is set by an environmental variable. After creating the import, it checks its status every 2 seconds and finishes when the import status is equal to finished



API integrations are now ready.


Frequently Asked Questions

What is the maximum file size for imports?

The CSV files for import cannot exceed 50 MB in size.


How many imports can be queued at once?

A maximum of 10 imports can be queued at once. Once this limit is reached, you will need to wait for one import to complete before queuing the next.


Can the imports I do via API be seen from the Connectif application?

Yes, the import engine is the same one used by the Connectif application. Therefore, imports done via API and app are both available in the list of imports.


Can I delete an enqueued or in-progress import?

Currently, imports can only be deleted in the states finished or error.


Keep learning!

To take full advantage of your account on Connectif, we recommend continuing with the following articles:

Questo articolo ti è stato utile?
Utenti che ritengono sia utile: 0 su 0