CSV Import Migration Guide

Learn how to migrate from the (legacy) CSV Import API to the (new) CSV Import API.

Employee App
Front Door Intranet

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:

CSV Import workflow

The workflow for both CSV import methods remains relatively the same, but the endpoints and functionalities differ providing more flexibility.

  1. Upload a CSV file by sending the POST request to /users/imports/.
  2. Configure the CSV file mapping by sending the PUT request to /users/imports/{importId}/config/.
  3. Optionally, preview the import changes by sending the PATCH request to /users/imports/{importId} with state parameter set to PREVIEW_PENDING.
  4. Import the file by sending the PATCH request to /users/imports/{importId} with state set to IMPORT_PENDING in the request body.

Upload a CSV file

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.

Configure the import

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
    Use the following additional parameters to send CSV reports:
reportMailAddressThe parameter to add a recipient email address for the processed CVS import report.
reportOnlyErrorsThe parameter that defines if an email only needs to be sent to the reportMailAddress recipient if an error occurs.

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.

Import a CSV file

PATCH request to /users/imports/{importId}, with state parameter set to IMPORT_PENDING.

Migrate to (new) CSV Import

Now that you know the differences between the import methods, you can transition to the (new) CSV Import.