> ## 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.

# Update an employee profile

> Updates the supplied fields and returns the employee profile. Omitted fields keep their values; nullable fields accept null to clear them. Supply at least one field. primaryEmail must already be linked to the employee. Managers must belong to the company; an employee cannot become their own manager, directly or through their reporting chain. Value changes keep field ownership unchanged unless the field keys are included in claimOwnership. Include an integration-owned field in claimOwnership to switch it to manual ownership, or set its source to manual through PUT /c/{companyId}/employees/{employeeId}/field-sources/{fieldKey}. Ownership claims also work without value changes. The response omits some editable fields, including jobLevel, gender, and pronouns. Use PUT /c/{companyId}/employees/{employeeId}/employment-status to archive or restore an employee. Requires permission to manage employee profiles (`org_chart.manage`).



## OpenAPI

````yaml https://api.gowindmill.com/api/v2/openapi.json patch /c/{companyId}/employees/{employeeId}
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/{employeeId}:
    patch:
      tags:
        - Employees
      summary: Update an employee profile
      description: >-
        Updates the supplied fields and returns the employee profile. Omitted
        fields keep their values; nullable fields accept null to clear them.
        Supply at least one field. primaryEmail must already be linked to the
        employee. Managers must belong to the company; an employee cannot become
        their own manager, directly or through their reporting chain. Value
        changes keep field ownership unchanged unless the field keys are
        included in claimOwnership. Include an integration-owned field in
        claimOwnership to switch it to manual ownership, or set its source to
        manual through PUT
        /c/{companyId}/employees/{employeeId}/field-sources/{fieldKey}.
        Ownership claims also work without value changes. The response omits
        some editable fields, including jobLevel, gender, and pronouns. Use PUT
        /c/{companyId}/employees/{employeeId}/employment-status to archive or
        restore an employee. Requires permission to manage employee profiles
        (`org_chart.manage`).
      operationId: employees.update
      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
        - schema:
            type: string
            minLength: 1
            maxLength: 128
            description: >-
              Opaque employee ID in the company. This identifies an org-chart
              person, not a member or user.
            title: Employee ID
            example: employee-avery
          required: true
          description: >-
            Opaque employee ID in the company. This identifies an org-chart
            person, not a member or user.
          name: employeeId
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeePatch'
      responses:
        '200':
          description: Extended employee profile after the patch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateEmployeeResponse'
        '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
        '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:
    EmployeePatch:
      type: object
      properties:
        firstName:
          type: string
          maxLength: 200
          description: >-
            New first name, up to 200 characters. Omit to retain it; an empty
            string is accepted.
          title: First name
          example: Avery
        lastName:
          type: string
          maxLength: 200
          description: >-
            New last name, up to 200 characters. Omit to retain it; an empty
            string is accepted.
          title: Last name
          example: Chen
        displayFullName:
          type: string
          maxLength: 400
          description: >-
            Display name to use for this employee. Omit it to retain the
            existing value.
          title: Display name
          example: Avery Chen
        jobTitle:
          type:
            - string
            - 'null'
          maxLength: 256
          description: >-
            New job title, up to 256 characters. Omit to retain it or send null
            to clear it.
          title: Job title
          example: Senior Engineer
        jobLevel:
          type:
            - string
            - 'null'
          maxLength: 256
          description: >-
            New job level, up to 256 characters. Omit to retain it or send null
            to clear it. Not included in this route's returned profile.
          title: Job level
          example: L3
        managerId:
          type:
            - string
            - 'null'
          minLength: 1
          maxLength: 128
          description: >-
            New manager employee ID in the company. Omit to retain it or send
            null to remove the manager.
          title: Manager ID
          example: employee-morgan
        primaryEmail:
          type:
            - string
            - 'null'
          maxLength: 320
          description: >-
            New primary email, up to 320 characters. A non-empty value must
            already be a known employee email. Null clears it.
          title: Primary email
          example: avery@example.test
        startDate:
          type:
            - string
            - 'null'
          format: date
          description: >-
            New date in YYYY-MM-DD format. Omit to retain it or send null to
            clear it.
          title: Start date
          example: '2025-03-17'
        gender:
          type:
            - string
            - 'null'
          maxLength: 256
          description: >-
            Employee gender value. Omit it to retain the value or send null to
            clear it.
          title: Gender
        pronouns:
          type:
            - string
            - 'null'
          maxLength: 256
          description: >-
            Employee pronouns. Omit them to retain the value or send null to
            clear them.
          title: Pronouns
          example: they/them
        claimOwnership:
          type: array
          items:
            $ref: '#/components/schemas/EmployeeFieldKey'
          maxItems: 22
          description: >-
            Unique field keys to claim as manually owned. Claims can take over
            integration-owned or unowned fields without changing their values.
            Omit to leave ownership unchanged.
          title: Claim manual field ownership
          example:
            - jobTitle
      additionalProperties: false
      title: Employee profile patch
      description: >-
        Supply at least one field. Omitted fields stay unchanged; null clears
        only nullable fields.
      example:
        jobTitle: Senior Engineer
        claimOwnership:
          - jobTitle
    UpdateEmployeeResponse:
      type: object
      properties:
        employee:
          $ref: '#/components/schemas/EmployeeView'
      required:
        - employee
      additionalProperties: false
      title: Updated employee response
      example:
        employee:
          id: employee-avery
          name: Avery Chen
          avatarUrl: null
          jobTitle: Senior 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
    EmployeeFieldKey:
      type: string
      enum:
        - avatarUrl
        - dateOfBirth
        - departments
        - displayFullName
        - employmentStatus
        - employmentType
        - ethnicity
        - firstName
        - preferredName
        - gender
        - jobLevel
        - jobTitle
        - lastName
        - managerId
        - maritalStatus
        - phoneNumber
        - primaryEmail
        - pronouns
        - startDate
        - terminationDate
        - workLocation
        - country
      description: Employee profile field whose owning source is configured or resolved.
      title: Employee field key
      example: jobTitle
    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.