API Imports

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. Creating the API Key

1. Go to Store Settings in the left sidebar menu.

2. In the tab selector, go to "API and IP access" and click on API Keys.

Import via API (screenshots August 24) - 1-min.png

3. Click the   Create new API Key button.

Import via API (screenshots August 24) - 2-min.png

4. In the Imports section of the creation panel, enable the permissions for Read, Write, and Delete in bulk.

Import via API (screenshots August 24) - 3-min.png

 

5. Save the API key and copy it for later use in your automation script.

Import via API (screenshots August 24) - 4-min.png

 

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

API_de_importacio_n_-_5-min.png

 

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

_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

 

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

 

Example

 

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}`,
            ...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 an environmental variable. After creating the import, it checks its status every 2 seconds and finishes when the import status is equal to finished

 

 

Success!
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:

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