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 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:
CSV Import workflow
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
PATCHrequest 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.
- Upload and configure a CSV file by sending the
POSTrequest to/users/import/csv/upload. - Optionally, preview the import changes by sending the
POSTrequest to/users/import/csv/updatewithdry=true. - Import the file by sending the
POSTrequest to/users/import/csv/updatewithdry=false.
Upload a CSV file
The main differences between the endpoints are:
With the CSV Import API, you can upload:
- Any number of files concurrently
- Files of any size
- Files without defining the general import configuration
With the (legacy) Import API, you can upload:
- Only one file at a time
If you want to upload another file, either the current upload must be canceled or completed.
- Limited in terms of file size
- Only by defining the general import configuration
POST request to /users/imports/
In this method, you only specify the local path of your CSV file.
POST request to /users/import/csv/upload
In this method, you need to specify the local path of your CSV file and the initial configuration, which includes:
- File encoding
- Partial import tag, if the import you want is a partial import
Configure the import
PATCH 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. |
reportOnlyOnErrors | The parameter that defines if an email only needs to be sent to the reportMailAddress recipient if an error occurs. |
POST request to /users/import/csv/update
With endpoint, you can specify the mapping and define the following:
generateRecoveryCodessendMailsNewsendMailsPendinginvitationLanguagedryRun
Preview the import
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.
POST request to the /users/import/csv/update with dryRun parameter set to true.
Import a CSV file
PATCH request to /users/imports/{importId}, with state parameter set to IMPORT_PENDING.
POST request to /users/import/csv/update, with dry parameter set to false.
Migrate to new CSV Import
Now that you know the differences between the import methods, you can transition to the new CSV Import.