Data import

Data import using Web API consists of the following steps:

  1. Preparing the file for import.
  2. Uploading the file to the system.
  3. Running the data import.
  4. Checking the import results.

Let’s consider these steps in more detail.

Prepare the file for import

The import template file is different for each app. You can download an app’s template once and fill it with data whenever you need to import data.

Depending on the amount of data and the capabilities of the data source system, the file can be filled out manually or automatically.

When the file is prepared, move on to the next step.

Upload the file to the system

To import data, you can use the method for uploading a file to a directory or the method for uploading a temporary file to the system. However, when you use the second method, you need to remember that the file will only be stored in the system for 60 minutes, and the data import must be finished within this timeframe. So when importing large chunks of data (more than 50,000 entries at a time), it is recommended to upload the file to a directory.

Note: One of the required parameters for both methods is hash. It is needed later to call the data import method. Please save the generated hash, as it is not returned in the response.

You can find an example of uploading a file to a directory in the article about connecting to the file upload API using TypeScript.

When the file is successfully uploaded to the system, you can move on to importing the data.

Run the data import

To start the data import, you need to use the hash of the previously uploaded file. In the request body, you also need to pass the file format (.xlsx or .csv) and ignore event handlers (withEventHandlers: false). It is recommended to ignore event handlers when importing large amounts of data, as they can create a high load and influence the system’s performance.

If your business logic requires using event handlers during import, it is recommended to import data in small chunks (up to 1,000 entries) and make pauses between requests to let the system finish processing the message queue.

If import starts successfully, the response to the request will contain information about the number of items that have been imported, the status of the current import and its ID that can be used to retrieve the status.

Note: If data import to an app is started, you won’t be able to start another import process. The request will return the status blocked.

Check the import result

The method for getting import status returns the same response as the method that starts the import process. By making this request with a certain frequency, you can get up-to-date information about the number of imported items and determine when the import finishes. It is recommended to request the import status no more frequently than once a second.