Skip to main content

V4 Mass Imports

V4 profile & custom table mass imports​

Mass imports are used to push a .csv file to update your profile and custom tables in bulk. They consist in a multipart/form-data body containing 2 files: a (zipped) CSV file with the data, and a JSON file with the definition of the import.

They are made with the following operations to 'Create a profile table import' and 'Create a custom table import':

POST /v4/entity/{entity}/table/{table}/import for profile tables

POST /v4/entity/{entity}/customTable/{table}/import for custom tables

What is the V5 equivalent?​

There are two V5 equivalent to import data in bulk:

POST /mass-imports/v5/entities/{entity}/etl-executions

POST /mass-imports/v5/entities/{entity}/etls/{etlId}/trigger-execution

What are their advantages?​

In addition to the same functional scope as V4 imports, both V5 operations benefit from all the extra features inherent to ETLs, namely:

  • Data transformation: transformations can be applied to format the data before loading into your Actito tables.

  • Retrieving the file on a remote location: instead of pushing the file directly in the body of the call, one shot ETLs can retrieve the file directly on a cloud location, like a FTP server.

tip

Retrieving the file remotely is a possibility, not a requirement.
The file can still be provided directly in the body of the API call, like for V4 imports.

What is the difference between the 2 alternatives?​

  • With one shot ETLs, the definition of the import parameters (table destination, mapping, transformations, report recipients,...) is provided in the API call, together with the data file.
    It is mostly used for occasional non-recurring imports with parameters that change every import.

  • With ETL executions triggered by API, the import parameters have been predefined beforehand and have a fixed definition, so the API call is only used to push the data file.
    It is ideal for recurring imports, where you have the same data flows at a set frequency (same table, mapping, etc).

    Of course, if you have data flows into different tables, you can set up multiple ETL definitions, or even a multifiles ETL, which allows you to import data into different table with a defined sequence (and is not possible with 'one shot ETLs').

    In addition, the definition of 'ETL executions triggered by API' is visible in the user interface (while only "finished" one shot ETLs are visible), enabling marketeers from having an overview of their recurring data flows.

tip

As there is usually a logical pattern and frequency for imports, we believe that 'ETL executions triggered by API' will be the best option if most cases.

How to update these calls?​

To assist developers in their updates, a side-by-side walkthrough is available on the developers portal.

It presents both options and how to set up them, with a direct format comparison between v4 and v5 operations.

What is the timing?​

V4 imports will remain supported until the end of June 2025.

They should be upgraded to v5 ETL executions before this date.

Following up imports​

Once an import has been created, several calls can be used to retrieve the status, result, error file and result file of this import.

These operations are replaced by the equivalent V5 operations related to one shot ETLs. After creating a oneshot ETL execution, its "id" is given as response, which allows to make the subsequent calls.

Retrieving the import status​

The V4 call to retrieve the import status is:

GET /v4/entity/{entity}/import/{import}/status

Once a one shot ETL execution has been created, its status can be retrieved with the V5 operation to 'Get a single ETL execution':

GET /mass-imports/v5/entities/{entity}/etl-executions/{etlExecutionId}

The response is a bit different from the V4 as it includes a repeat of the definition of the ETL. The information in the "status" parameter is the replacement of the V4 call.

Retrieving the import result​

Once the status of an import was FINISHED, its result could be retrieved with the following call:

GET /v4/entity/{entity}/import/{import}/result

You can now retrieve the result of a one shot execution with the V5 operation to 'Get a single ETL execution's results':

GET /mass-imports/v5/entities/{entity}/etl-executions/{executionId}/integration-results

tip

It is also possible (and recommended!) to set up a webhook on ETL executions.

Retrieving the import error and result files​

Depending on the result of the import, you could

GET /v4/entity/{entity}/import/{import}/errors

GET /v4/entity/{entity}/import/{import}/result-file

With one shot ETL executions, you can now retrieve both files at once, thanks to the V5 operation to 'Get a single ETL execution's output files':

GET /mass-imports/v5/entities/{entity}/etl-executions/{executionId}/output-files

tip

To be able to retrieve the output files, their generation must be defined in the parameters of the one shot ETL.