> ## Documentation Index
> Fetch the complete documentation index at: https://developer.tryfinch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add new individuals to a sandbox company

<Warning>
  Note that requests using the SDK will require a JSON object with a key of `body` and a value of an array of individuals.

  ```
  // JavaScript example
  await client.sandbox.directory.create({
    body: [
      // list of individual objects
    ]
  })
  ```
</Warning>


## OpenAPI

````yaml post /sandbox/directory
openapi: 3.1.0
info:
  title: API Reference
  version: '2020-09-17'
  contact: {}
  description: >-
    The Finch HRIS API provides a unified way to connect to a multitide of HRIS
    systems. The API requires an access token issued by Finch.


    By default, Organization and Payroll requests use Finch's [Data
    Syncs](/developer-resources/Data-Syncs). If a request is made before the
    initial sync has completed, Finch will request data live from the provider.
    The latency on live requests may range from seconds to minutes depending on
    the provider and batch size.

    For automated integrations, Deductions requests (both read and write) are
    always made live to the provider. Latencies may range from seconds to
    minutes depending on the provider and batch size.



    Employer products are specified by the product parameter, a space-separated
    list of products that your application requests from an employer
    authenticating through Finch Connect. Valid product names are—

    - `company`: Read basic company data


    - `directory`: Read company directory and organization structure


    - `individual`: Read individual data, excluding income and employment data


    - `employment`: Read individual employment and income data


    - `payment`: Read payroll and contractor related payments by the company


    - `pay_statement`: Read detailed pay statements for each individual


    - `benefits`: Create and manage deductions and contributions and enrollment
    for an employer


    [![Open in
    Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/21027137-08db0929-883d-4094-a9ce-dbf5a9bee4a4?action=collection%2Ffork&collection-url=entityId%3D21027137-08db0929-883d-4094-a9ce-dbf5a9bee4a4%26entityType%3Dcollection%26workspaceId%3D1edf19bc-e0a8-41e9-ac55-481a4b50790b)
servers:
  - url: https://api.tryfinch.com
    description: ''
security: []
tags:
  - name: Organization
  - name: Payroll
  - name: Deductions
  - name: Management
  - name: Sandbox
paths:
  /sandbox/directory:
    post:
      tags:
        - Sandbox
      summary: Add new individuals to a sandbox company
      operationId: post-sandbox-directory
      requestBody:
        content:
          application/json:
            schema:
              type: array
              description: >-
                Array of individuals to create. Takes all combined fields from
                `/individual` and `/employment` endpoints. All fields are
                optional.
              items:
                allOf:
                  - $ref: '#/components/schemas/IndividualWithoutId'
                  - $ref: '#/components/schemas/EmploymentWithoutId'
            examples:
              Example 1:
                value:
                  - first_name: John
                    last_name: Smith
                    dob: 01/01/2000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                description: The individuals which were created
                items:
                  type: object
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Finch from '@tryfinch/finch-api';

            const client = new Finch({
              accessToken: 'My Access Token',
            });

            const directories = await client.sandbox.directory.create();

            console.log(directories);
        - lang: Python
          source: |-
            from finch import Finch

            client = Finch(
                access_token="My Access Token",
            )
            directories = client.sandbox.directory.create()
            print(directories)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/Finch-API/finch-api-go\"\n\t\"github.com/Finch-API/finch-api-go/option\"\n)\n\nfunc main() {\n\tclient := finchgo.NewClient(\n\t\toption.WithAccessToken(\"My Access Token\"),\n\t)\n\tdirectories, err := client.Sandbox.Directory.New(context.TODO(), finchgo.SandboxDirectoryNewParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", directories)\n}\n"
        - lang: Java
          source: |-
            package com.tryfinch.api.example;

            import com.tryfinch.api.client.FinchClient;
            import com.tryfinch.api.client.okhttp.FinchOkHttpClient;
            import com.tryfinch.api.models.DirectoryCreateResponse;
            import com.tryfinch.api.models.SandboxDirectoryCreateParams;

            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    FinchClient client = FinchOkHttpClient.builder()
                        .fromEnv()
                        .accessToken("My Access Token")
                        .build();

                    List<DirectoryCreateResponse> directories = client.sandbox().directory().create();
                }
            }
        - lang: Kotlin
          source: |-
            package com.tryfinch.api.example

            import com.tryfinch.api.client.FinchClient
            import com.tryfinch.api.client.okhttp.FinchOkHttpClient
            import com.tryfinch.api.models.DirectoryCreateResponse
            import com.tryfinch.api.models.SandboxDirectoryCreateParams

            fun main() {
                val client: FinchClient = FinchOkHttpClient.builder()
                    .fromEnv()
                    .accessToken("My Access Token")
                    .build()

                val directories: List<DirectoryCreateResponse> = client.sandbox().directory().create()
            }
        - lang: Ruby
          source: |-
            require "finch_api"

            finch = FinchAPI::Client.new(access_token: "My Access Token")

            directories = finch.sandbox.directory.create

            puts(directories)
