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. Each system needs a short setup first — see Importing from BambooHR or Importing from HiBob.
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 BambooHR
When you select BambooHR under Or import from, Shapes connects using a BambooHR API key and your company's BambooHR subdomain. An API key has the same access as the BambooHR user who created it, so Shapes can only see the employees and fields that user can see. If the key belongs to someone with limited access, the connection still works and no error appears, but Build your directory creates fewer fields and the import brings in fewer employees.
Who should create the API key?
We recommend that a BambooHR Account Owner creates the key, so Shapes can see all of your employees and fields. If that isn't possible, give the person who will create the key a custom access level first. See Using a custom access level in BambooHR.
Step 1: In BambooHR, click your profile picture in the bottom-left corner and select API Keys.
Step 2: Click Add New Key.
Step 3: Give the key a name, for example Shapes. The name is only for your own reference. Click Copy Key right away and keep the key somewhere safe until you paste it into Shapes, then click Done.
Step 4: Find your subdomain. It's the part of your BambooHR web address before .bamboohr.com. For example, if you sign in at https://acme.bamboohr.com, your subdomain is acme.
Step 5: In Shapes, go to Employee Fields and click Build your directory. Select BambooHR, enter your subdomain and API key, and follow the steps above to review and approve the fields. Enter the subdomain on its own, without https:// or .bamboohr.com, and make sure there are no extra spaces before or after the key.
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. To fix a wrong mapping, unmap the column from its current field first, then select the correct one. If a BambooHR field has no matching field in Shapes, use Create a field on the mapping screen to add it without leaving the import.
Using a custom access level in BambooHR
If an Account Owner can't create the key, set up a custom access level for the person who will create it, before they create it.
In BambooHR, click Settings (⚙️) in the top-right corner, then select Access Levels in the left menu.
Click the + next to Levels and select Custom Access Level. Enter a name and description, then click Next Step.
Under What can people with this access level do?, scroll to the Settings section and select Company Field Settings. Without it, company-level fields such as Division and Department aren't shared. Click Next Step.
Under What this access level can see, go to See about other employees and select View Only for the information you want to bring into Shapes.
If you use custom tables, open the section where each table lives (for example, Personal or Job) and grant access to every table you want to import.
Save the access level, click Add Employee, select the person who will create the API key, and click Done.
Already have a custom access level? Open it under Access Levels, check that it includes the permissions in steps 3–5, and make sure the person creating the key is assigned to it.
Troubleshooting the BambooHR connection
The connection fails right away: check that you entered only the subdomain (for example, acme), not the full address, and that the API key has no spaces before or after it. Entering a wrong key several times can make BambooHR temporarily block API access for your account, so correct the key and wait before trying again.
Employees or fields are missing: the access level behind the key doesn't cover them. Have an Account Owner create a new key, or widen the custom access level and create a new key. 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.
The connection stopped working: deleting the key in BambooHR, or removing its creator's access, disconnects Shapes. Create a new key and connect again.
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 System Settings → Integrations and click Manage on the Service users tile. Click Create service user, enter any display name, and click Create. HiBob then shows the new service user's ID and Token. Copy both and keep them somewhere safe, then click Go to permission groups.
Step 2: Click Create permission group and choose Service user. Enter a group name (for example, API – People Data), select your new service user under Select service users, and click Create. When asked to confirm, click Confirm.
Step 3: Choose whose data the service user can access. In the group's People's data tab, click Access data for, then Edit permissions in the top-right corner. Under Whose data can members access?, choose Select people by condition and click Edit. Select every lifecycle status you want to import — usually Hired, Employed and Terminated — then click Apply twice. Hired covers people who have signed but haven't started yet, and Terminated covers past employees.
Step 4: Still in People's data, grant access to every category you want to bring into Shapes. For each category, turn on both permissions:
View selected employees' [category] sections — the current values.
View selected employees' [category] section histories — the past values. Without this, Shapes can only import the latest value, not the full compensation or role history.
Basic Info is required, because it holds employee names. Also include Personal and Personal contact details, which hold fields such as Age, plus any other category you need, such as Employment, Work, Lifecycle or Payroll. When you're done, click Save and Apply.
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. Shapes only reads this data and never edits it in HiBob. 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 5: In Shapes, go to Employee Fields and click Build your directory. Select HiBob, enter the service user's ID and token, 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.
If a field is still missing: HiBob lets admins move fields into different categories, so a field may not be in the category you expect. Open a sample employee in HiBob, check which category the field sits in (for example, Personal, Work or About), and grant access to that category as in Step 4, plus Edit if it's a sensitive field. Then run Build your directory again and 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.