(New) Get Started With CSV Import

User Management via CSV Import API is one of the easiest and most scalable ways to manage users on the Staffbase platform. The functions and capabilities that the CSV Import API offers are similar to those of the manual CSV import in the Staffbase Studio. The main difference is that with the CSV Import API, the script runs on an automatic schedule. This reduces or eliminates manual efforts, and comes with some additional capabilities.

Similar to manual CSV import, you need to actively push or upload the CSV file from your local environment to the Staffbase platform for automatic CSV import. You can do this with upload and update requests to the Staffbase endpoints. These calls are always performed in succession for the automatic CSV import. With the CSV Import API, Staffbase supports both complete imports and selected user imports. The selected user imports are also referred to as delta imports. Use this guide to get started with the automatic CSV import using the CSV Import API. The examples provided in the instructions use the cURL command line.

• 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.
• You have a good understanding of the new CSV import via the Staffbase Studio.
• You have the (new) CSV Import enabled for your platform.

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 PATCHrequest to /users/imports/{importId}/config/.
3. Optionally, preview the import changes by sending the PATCHrequest 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.

You can find examples of CSV files on our Support Portal.

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.

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 on the overview page of the Staffbase Studio.

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

1. Make a GET request to the endpoint /users/imports.

curl -X 'GET' \
  'https://exampleapp.staffbase.com/api/users/imports?limit=20' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic {Token}'

{
  "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"
}

2. Save the id from the response. This id is the importId required in the next step.

3. Make a PATCHrequest to the endpoint /users/imports/{importId}/config , with the following details:

curl -X 'PATCH' \
  'https://exampleapp.staffbase.com/api/users/imports/{importId}/config' \
  -H 'accept: */*' \
  -H 'Authorization: Basic {Token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "delta": false,
  "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",
        "userName": : "Identifier",
        "profile-field:position" : "Position"
    }
}'

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.

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

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

You get a 204 response.

2. Make a GET request to the endpoint /users/imports/{importId}/status.

curl --location 'https://exampleapp.staffbase.com/api/users/imports/{importId}/status' \
--header 'Authorization: Basic {Token}'

{
  "totalLines": 5,
  "completedLines": 3,
  "status": "PREVIEW_READY",
  "changes": {
    "created": 5,
    "updated": 0,
    "deactivated": 0,
    "deleted": 0,
    "errors": [
      {
        "line": 2,
        "subject": "column",
        "property": "name",
        "value": "Gustav"
      }
    ]
  }
}

You can view the changes that come with the import in the response.

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

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.

• CSV Import migration guide
• Use case guides:
  • Check the status of CSV Imports
  • Manage delta imports using the CSV Import