components:
  schemas:
    IndividualWithoutId:
      type: object
      properties:
        first_name:
          type: string
          description: The legal first name of the individual.
          nullable: true
        middle_name:
          type: string
          description: The legal middle name of the individual.
          nullable: true
        last_name:
          type: string
          description: The legal last name of the individual.
          nullable: true
        preferred_name:
          type: string
          description: The preferred name of the individual.
          nullable: true
        emails:
          type: array
          nullable: true
          items:
            type: object
            properties:
              data:
                type: string
              type:
                type: string
                enum:
                  - work
                  - personal
                  - null
                nullable: true
        phone_numbers:
          type: array
          nullable: true
          items:
            type: object
            nullable: true
            properties:
              data:
                type: string
                nullable: true
              type:
                type: string
                enum:
                  - work
                  - personal
                  - null
                nullable: true
        gender:
          type: string
          description: The gender of the individual.
          enum:
            - female
            - male
            - other
            - decline_to_specify
            - null
          nullable: true
        ethnicity:
          type: string
          enum:
            - 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
          description: The EEOC-defined ethnicity of the individual.
          nullable: true
        dob:
          $ref: '#/components/schemas/Date'
          nullable: true
        ssn:
          type: string
          description: >-
            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).
          nullable: true
        encrypted_ssn:
          type: string
          description: >-
            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.
          nullable: true
        residence:
          $ref: '#/components/schemas/Location'
    EmploymentWithoutId:
      type: object
      properties:
        first_name:
          type: string
          description: The legal first name of the individual.
          nullable: true
        middle_name:
          type: string
          description: The legal middle name of the individual.
          nullable: true
        last_name:
          type: string
          description: The legal last name of the individual.
          nullable: true
        title:
          type: string
          description: The current title of the individual.
          nullable: true
        manager:
          type: object
          description: >-
            The manager object representing the manager of the individual within
            the org.
          nullable: true
          properties:
            id:
              type: string
              description: A stable Finch `id` (UUID v4) for an individual in the company.
              pattern: '[0-9a-fA-F]{8}[-]?(?:[0-9a-fA-F]{4}[-]?){3}[0-9a-fA-F]{12}'
              format: uuid
        department:
          type: object
          description: The department object.
          nullable: true
          properties:
            name:
              type: string
              description: The name of the department associated with the individual.
              nullable: true
        employment:
          type: object
          description: The employment object.
          nullable: true
          properties:
            type:
              type: string
              description: The main employment type of the individual.
              enum:
                - employee
                - contractor
                - null
              nullable: true
            subtype:
              type: string
              description: >-
                The secondary employment type of the individual. Options:
                `full_time`, `part_time`, `intern`, `temp`, `seasonal` and
                `individual_contractor`.
              enum:
                - full_time
                - intern
                - part_time
                - temp
                - seasonal
                - individual_contractor
                - null
              nullable: true
        start_date:
          $ref: '#/components/schemas/Date'
        end_date:
          $ref: '#/components/schemas/Date'
        latest_rehire_date:
          $ref: '#/components/schemas/Date'
        is_active:
          type: boolean
          description: >-
            `true` if the individual an an active employee or contractor at the
            company.
          nullable: true
        employment_status:
          type: string
          description: The detailed employment status of the individual.
          enum:
            - active
            - deceased
            - leave
            - onboarding
            - prehire
            - retired
            - terminated
            - null
          nullable: true
        flsa_status:
          type: string
          description: >-
            The FLSA status of the individual. Available options: `exempt`,
            `non_exempt`, `unknown`.
          enum:
            - exempt
            - non_exempt
            - unknown
            - null
          nullable: true
        class_code:
          type: string
          description: Worker's compensation classification code for this employee
          nullable: true
        location:
          $ref: '#/components/schemas/Location'
        income:
          $ref: '#/components/schemas/Income'
        income_history:
          type: array
          description: The array of income history.
          nullable: true
          items:
            $ref: '#/components/schemas/Income'
        custom_fields:
          type: array
          nullable: true
          description: >-
            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.
          items:
            type: object
            properties:
              name:
                type: string
                nullable: true
              value:
                type:
                  - string
                  - array
                  - object
                  - number
                  - boolean
                  - 'null'
                nullable: true
        source_id:
          type: string
          nullable: true
          description: The source system's unique employment identifier for this individual
    Date:
      type: string
      title: Date
      nullable: true
      pattern: (\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]))
    Location:
      type: object
      nullable: true
      properties:
        line1:
          type: string
          nullable: true
          description: Street address or PO box.
        line2:
          type: string
          nullable: true
          description: Apartment, suite, unit, or building.
        city:
          type: string
          nullable: true
          description: City, district, suburb, town, or village.
        state:
          type: string
          nullable: true
          description: The state code.
        postal_code:
          type: string
          nullable: true
          description: The postal code or zip code.
        country:
          type: string
          nullable: true
          description: The 2-letter ISO 3166 country code.
        name:
          type: string
          nullable: true
        source_id:
          type: string
          nullable: true
      required:
        - line1
        - line2
        - city
        - state
        - postal_code
        - country
      description: ''
      title: Location
      x-tags:
        - Models
    Income:
      type: object
      nullable: true
      properties:
        unit:
          type: string
          nullable: true
          enum:
            - yearly
            - quarterly
            - monthly
            - semi_monthly
            - bi_weekly
            - weekly
            - daily
            - hourly
            - fixed
            - null
          description: >-
            The income unit of payment. Options: `yearly`, `quarterly`,
            `monthly`, `semi_monthly`, `bi_weekly`, `weekly`, `daily`, `hourly`,
            and `fixed`.
        amount:
          type: integer
          nullable: true
          description: The income amount in cents.
        currency:
          type: string
          nullable: true
          description: The currency code.
        effective_date:
          type: string
          nullable: true
          format: date
          description: The date the income amount went into effect.
      required:
        - unit
        - amount
        - currency
        - effective_date
      description: >-
        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.
      title: Income
      x-tags:
        - Models
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Please use your Access Token

````