CSV Import Migration Guide

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

Employee App
Staffbase 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:

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 PATCH 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.
  1. Upload and configure a CSV file by sending the POST request to /users/import/csv/upload.
  2. Optionally, preview the import changes by sending the POST request to /users/import/csv/update with dry=true.
  3. Import the file by sending the POST request to /users/import/csv/update with dry=false.

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

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

The (new) import does not support the partial import function. Instead, it has an advanced feature called delta import, which covers the same use case as partial import. Learn more.

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
    Use the following additional parameters to send CSV reports:
ParameterDescription
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.

POST request to /users/import/csv/update

With endpoint, you can specify the mapping and define the following:

  • generateRecoveryCodes
  • sendMailsNew
  • sendMailsPending
  • invitationLanguage
  • dryRun

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.

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.

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