Bulk imports require the "Add employees" admin permission. Imports are scoped to the admin's groups — rows for employees outside that scope are skipped with an explanation, and rows with missing required information are flagged for review before the import runs.
Building your directory
Before importing employees, Shapes can build your account's structure for you from a spreadsheet you already use. This step only sets up your fields — no employee data is imported yet. You'll import your people afterwards, in a separate step.
Step 1: Go to your account settings and open Employee Fields.
Step 2: Click Build your directory in the top-right corner.
Step 3: Drop an .xlsx or .csv file from any HR system into the upload area, or click it to browse. To pull your data straight from your HR system instead, select BambooHR or HiBob under Or import from, then click Create.
You can also add a note with your file before it starts, for example "keep compensation in its own tab" or "the headers are in Hebrew". The proposal follows your note.
Step 4: On the Your data is ready screen, check the number of fields found and click Create. To use a different file, click the trash icon and start over.
Step 5: Wait while Shapes reads your file, compares it with the fields you already have, and groups the columns into sections. This takes about a minute. Columns are matched by meaning rather than exact spelling, and repeating records are detected and built as tables.
Step 6: Review the draft. A Your setup is ready for review banner appears at the top. To find what was added:
A blue dot next to a tab's name means that tab contains new fields.
Inside the tab, each added field is tagged New field.
Added sections have a dashed outline and are tagged New section.
For single-select and multi-select fields, Shapes also creates the list of options from the values in your file, so you don't have to type them in.
Click View field summary to open the All fields changes panel. It shows how many New fields were created and how many Matched fields were linked to fields you already have, so nothing is duplicated, and lists each new field with its field type.
Step 7: Make any changes before approving. While the setup is still a draft, you can:
Click a field's name to rename it. Edited fields are tagged Changed.
Delete any proposed field you don't want.
Change a field's type. This only works between compatible types — for example, Text to Long text — not from any type to any other.
Use Add Field to add a field to a section, or Create section to add a new section.
Ask the assistant for changes in plain language, for example "Create a new tab with two sections in it". See Refining the draft with the assistant.
Want only part of the proposal? Delete the fields you don't need while the setup is still a draft, then approve the rest. This is easier than approving everything and deleting fields from your account afterwards.
Step 8: Click Approve to save the structure, or Discard to throw the draft away. Nothing is written to your account until you approve. Once approved, a confirmation message shows that your fields and changes have been saved.
Refining the draft with the assistant
An assistant sits next to the draft. Describe a change in plain language and the draft updates in place. For example:
"Rename Department to Team"
"Move Laptop into Equipment"
"Add the usual US documents"
"Create a new tab with two sections in it"
Your manual edits are kept. The assistant reads the draft fresh each time it replies and never undoes changes you made yourself.
After each request, the assistant replies with a short summary of what it added, how many columns it matched, and what to double-check. Nothing is written to your account until you click Approve.
Planning your fields first still pays off, even with an AI-assisted proposal to review. See Planning Your Employee Field Architecture in Shapes for what to consider before approving the draft.
Importing from HiBob
When you select HiBob under Or import from, Shapes reads your data through a HiBob API service user. Shapes can only see the fields that service user's permission group can access. If a data category is hidden from that group, Build your directory won't create the matching fields, and the import will then skip that data or map it to the wrong field.
The permissions for importing people data are different from the ones for importing employee files. To import people data, the service user needs access to all of your employees' personal fields, not just basic details.
Step 1: In HiBob, go to Service Users and create or select a service user. Copy its ID and token.
Step 2: Go to System Settings → Permission groups, create a group (for example, API – People Data), and add the service user to it.
Step 3: In the group, open People's data and grant access to every category you want to bring into Shapes, including Personal and Personal contact details. These hold fields such as Age.
Sensitive fields in HiBob need one more permission
For sensitive fields, such as Date of birth (with the year) and SSN, HiBob only shares the data when the service user has both View and Edit on that field. View alone isn't enough, and HiBob doesn't show an error; it just leaves the field out. For each sensitive field you want to import:
In HiBob, open the service user's permission group.
Go to People's data → People's fields and find the field (for example, Personal → Date of birth).
Turn on Edit next to View.
Step 4: To import past employees as well, go to Access data for, choose Select people by condition, and set the lifecycle status condition to include both Employed and Terminated.
Step 5: In Shapes, go to Employee Fields and click Build your directory. Select HiBob and follow the steps above to review and approve the fields.
Step 6: Start the import. Review the proposed mapping carefully before you run it. Auto-mapping can pair fields that look similar but hold different kinds of data, like a HiBob text field mapped to a Shapes number field. To fix a wrong mapping, unmap the column from its current field first, then select the correct one. If a HiBob field has no matching field in Shapes, use Create a field on the mapping screen to add it without leaving the import.
If you already ran Build your directory before fixing permissions: update the permission group, then run Build your directory again. It adds the fields that were missing, without duplicating the ones you already have. Then re-run the import.
Importing employees
Once your fields are in place, import your employee spreadsheet. You can use the same import to add new employees, update existing ones, or both. To start, go to the People Directory, click the three dots next to Add Employee, and select Import.
Required columns
New employees: First Name, Last Name and Email Address.
Updating existing employees: Email Address only — it's used to match each row to the right person.
Role or compensation data: a date column that shows when each value took effect, such as Start Date or Effective Date. See Importing salary and job history.
If your file updates existing employees but also includes people who aren't in Shapes yet, add First Name and Last Name columns to the spreadsheet — without them, those new people can't be created.
Step 1: Upload your employee file. An agent maps each column to one of your fields — review the proposed mapping and adjust it if needed. If a column has no matching field, select Create a field to add it right from the mapping screen, without leaving the import.
Step 2: If your file includes role or compensation columns, choose which column holds the effective date. Shapes suggests every date column in your file. If each employee has only one row, their Start Date works. If an employee has several history rows, choose a column with the date each change took effect — using the same date on all of an employee's rows is flagged as an error. If your file has no date column, add one to the spreadsheet and upload it again.
Step 3: Review the matches. Each row is checked against your existing people, and for anything that would change on an existing employee, you'll see the current value alongside the incoming one. Employees who are already in Shapes — for example, people you've already invited — are recognized and updated, not created a second time.
Step 4: If you're importing into a table that already holds data, such as Bonus or Equity, choose whether to replace the existing rows or add the new rows alongside them.
Step 5: For fields that track history, such as compensation, choose to bring in the full history rather than just the latest value.
Step 6: Fix any errors, which are surfaced per row inside the import wizard, then run the import. You can correct most issues in place, without leaving the import to edit your file. A handful of bad rows won't block the rest of the file from importing — but a row missing its required columns won't be imported (for new employees) or updated (for existing ones).
Exporting errors and warnings
Instead of working through issues one by one in the wizard, you can export every error and warning as a CSV or Excel file. Each row in the export covers one issue: the employee's email, the row and column it came from, the problematic value, whether it's an error or a warning, and a description of the problem. Correct the issues offline, then re-upload.
Importing salary and job history
To upload historical compensation and role data, use the sample templates attached at the bottom of this article: Employee Data, Compensation History and Role History.
Each history template includes an Effective Date column, which tells Shapes when a change took effect so your history stays accurate:
The first role for each employee should use their start date as the effective date.
For every later salary or role change, enter the date that change took effect on its own row.
If there are no past changes to record, add a single row per employee.
Make sure every row has an effective date. Shapes no longer fills in today's date when one is missing, so a file without a date column can't continue past the effective date step.
Viewing past imports and undoing one
Every import is logged in Import History, along with who ran it and when — see Import History and Undoing an Import for how to view that log and undo an import if needed.