Bulk data import

The bulk import adds people to your Deeper Signals account and keeps their data current. One file format carries up to three layers of data, and there are two ways to deliver it: upload it through the API, or place it on an SFTP server that Deeper Signals polls. Both paths run the same import, so the file is identical.

Layer	Columns	What it does
Users (required)	user, first_name, last_name	Creates users that do not exist yet and updates the names of those that do. The e-mail address in user is the identifier.
Teams (optional)	manager	Builds the reporting hierarchy: each user is placed under the manager with that e-mail address.
HRIS attributes (optional)	any further column	Imported as attributes of the user (department, location, hire date, salary band, ...) and available as filters, columns and chart dimensions in analytics.

File format

Option	Requirement
Type	CSV (comma-separated values), UTF-8
Extension	.csv
Delimiter	, (also accepted: ;, tab, |; the delimiter is detected from the first line)
Row 1	Column names. user, first_name and last_name are required; the order of columns does not matter.
Row 2	Column types (only needed when the file carries HRIS attributes): email for user and manager, name for the name columns, and keyword, numeric or date for each HRIS attribute.
Rows 3+	One row per user. Every import is a full snapshot: include all users each time.

Column types

Type	Use for	Values
keyword	Categories: department, location, job level, ...	Free text; shown as a filter with one option per distinct value.
numeric	Numbers: tenure in months, salary band, performance rating, ...	Integers or decimals.
date	Dates: hire date, last promotion, ...	YYYY-MM-DD (other unambiguous formats are parsed, but stick to ISO).

An HRIS column keeps the type it had the first time it was imported. Column names are what administrators see in analytics: a column called Business Unit shows up as "Business Unit".

Sample

user,first_name,last_name,manager,Business Unit,Location,Hire Date,Salary Band
email,name,name,email,keyword,keyword,date,numeric
ceo@example.com,Ada,Lovelace,,Executive,London,2019-01-07,9
jane.doe@example.com,Jane,Doe,ceo@example.com,Sales,Berlin,2024-03-01,4
john.roe@example.com,John,Roe,jane.doe@example.com,Sales,Berlin,2025-09-15,3

Download: Users_Teams_And_HRIS_Import_File_Sample.csv.

A file with only the three user columns (and optionally manager) needs no type row:

user,first_name,last_name,manager
jane.doe@example.com,Jane,Doe,ceo@example.com

Delivery 1: upload through the API

POST /users/upload takes the file as the multipart field users and returns immediately; the import runs in the background.

curl -X POST https://api.deepersignals.com/api/external/users/upload \
  -H "X-TOKEN: $DS_API_TOKEN" \
  -F "users=@users_2026-10-01.csv"

{ "message": "Your users will be imported as soon as possible" }

Use it for one-off loads or when your HR system can call our API on a schedule. The file is validated on upload (400 when it is not a CSV or a required column is missing).

Delivery 2: drop the file on SFTP

When your HR system can only export files, Deeper Signals pulls them from an SFTP server on your side. Agree the host, the folder and the polling interval with your Deeper Signals contact; the platform authenticates with its SSH key.

Option	Requirement
File name	hris_YYYY-MM-DD.csv for the full file described above (for example hris_2026-10-01.csv). A users-and-managers-only file may instead be named teams_YYYY-MM-DD.csv.
Which file is used	On every poll the most recent date of each prefix wins and older files are ignored. A file name that was already imported is not imported again, so each export needs a new date.
Content	Identical to the API upload.

Export daily (or at the agreed interval) and leave the previous files in place or remove them; both work.

What happens after the import

1. Users are created or updated; UserCreated webhooks fire for new ones. Users missing from the file are not deleted.
2. The hierarchy is rebuilt from the manager column. Managers must themselves appear in the file or already exist on the account.
3. HRIS attributes are matched to users by e-mail; rows whose e-mail has no user are skipped.
4. The account owner (or the administrator who triggered the import) receives an e-mail when the import finished or failed, with the reason.

Imported attributes appear under Analytics as filters a few minutes after the import.

When to use what

Need	Use
One-off or scheduled bulk load from your own system	API upload
Continuous sync without API work on your side	SFTP
Real-time provisioning from your identity provider	SCIM
Individual users from your own app	POST /user, PATCH /users/{user_id}
Direct HR-system connection (Workday and others)	See Integrations