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

# Create employees in bulk

> Creates 1 to 100 new employees and returns their profiles in input order. The entire batch fails without changes if an email matches an existing current or former employee, is repeated within the batch, or a manager is invalid. Email conflicts return 409. To restore a former employee, use PUT /c/{companyId}/employees/{employeeId}/employment-status with CURRENT. No workspace invitations are sent. Returns 201 for a successful batch. Requires permission to manage employee profiles (`org_chart.manage`).



## OpenAPI

````yaml https://api.gowindmill.com/api/v2/openapi.json post /c/{companyId}/employees/bulk
openapi: 3.1.0
info:
  title: Windmill API
  version: 2.0.0
  description: >-
    Use the Windmill API to integrate your systems, automate workflows, and
    build applications on your organization's data. Authenticate with an API key
    or OAuth access token. Each request uses the authenticated user's
    permissions within the selected workspace.
servers:
  - url: https://api.gowindmill.com/api/v2
security:
  - bearerAuth: []
paths:
  /c/{companyId}/employees/bulk:
    post:
      tags:
        - Employees
      summary: Create employees in bulk
      description: >-
        Creates 1 to 100 new employees and returns their profiles in input
        order. The entire batch fails without changes if an email matches an
        existing current or former employee, is repeated within the batch, or a
        manager is invalid. Email conflicts return 409. To restore a former
        employee, use PUT
        /c/{companyId}/employees/{employeeId}/employment-status with CURRENT. No
        workspace invitations are sent. Returns 201 for a successful batch.
        Requires permission to manage employee profiles (`org_chart.manage`).
      operationId: employees.bulk.create
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 128
            description: >-
              Company ID. A URL slug is also accepted. The caller must have
              access to this company.
            title: Company ID
            example: company-acme
          required: true
          description: >-
            Company ID. A URL slug is also accepted. The caller must have access
            to this company.
          name: companyId
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmployeesRequest'
      responses:
        '201':
          description: New employee profiles in input order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEmployeesResponse'
        '400':
          description: Bad request or request validation failed
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            enum:
                              - BAD_REQUEST
                          message:
                            type: string
                          requestId:
                            type: string
                        required:
                          - code
                          - message
                          - requestId
                    required:
                      - error
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            enum:
                              - VALIDATION_ERROR
                          message:
                            type: string
                          requestId:
                            type: string
                          details:
                            type: array
                            items:
                              type: object
                              properties:
                                path:
                                  type: array
                                  items:
                                    anyOf:
                                      - type: string
                                      - type: number
                                message:
                                  type: string
                              required:
                                - path
                                - message
                        required:
                          - code
                          - message
                          - requestId
                          - details
                    required:
                      - error
        '401':
          description: >-
            Authentication is missing or invalid. Send a valid API key or OAuth
            access token in the Authorization: Bearer <TOKEN> header before
            retrying.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - UNAUTHORIZED
                      message:
                        type: string
                      requestId:
                        type: string
                    required:
                      - code
                      - message
                      - requestId
                required:
                  - error
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - FORBIDDEN
                      message:
                        type: string
                      requestId:
                        type: string
                    required:
                      - code
                      - message
                      - requestId
                required:
                  - error
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - NOT_FOUND
                      message:
                        type: string
                      requestId:
                        type: string
                    required:
                      - code
                      - message
                      - requestId
                required:
                  - error
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - CONFLICT
                      message:
                        type: string
                      requestId:
                        type: string
                    required:
                      - code
                      - message
                      - requestId
                required:
                  - error
        '429':
          description: >-
            The API-client request budget is exhausted. API keys allow 500
            requests per minute per key; OAuth clients allow 500 per minute per
            client and workspace. Reads and writes share the budget. One HTTP
            request counts once, including bulk requests. Wait for the
            Retry-After delay before retrying.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              required: true
              schema:
                type: integer
                minimum: 0
                example: 42
            RateLimit:
              description: >-
                Current request budget: limit is the maximum count, remaining is
                the unused count, and reset is seconds until the window resets,
                not a timestamp.
              required: true
              schema:
                type: string
                example: limit=500, remaining=0, reset=42
            RateLimit-Policy:
              description: >-
                Request limit and window length in seconds, formatted as
                <limit>;w=<seconds>.
              required: true
              schema:
                type: string
                example: 500;w=60
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - RATE_LIMITED
                      message:
                        type: string
                      requestId:
                        type: string
                    required:
                      - code
                      - message
                      - requestId
                required:
                  - error
      security:
        - bearerAuth: []
