---
title: "Add new individuals to a sandbox company"
method: POST
path: "/sandbox/directory"
tags: ["Sandbox"]
---

# Add new individuals to a sandbox company

`POST /sandbox/directory`

## Request body

- IndividualOrEmployment[] — Array of individuals to create. Takes all combined fields from `/individual` and `/employment` endpoints. All fields are optional.
  - `first_name` string, nullable — The legal first name of the individual.
  - `middle_name` string, nullable — The legal middle name of the individual.
  - `last_name` string, nullable — The legal last name of the individual.
  - `preferred_name` string, nullable — The preferred name of the individual.
  - `emails` object[], nullable
    - `data` string
    - `type` 'work' | 'personal' | 'null', nullable
  - `phone_numbers` object[], nullable
    - `data` string, nullable
    - `type` 'work' | 'personal' | 'null', nullable
  - `gender` 'female' | 'male' | 'other' | 'decline_to_specify' | 'null', nullable — The gender of the individual.
  - `ethnicity` 'asian' | 'white' | 'black_or_african_american' | 'native_hawaiian_or_pacific_islander' | 'american_indian_or_alaska_native' | 'hispanic_or_latino' | 'two_or_more_races' | 'decline_to_specify' | 'null', nullable — The EEOC-defined ethnicity of the individual.
  - `marital_status` 'single' | 'married' | 'divorced' | 'widowed' | 'domestic_partner' | 'unknown' | 'null', nullable — The employee's marital status, used for beneficiary designation and spousal consent workflows.
  - `dob` string, nullable
  - `ssn` string, nullable — Social Security Number of the individual. This field is only available with the `ssn` scope enabled and the `options: { include: ['ssn'] }` param set in the body. [Click here to learn more about enabling the SSN field](/developer-resources/Enable-SSN-Field).
  - `encrypted_ssn` string, nullable — Social Security Number of the individual in **encrypted** format. This field is only available with the `ssn` scope enabled and the `options: { include: ['ssn'] }` param set in the body.
  - `residence` Location, nullable
    - `line1` string, nullable, required — Street address or PO box.
    - `line2` string, nullable, required — Apartment, suite, unit, or building.
    - `city` string, nullable, required — City, district, suburb, town, or village.
    - `state` string, nullable, required — The state code.
    - `postal_code` string, nullable, required — The postal code or zip code.
    - `country` string, nullable, required — The 2-letter ISO 3166 country code.
    - `name` string, nullable
    - `source_id` string, nullable
  - `title` string, nullable — The current title of the individual.
  - `manager` object, nullable — The manager object representing the manager of the individual within the org.
    - `id` string, uuid — A stable Finch `id` (UUID v4) for an individual in the company.
  - `department` object, nullable — The department object.
    - `name` string, nullable — The name of the department associated with the individual.
  - `employment` object, nullable — The employment object.
    - `type` 'employee' | 'contractor' | 'null', nullable — The main employment type of the individual.
    - `subtype` 'full_time' | 'intern' | 'part_time' | 'temp' | 'seasonal' | 'individual_contractor' | 'null', nullable — The secondary employment type of the individual. Options: `full_time`, `part_time`, `intern`, `temp`, `seasonal` and `individual_contractor`.
  - `start_date` string, nullable
  - `end_date` string, nullable
  - `latest_rehire_date` string, nullable
  - `is_active` boolean, nullable — `true` if the individual an an active employee or contractor at the company.
  - `employment_status` 'active' | 'deceased' | 'leave' | 'onboarding' | 'prehire' | 'retired' | 'terminated' | 'null', nullable — The detailed employment status of the individual.
  - `flsa_status` 'exempt' | 'non_exempt' | 'unknown' | 'null', nullable — The FLSA status of the individual. Available options: `exempt`, `non_exempt`, `unknown`.
  - `class_code` string, nullable — Worker's compensation classification code for this employee
  - `location` Location, nullable
    - `line1` string, nullable, required — Street address or PO box.
    - `line2` string, nullable, required — Apartment, suite, unit, or building.
    - `city` string, nullable, required — City, district, suburb, town, or village.
    - `state` string, nullable, required — The state code.
    - `postal_code` string, nullable, required — The postal code or zip code.
    - `country` string, nullable, required — The 2-letter ISO 3166 country code.
    - `name` string, nullable
    - `source_id` string, nullable
  - `income` Income, nullable — The employee's income as reported by the provider. This may not always be annualized income, but may be in units of bi-weekly, semi-monthly, daily, etc, depending on what information the provider returns.
    - `unit` 'yearly' | 'quarterly' | 'monthly' | 'semi_monthly' | 'bi_weekly' | 'weekly' | 'daily' | 'hourly' | 'fixed' | 'null', nullable, required — The income unit of payment. Options: `yearly`, `quarterly`, `monthly`, `semi_monthly`, `bi_weekly`, `weekly`, `daily`, `hourly`, and `fixed`.
    - `amount` integer, nullable, required — The income amount in cents.
    - `currency` string, nullable, required — The currency code.
    - `effective_date` string, date, nullable, required — The date the income amount went into effect.
  - `income_history` Income[], nullable — The array of income history.
    - `unit` 'yearly' | 'quarterly' | 'monthly' | 'semi_monthly' | 'bi_weekly' | 'weekly' | 'daily' | 'hourly' | 'fixed' | 'null', nullable, required — The income unit of payment. Options: `yearly`, `quarterly`, `monthly`, `semi_monthly`, `bi_weekly`, `weekly`, `daily`, `hourly`, and `fixed`.
    - `amount` integer, nullable, required — The income amount in cents.
    - `currency` string, nullable, required — The currency code.
    - `effective_date` string, date, nullable, required — The date the income amount went into effect.
  - `custom_fields` object[], nullable — Custom fields for the individual. These are fields which are defined by the employer in the system. Custom fields are not currently supported for assisted connections.
    - `name` string, nullable
    - `value` union
      - string
      - object
      - number
      - boolean
  - `union_code` string, nullable — The code identifying the union the employee is a member of, as configured in the payroll system.
  - `union_local` string, nullable — The local chapter or local number within the employee's union.
  - `highly_compensated_employee` boolean, nullable — IRS flag indicating whether the employee is classified as a Highly Compensated Employee for nondiscrimination testing purposes (ADP/ACP tests). US-only.
  - `key_employee` boolean, nullable — IRS flag indicating whether the employee is classified as a Key Employee for top-heavy testing purposes. US-only.
  - `source_id` string, nullable — The source system's unique employment identifier for this individual

## Response `200`

OK

- object[] — The individuals which were created

---

[API](https://skmtc.net/finch-api/apis/api-reference.md) · [All operations](https://skmtc.net/finch-api/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/finch-api/api-reference/revisions/f1cca2cb0ef2/schema)