> ## 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 an employee

> Creates a new org-chart employee without inviting them to the workspace. An email matching any existing employee, including a former employee, returns 409 without changing the record. To restore a former employee, use PUT /c/{companyId}/employees/{employeeId}/employment-status with CURRENT. A supplied manager must be a current employee in the same company. Returns 201. Requires permission to manage employee profiles (`org_chart.manage`).



## OpenAPI

````yaml https://api.gowindmill.com/api/v2/openapi.json post /c/{companyId}/employees
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:
    post:
      tags:
        - Employees
      summary: Create an employee
      description: >-
        Creates a new org-chart employee without inviting them to the workspace.
        An email matching any existing employee, including a former employee,
        returns 409 without changing the record. To restore a former employee,
        use PUT /c/{companyId}/employees/{employeeId}/employment-status with
        CURRENT. A supplied manager must be a current employee in the same
        company. Returns 201. Requires permission to manage employee profiles
        (`org_chart.manage`).
      operationId: employees.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/CreateEmployeeRequest'
      responses:
        '201':
          description: New employee profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEmployeeResponse'
        '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:
    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
    CreateEmployeeResponse:
      type: object
      properties:
        employee:
          $ref: '#/components/schemas/EmployeeView'
      required:
        - employee
      additionalProperties: false
      title: Created employee response
      example:
        employee:
          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
          startDate: '2025-03-17'
          timezone: America/New_York
          employmentStatus: CURRENT
          emails:
            - avery@example.test
          directReportsCount: 0
          directReportMembersCount: 0
          manager:
            id: employee-morgan
            name: Morgan Reed
            avatarUrl: null
            jobTitle: Engineering Manager
            managerId: null
            primaryEmail: morgan@example.test
            phoneNumber: null
            firstName: Morgan
            preferredName: null
            lastName: Reed
            isActiveMember: true
    EmployeeView:
      allOf:
        - $ref: '#/components/schemas/EmployeeMinView'
        - type: object
          properties:
            startDate:
              type:
                - string
                - 'null'
              description: Employee start date as YYYY-MM-DD, or null when unavailable.
              title: Start date
              example: '2025-03-17'
            timezone:
              type:
                - string
                - 'null'
              description: Resolved IANA timezone name, or null when unavailable.
              title: Timezone
              example: America/New_York
            employmentStatus:
              type: string
              enum:
                - CURRENT
                - FORMER
              description: >-
                CURRENT means the employee is not archived; FORMER means
                archived. Employment status is separate from member access.
              title: Employment status
              example: CURRENT
            emails:
              type: array
              items:
                type: string
              description: Known email addresses associated with the employee.
              title: Known email addresses
              example:
                - avery@example.test
            directReportsCount:
              type: number
              description: >-
                Direct reports in the primary organization. Former reports are
                included only when the caller requests archived-report counts.
              title: Direct report count
              example: 0
            directReportMembersCount:
              type: number
              description: >-
                Direct reports in the primary organization with active workspace
                memberships, independent of employee archive status.
              title: Direct report member count
              example: 0
            manager:
              allOf:
                - $ref: '#/components/schemas/EmployeeMinView'
                - type:
                    - object
                    - 'null'
                  title: Direct manager
                  description: >-
                    Basic profile of the direct manager, or null when none is
                    assigned.
          required:
            - startDate
            - timezone
            - employmentStatus
            - emails
            - directReportsCount
            - directReportMembersCount
            - manager
      title: Employee
      description: Employee profile returned by this operation.
      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
        startDate: '2025-03-17'
        timezone: America/New_York
        employmentStatus: CURRENT
        emails:
          - avery@example.test
        directReportsCount: 0
        directReportMembersCount: 0
        manager:
          id: employee-morgan
          name: Morgan Reed
          avatarUrl: null
          jobTitle: Engineering Manager
          managerId: null
          primaryEmail: morgan@example.test
          phoneNumber: null
          firstName: Morgan
          preferredName: null
          lastName: Reed
          isActiveMember: true
    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.