components:
  schemas:
    CreateEmployeesRequest:
      type: object
      properties:
        employees:
          type: array
          items:
            $ref: '#/components/schemas/CreateEmployeeRequest'
          minItems: 1
          maxItems: 100
          description: Between 1 and 100 new employee requests. The batch is transactional.
          title: Employees
      required:
        - employees
      additionalProperties: false
      title: Create employee batch
      example:
        employees:
          - primaryEmail: avery@example.test
            firstName: Avery
            lastName: Chen
            jobTitle: Engineer
            managerId: employee-morgan
    CreateEmployeesResponse:
      type: object
      properties:
        employees:
          type: array
          items:
            $ref: '#/components/schemas/EmployeeMinView'
          description: New employee profiles in the same order as the submitted entries.
          title: Employees
      required:
        - employees
      additionalProperties: false
      title: Created employee batch response
      example:
        employees:
          - id: employee-avery
            name: Avery Chen
            avatarUrl: null
            jobTitle: Engineer
            managerId: employee-morgan
            primaryEmail: avery@example.test
            phoneNumber: null
            firstName: Avery
            preferredName: null
            lastName: Chen
            isActiveMember: true
    CreateEmployeeRequest:
      anyOf:
        - type: object
          properties:
            primaryEmail:
              type: string
              maxLength: 320
              format: email
              description: >-
                Valid email address for the new employee. Any existing current
                or former employee match returns 409. Takes precedence over the
                deprecated email alias.
              title: Initial employee email
              example: avery@example.test
            email:
              type: string
              maxLength: 320
              format: email
              description: >-
                Deprecated alias for primaryEmail. Supply primaryEmail for new
                integrations.
              title: Legacy initial employee email
              deprecated: true
            firstName:
              type: string
              minLength: 1
              maxLength: 200
              description: Required first name, from 1 to 200 characters.
              title: First name
              example: Avery
            lastName:
              type: string
              minLength: 1
              maxLength: 200
              description: Required last name, from 1 to 200 characters.
              title: Last name
              example: Chen
            jobTitle:
              type:
                - string
                - 'null'
              maxLength: 256
              description: >-
                Job title for the new employee, up to 256 characters. Optional
                and nullable.
              title: Job title
              example: Engineer
            managerId:
              type:
                - string
                - 'null'
              minLength: 1
              maxLength: 128
              description: >-
                A current employee in the same company. Omit or send null for no
                manager.
              title: Manager ID
              example: employee-morgan
          required:
            - primaryEmail
            - firstName
            - lastName
          additionalProperties: false
        - type: object
          properties:
            primaryEmail:
              type: string
              maxLength: 320
              format: email
              description: >-
                Valid email address for the new employee. Any existing current
                or former employee match returns 409. Takes precedence over the
                deprecated email alias.
              title: Initial employee email
              example: avery@example.test
            email:
              type: string
              maxLength: 320
              format: email
              description: >-
                Deprecated alias for primaryEmail. Supply primaryEmail for new
                integrations.
              title: Legacy initial employee email
              deprecated: true
            firstName:
              type: string
              minLength: 1
              maxLength: 200
              description: Required first name, from 1 to 200 characters.
              title: First name
              example: Avery
            lastName:
              type: string
              minLength: 1
              maxLength: 200
              description: Required last name, from 1 to 200 characters.
              title: Last name
              example: Chen
            jobTitle:
              type:
                - string
                - 'null'
              maxLength: 256
              description: >-
                Job title for the new employee, up to 256 characters. Optional
                and nullable.
              title: Job title
              example: Engineer
            managerId:
              type:
                - string
                - 'null'
              minLength: 1
              maxLength: 128
              description: >-
                A current employee in the same company. Omit or send null for no
                manager.
              title: Manager ID
              example: employee-morgan
          required:
            - email
            - firstName
            - lastName
          additionalProperties: false
      title: Create employee request
      example:
        primaryEmail: avery@example.test
        firstName: Avery
        lastName: Chen
        jobTitle: Engineer
        managerId: employee-morgan
    EmployeeMinView:
      type: object
      properties:
        id:
          type: string
          description: >-
            Opaque employee identifier. This identifies an org-chart person, not
            a member or user.
          title: Employee ID
          example: employee-avery
        name:
          type: string
          description: Resolved display name for the employee.
          title: Display name
          example: Avery Chen
        avatarUrl:
          type:
            - string
            - 'null'
          description: Employee avatar URL, or null when no avatar is available.
          title: Avatar URL
        jobTitle:
          type:
            - string
            - 'null'
          description: Employee job title. Null indicates no recorded title.
          title: Job title
          example: Engineer
        managerId:
          type:
            - string
            - 'null'
          description: >-
            Employee ID of the direct manager, or null when no manager is
            assigned.
          title: Manager ID
          example: employee-morgan
        primaryEmail:
          type:
            - string
            - 'null'
          description: Primary employee email address, or null when none is set.
          title: Primary email
          example: avery@example.test
        phoneNumber:
          type:
            - string
            - 'null'
          description: Employee phone number, or null when unavailable.
          title: Phone number
        firstName:
          type:
            - string
            - 'null'
          description: Employee first name, or null when unavailable.
          title: First name
          example: Avery
        preferredName:
          type:
            - string
            - 'null'
          description: Employee preferred first name, or null when unavailable.
          title: Preferred name
        lastName:
          type:
            - string
            - 'null'
          description: Employee last name, or null when unavailable.
          title: Last name
          example: Chen
        isActiveMember:
          type: boolean
          description: Whether the employee has an active linked workspace membership.
          title: Has active workspace access
          example: true
      required:
        - id
        - name
        - avatarUrl
        - jobTitle
        - managerId
        - primaryEmail
        - phoneNumber
        - firstName
        - preferredName
        - lastName
        - isActiveMember
      title: Basic employee profile
      description: >-
        Identity, contact details, and workspace membership for an org-chart
        employee.
      example:
        id: employee-avery
        name: Avery Chen
        avatarUrl: null
        jobTitle: Engineer
        managerId: employee-morgan
        primaryEmail: avery@example.test
        phoneNumber: null
        firstName: Avery
        preferredName: null
        lastName: Chen
        isActiveMember: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Use an API key or OAuth access token. Enter only the token in the
        authorization dialog; requests send it as `Authorization: Bearer
        <TOKEN>`.


        Create an API key in your workspace's **Settings → API keys**. Keys
        start with `wm_api_` and only work in the workspace where they were
        created. Read-only keys can read data; creating, updating, or deleting
        data requires a read-write key.


        ```http

        Authorization: Bearer wm_api_example

        ```


        OAuth access tokens are issued for connected Windmill applications.


        ```http

        Authorization: Bearer <OAUTH_ACCESS_TOKEN>

        ```


        Both token types use the authenticated user's workspace permissions.
        Each endpoint's permission requirements and the sharing settings of the
        requested items still apply.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.