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?
The V5 equivalent to import data in bulk is the 'one shot ETL' V5 operation.
POST /mass-imports/v5/entities/{entity}/etl-executions
What are its advantages?
In addition to the same functional scope as V4 imports, the 'one shot ETL' V5 operation benefits 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.
How to update these calls?
Just like the V4 imports, the V5 operation consists in a multipart/form-data body containing 2 files: a CSV file with the data and JSON file with the ETL definition.
The path and the definition of the JSON file differ slightly between the V4 and V5 operations. To assist developers in their updates, a side-by-side walkthrough is available on the developers portal.
What is the timing?
V4 imports will remain supported until the end of June 2025.
They should be upgraded to one shot 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
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.