Migrating Contacts Integration from Email Classic to Staffbase Email

The Employee Email (Classic) Contact API is being deprecated together with the Employee Email (Classic) platform. To continue managing contacts effectively in Staffbase Email, Staffbase recommends migrating any existing Contact API integrations to one of the following APIs:

• User API: for real-time data synchronization
• CSV Import API: for bulk operations

This guide walks you through both migration paths in detail.

Moving away from the Employee Email (Classic) and Contact API enables you to take advantage of a more robust and feature-rich platform with improved performance, modern authentication for enhanced security, and expanded contact management capabilities.

The first step in migrating from the Contact API is selecting the right replacement API. Your choice depends on your technical requirements and business needs, and it will define the architecture of your new integration. You can choose between a real-time or bulk-processing approach:

• User API: This API is the ideal choice for event-driven systems that require immediate data consistency. Use it if your integration needs to respond instantly to changes. For example, a Staffbase account needs to be created as soon as a new employee is added to your Human Resources Information System (HRIS). The User API provides the necessary endpoints for direct, real-time control. It’s built for low-latency, transactional operations on individual contact records.
• CSV Import API: This API is best suited for scenarios involving large datasets and scheduled updates. Use it if you’re migrating a significant volume of contacts from a legacy system or working with batch exports. The CSV Import API provides the necessary endpoints for efficient and reliable bulk data processing. It is designed to handle thousands of records at once and includes a stateful import process that you can monitor.

• Create an API token with administrative access via the Staffbase Studio.

• Before importing contacts, ensure all custom fields in your JSON payload or CSV file are set up in Staffbase Studio.
  To identify the required fields, check the customFields object (reference) nested in the contacts object in your current Employee Email (Classic) JSON data and add any missing fields in the Studio before proceeding. Learn more.

For the migration example, we need to add the following custom fields:

• team
• costcenter

Employee Email (Classic) JSON example

{
  "contacts": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@email.com",
      "location": "Vancouver",
      "department": "Sales",
      "jobTitle": "SDR",
      "customFields": {
        "team": "Team A",
        "costcenter": "12345"
      }
    },
    {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane.doe@email.com",
      "location": "Vancouver",
      "department": "Sales",
      "jobTitle": "VP",
      "customFields": {
        "team": "Team B",
        "costcenter": "12345"
      }
    },
    {
      "firstName": "Jim",
      "lastName": "Doe",
      "email": "jim.doe@email.com",
      "location": "Vancouver",
      "department": "Product",
      "jobTitle": "Engineer",
      "customFields": {
        "team": "Team B",
        "costcenter": "12345"
      }
    }
  ]
}

{
  "externalId": "john.doe@email.com",
  "email": "john.doe@email.com",
  "profile": {
    "firstName": "John",
    "lastName": "Doe",
    "location": "Vancouver",
    "department": "Sales",
    "position": "SDR",
    "team": "Team A",
    "costcenter": "12345"
  },
  "status": "contact"
}

externalId,firstName,lastName,email,location,department,position,team,costcenter
john.doe@email.com,John,Doe,john.doe@email.com,Vancouver,Sales,SDR,Team A,12345
jane.doe@email.com,Jane,Doe,jane.doe@email.com,Vancouver,Sales,VP,Team B,12345
jim.doe@email.com,Jim,Doe,jim.doe@email.com,Vancouver,Product,Engineer,Team B,12345