Skip to main content

CSV Integration

For a less development heavy approach to sync your data into OurPeople you can take advantage of our CSV integration.

You can upload CSV files containing your company data to an SFTP server and OurPeople will automatically import the data into your OurPeople space.

CSV files are read periodically and used as a source of truth for your data. This means that any changes you make to your CSV data will be reflected in OurPeople after a short delay. Exact timing of the delay will vary, but typically you can expect changes to appear within 4 hours.

Getting started​

Our CSV integration is offered on request. If you are interested in using this integration please contact support@ourpeople.com.

CSV format​

The integration requires 3 CSV files to be present on the SFTP server. Each file must adhere to these requirements:

  • The first row must contain column headers
  • Each row must contain the same number of columns
  • Each column header should be unique
  • Column headers are case-sensitive
  • Values should be separated by a comma (,)
  • Rows should be separated by a newline character (\n)
  • Values can optionally be enclosed in double quotes (")
  • File names must be constant

Also note that:

  • Records that were present and subsequently removed from a CSV file will be removed from OurPeople. We treat the CSV files as the source of truth and will update OurPeople to match them.

users.csv​

Download an example users.csv

This file contains information about your users. Each row represents a single user and each column represents a single attribute of that user. The following columns are supported:

id​

A unique and constant ID for the user. Required.

employeeId​

An identifier for the employee. The employee ID is displayed as additional information in the user's account, it is not used for any relationships. Optional.

firstName​

The user's first name. Required.

lastName​

The user's last name. Optional.

emailAddress​

The user's email address. Optional.

mobileNumber​

The user's mobile number in E.164 format. Optional.

deactivated​

A 1 or 0 value indicating whether the user is deactivated. Deactivated users are synced but marked as frozen in OurPeople. You can use this to suspend a user's access to OurPeople. Optional.

roleId​

The user's access level. Must be one of the roles listed below. If no role is provided, any value assigned manually will be used instead. Optional.

  • ROLE_USER - App User
  • ROLE_APP_BROADCAST - Cover Sender
  • ROLE_APP_ADMIN - Cover Assigner
  • ROLE_BROADCAST_ADMIN - Broadcast Admin
  • ROLE_ADMIN - Team Admin
  • ROLE_SUPER_ADMIN - Global Admin

adminTeamId{1..n}​

The id of a tag in tags.csv. You can specify multiple tags by adding multiple adminTeamId headers, each one with a unique suffix, e.g. adminTeamId1, adminTeamId2, etc.. When paired with a roleId value of ROLE_ADMIN or ROLE_BROADCAST_ADMIN the user will be given admin permission for the given teams. If no teams are provided, any values assigned manually will be used instead. Optional.

tags.csv​

Download an example tags.csv

This file contains information about your tags. Tags are used in OurPeople to provide powerful filtering options, allowing you to target content, or limit access to people with specific combinations of tags.

OurPeople supports the following tag types: Region, Team, Department, JobTitle and Skill. We will map your tags to one of these types.

Each row in the CSV represents a single tag and each column represents a single attribute of that tag. The following columns are supported:

id​

A unique and constant ID for the tag. Required.

name​

The name of the tag. Required.

source​

A string denoting where the tag came from in your own system or what it represents. Sources are used to map against our own tag types. For example we might map a tag with source "job" to tag type "jobTitle" in OurPeople. Required.

profiles.csv​

Download an example profiles.csv

This file pairs the data in your users.csv with the data in your tags.csv. Each user can have multiple profiles. A profile is a collection of tags which together can define the user's roles/responsibilities.

You can put all of your tags in to a single profile, and this is typical for most users as they typically only have one role. But there are cases where a user might have two distinct roles and being able to target content at those roles separately is useful.

For example a person might work 50% of their time as a "HR Manager" in one location and 50% of their time as a "Practice Manager" in another. In this case you might create two profiles for the user, one with tags "Region: California" and "JobTitle: HR Manager" and another with tags "Region: Nevada" and "JobTitle: Practice Manager".

Each row in the CSV represents a single profile and each column represents a single attribute of that profile. The following columns are supported:

id​

A unique and constant ID for the profile. Required.

userId​

The id of a user in users.csv. Required.

tagId{1..n}​

The id of a tag in tags.csv. You can specify multiple tags by adding multiple tagId headers, each one with a unique suffix, e.g. tagId1, tagId2, etc.. Optional.

SFTP server​

Once your files are ready they can be hosted on any SFTP server. If you would like to host on the OurPeople SFTP server you will first need to request credentials to grant you access. Alternatively you will need to provide connection details and credentials to your own SFTP server. In either case please contact support@ourpeople.com so that the location of your files can be correctly configured and your integration enabled.

Note that the OurPeople SFTP server adheres to same level of data protection as the rest of the OurPeople platform. All data is encrypted in transit and at rest.

Sync results​

Download an example sync_result.json

At the end of each sync a sync_result.json file will be uploaded to the same location as your CSV files. This file will contain a summary of the sync results, including an error message if one is available.

sync_result.json

{
  "syncId": string,
  "finishedAt": string,
  "success": boolean,
  "errorMessage": null | string
}

Other integrations​

As well as offering a CSV integration, we also integrate with some well known HR systems such as ADP, Paychex and CIPHR. If you are interested in knowing more about our other integration options please contact support@ourpeople.com.