Learn how to migrate from the (legacy) CSV Import API to the (new) CSV Import API.
Staffbase offers a new CSV Import API that simplifies and streamlines the process of importing user data. This new API offers significant improvements compared to the previous (legacy) CSV Import API.
This article explains the difference between the legacy CSV Import API and the new CSV Import API workflows and endpoints. Understanding these differences will allow you to migrate to the new API and take full advantage of its benefits. For getting started with the CSV Import API, see (New) Get Started With a CSV Import.
It is also important to note that the legacy method is planned to be deprecated in the future. Therefore, Staffbase recommends you transition to the new method at your earliest convenience.
This article covers only the endpoints for the main processes. It does not include example requests and responses for the endpoints for the main processes. If you want to learn more about examples or other endpoints not covered in the article, refer to the respective API specifications:
The workflow for both CSV import methods remains relatively the same, but the endpoints and functionalities differ providing more flexibility.
- Upload a CSV file by sending the
POSTrequest to/users/imports/. - Configure the CSV file mapping by sending the
PUTrequest to/users/imports/{importId}/config/. - Optionally, preview the import changes by sending the
PATCHrequest to/users/imports/{importId}with state parameter set toPREVIEW_PENDING. - Import the file by sending the
PATCHrequest to/users/imports/{importId}with state set toIMPORT_PENDINGin the request body.
The main differences between the endpoints are:
With the (new) CSV Import API, you can upload:
- Any number of files concurrently
- Files of any size
- Files without defining the general import configuration
POST request to /users/imports/
In this method, you only specify the local path of your CSV file.
PUT request to /users/imports/{importId}/config/
In this method, you need to specify the general configuration and mapping.
Under general configuration, you can define:
- Running an import for:
- All users
- A subset of users, also known as delta.
You can define it by setting the delta parameter to true.
- Sending the CSV import report:
- To a recipient
- To a recipient only if an error occurs
| Parameter | Description |
|---|---|
reportMailAddress | The parameter to add a recipient email address for the processed CVS import report. |
reportOnlyErrors | The parameter that defines if an email only needs to be sent to the reportMailAddress recipient if an error occurs. |
PATCH request to the endpoint /users/imports/{importId}, with state parameter set to PREVIEW_PENDING
This is an additional step in the process for previewing the import, which makes the process more reliable than the legacy import method.
PATCH request to /users/imports/{importId}, with state parameter set to IMPORT_PENDING.
Now that you know the differences between the import methods, you can transition to the (new) CSV Import.