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.

  

This article is part of the guide to creating a custom integration.
If your integration is via a module, this tag will be added to your ecommerce platform automatically.

 

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.

API_de_importaci_n_-_1-min.png

 

2. Click the   Create new API Key button.

API_de_importaci_n_-_2-min.png

 

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

API_de_importaci_n_-_3-min.png

 

4. Save the changes to register the API key.

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

API_de_importaci_n_-_4-min.png

 

STEP 2. Create the import

  

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

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".

API_de_importaci_n_-_5-min.png

 

In the following CSV you can see an example where _email, _name and _points correspond to the identifiers of the Email, Name and Points system 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

 

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

 

Example

 

In the following example is a basic Node.js script to automate the import 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}`,
            ...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);
});
  

The script creates an import from a CSV file whose path is set by environment variable. After creating the import, it checks its status every two seconds and ends when the import status equals finished

 

 

Success!
API integrations are ready.

 


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:

Was this article helpful?
0 out of 0 found this helpful