API imports

Connectif allows you to automate bulk imports of contacts, products and vouchers using the Import API.

In this article, you’ll learn how to import your contact information, product catalog, and shopping vouchers via the Connectif API.

 

Before we begin: use cases

This API covers the following use cases:

• If you want to automate periodically (daily, weekly, etc.) the synchronization of all or a large part of your contacts or products.
• If you want to import vouchers to a voucher set.

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

 

STEP 1. API key creation

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

 

2. Click the   Create new API Key button.

 

3. In the Imports section of the authoring panel, enable the bulk Read, Write and Delete permissions.

 

4. Save the changes to register the API key.

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

 

STEP 2. Create the import

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

• Encoding UTF-8.
• The first row must contain the name of the headers of each field.
• The headers of the contact file must match the IDs of the Connectif Contact fields which you will find in your account, in "Contacts > Contact fields".

_email,_name,_points
john@example.org,John,10
micheal@example.org,Michael,10
steve@example.org,Steve,20
mark@example.org,Mark,12
carl@example.org,Carl,10

 

• The product data must match the field names with the same in the visited product event notification.
• The voucher import must contain a single "code" header.

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

 

Example

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}`,
            ...form.getHeaders()
        },
        body: form
    });

    if (!response.ok) {
        console.error(response.status, await response.json());
        process.exit(1);
    }

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

    while(true) {
        const getResponse = await fetch(`https://api.connectif.cloud/imports/${id}`, {
            method: 'GET',
            headers: {
                'Authorization': `apiKey ${apiKey}`
            }
        });
        const { success, errors, status } = await getResponse.json();
        console.log(`completed ${success + errors} of ${total}`);

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

main().catch(error => {
    console.error(error);
    process.exit(1);
});

 

 

---

Frequently asked questions

What is the maximum file size to import?

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

 

How many imports can be queued at once?

A maximum of 10 imports can be queued at a time. Once this limit is reached, we will have to wait for an import to complete before putting the next one in the queue.

 

Can the imports that I make via API be queried from the Connectif application?

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

 

Can I delete a queued or in-progress import?

Currently, it is possible to delete imports only in the finished or error states.

 

---

Keep learning!

To make the most of your Connectif account, we recommend reading these articles next:

• Onboarding, to learn all about our interface.

• Initial workflows, to implement your first strategies in your account.

• Integrations with external systems, to integrate your Facebook, website forms and webhooks.

• Events that use your Activity allowance, to understand your account consumption better.