Manage Delta Imports Using the (New) CSV Import API

Learn how to sync and update the data of a subset of users using the (New) CSV Import API.

Employee App
Front Door Intranet
beta

CSV Imports is one of the easiest ways to import and sync user data into the Staffbase platform. Using the (new) CSV Import API makes it even easier to automate data syncs and keep your constantly evolving user database up to date.

In this article, we’ll look at how to do a delta import using the (new) CSV Import API.

Delta import refers to imports that sync and update only a subset of your user base. This can be very useful in different scenarios. If you want to offboard users using delta imports, by deactivating or deleting their accounts, you need to specify the intended user status in the CSV file. To do this, you can add a column called Status_code in your CSV file and populate each user’s account status. For information on setting up the file, see the examples. You can add the following account statuses for users:

  • Activated
  • Deactivated

During the delta import, if deactivated status is added for:

  • Pending user: The account is deleted.
  • Registered user: The account is deactivated.

The delta imports are different from the legacy partial imports. You do not need partial import CSV tags. All user data changes only if the changes are included explicitly. This gives delta imports more flexibility over the legacy partial imports.

For example:

  • Multiple branches or locations
    If you have various branches or locations for your organization, you can then perform a delta import to synchronize and update only the user data of that specific location. This way, only a subset of the user database will have their data synced and updated.
  • Syncing new employees
    Most organizations have a consistent influx of new employees. In this case, you may only want to sync the data of the new employees and not touch the existing user data. This is another scenario where delta import can be helpful.

In all of the above cases, if you do not use the delta import and update all users, the import deactivates active users and deletes pending users who are not in the CSV file.

  • You have enabled the (New) CSV Import for your platform.
  • You have the user data in CSV file format.
  • The identifier for each user is defined in the CSV file.
    If you already have existing users in the platform, ensure the identifiers are set and match the identifiers in the CSV file.
  • You have generated an API token with administrative access via the Staffbase Studio. Learn more.

The process of performing an automated CSV import in a nutshell.

  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 parameter set to IMPORT_PENDING.

Make a POST request to the endpoint /users/imports with the path of the CSV file in your local computer.

Example request

The following cURL command uploads a new CSV file from your local computer to your Staffbase platform.

Terminal window
curl -X 'POST' \
  'https://exampleapp.staffbase.com/api/users/imports' \
  -H 'accept: */*' \
  -H 'Authorization: Basic {Token}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@showcase_user_export_2024-03-06.csv;type=text/csv'

Your CSV file is uploaded to the Staffbase platform. You can view it in the overview page of the Staffbase Studio.

In the response header, you can see the location URL of the imported file.
For example, https://exampleapp.staffbase.com/api/users/imports/660e76a12487882f89a095b4e

You can save the id from the response. In this case, 660e76a12487882f89a095b4e.
This id is the importId required for further steps.

Do the following to map the CSV attributes to the Staffbase Studio profile fields:

Skip 1 and 2 steps if you already have the importId.

  1. Make a GET request to the endpoint /users/imports.
Example request
Terminal window
curl -X 'GET' \
  'https://exampleapp.staffbase.com/api/users/imports?limit=20' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic {Token}'
Example response
Terminal window
{
  "entries": [
    {
      "id": "64b0fbf58e05e970f88a2791",
      "createdAt": "2023-07-14T07:40:37.478Z",
      "fileName": "mariokart_user_export_2023-06-14.csv",
      "fileSize": 2010,
      "recordCount": 8,
      "state": "DRAFT",
      "owner": {
        "ownerId": "645de133f3e49f6b7f78cfff",
              }
    }
  ],
  "nextCursor": "NjU0YjU3ZDBhZTBjMmQzNTc2OTk3NTU4_dHJ1ZQ",
  "prevCursor": " NjU0MzUxMjNmNmJiMzA0ZjRiZmEzOWYy_ZmFsc2U"
}
  1. Save the id from the response. This id is the importId required in the next step.

If there are multiple imports, you can identify the import you want based on the following parameters:

  • createdAt
  • fileName
  • ownerId
  1. Make a PUT request to the endpoint /users/imports/{importId}/config/, with delta parameter set to true.
You need to map the status parameter to the Status_code column of your CSV file only if you want to add or update user data using the delta import.
Example request
Terminal window
curl -X 'PUT' \
  'https://exampleapp.staffbase.com//api/users/imports/{importId}/config' \
  -H 'accept: */*' \
  -H 'Authorization: Basic {Token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "delta": true,
  "encoding": "UTF-8",
  "generateRecoveryCode": false,
  "reportMailAddress": "recipient@company.com",
  "reportOnlyErrors": false,
  "sendMailsNew": true,
  "sendMailsPending": true,
  "separator": ";",
  "mapping": {
        "profile-field:firstName": "First Name",
        "profile-field:lastName": "Last Name",
        "externalId": "Identifier",
        "profile-field:position" : "Position",
        "status":"Status_code"
    }
}'

You can map one column from your CSV file to multiple profile fields. For example, externalId,userName maps the identifier and username based on the same column.

See CSV Import error list to help you analyze your CSV import and get more information on potential warning and error codes.

After configuring the mapping, you can preview the file.

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

Example request
Terminal window
curl -X 'PATCH' \
  'https://exampleapp.staffbase.com/api/users/imports/{importId}' \
  -H 'accept: */*' \
  -H 'Authorization: Basic {Token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "state": "IMPORT_PENDING"
  }'

You can now schedule the imports and updates based on your business requirements using this CSV import workflow. You can use any scheduling tool of your choice. For example, if you’re using the cURL command-line for Unix or Linux, you can use the cron job command for scheduling.