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

# Set an employee field source override

> Sets the source for one employee field, taking precedence over the company default.

- First call GET /c/{companyId}/field-sources/available-sources to choose a source that supports the field. New integration assignments require a connected source; manual is always available.
- This request is idempotent: repeating the saved source returns the unchanged configuration without requesting another refresh, even after disconnection.
- This saves ownership, not a field value. To enter a value yourself, select manual, then use PATCH /c/{companyId}/employees/{employeeId} for a field accepted by that operation's request schema. For example, set jobTitle to manual, then PATCH `{"jobTitle":"Senior Engineer"}`. Manual ownership does not make every field writable.
- Updating the value separately requires permission to manage employee profiles (`org_chart.manage`).
- When the selected source supports refresh, Windmill requests updated integration data in the background. A successful response confirms the ownership change, not that employee values have refreshed. The response contains configuration only.

The employee must exist in the company. Requires permission to manage employee field sources (`employees.manage_field_mappings`).



## OpenAPI

````yaml https://api.gowindmill.com/api/v2/openapi.json put /c/{companyId}/employees/{employeeId}/field-sources/{fieldKey}
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}/field-sources/{fieldKey}:
    put:
      tags:
        - Employee Field Sources
      summary: Set an employee field source override
      description: >-
        Sets the source for one employee field, taking precedence over the
        company default.


        - First call GET /c/{companyId}/field-sources/available-sources to
        choose a source that supports the field. New integration assignments
        require a connected source; manual is always available.

        - This request is idempotent: repeating the saved source returns the
        unchanged configuration without requesting another refresh, even after
        disconnection.

        - This saves ownership, not a field value. To enter a value yourself,
        select manual, then use PATCH /c/{companyId}/employees/{employeeId} for
        a field accepted by that operation's request schema. For example, set
        jobTitle to manual, then PATCH `{"jobTitle":"Senior Engineer"}`. Manual
        ownership does not make every field writable.

        - Updating the value separately requires permission to manage employee
        profiles (`org_chart.manage`).

        - When the selected source supports refresh, Windmill requests updated
        integration data in the background. A successful response confirms the
        ownership change, not that employee values have refreshed. The response
        contains configuration only.


        The employee must exist in the company. Requires permission to manage
        employee field sources (`employees.manage_field_mappings`).
      operationId: employees.fieldSources.set
      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
            description: >-
              Employee ID in this company. This identifies an org-chart person,
              not a member.
            title: Employee ID
            example: employee-avery
          required: true
          description: >-
            Employee ID in this company. This identifies an org-chart person,
            not a member.
          name: employeeId
          in: path
        - schema:
            $ref: '#/components/schemas/EmployeeFieldKey'
          required: true
          description: >-
            Employee profile field whose owning source is configured or
            resolved.
          name: fieldKey
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetEmployeeFieldSourceRequest'
      responses:
        '200':
          description: Saved employee-specific field owner override.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SetEmployeeFieldSourceResponse'
                  - example:
                      config:
                        id: field-config-job-title
                        companyId: company-acme
                        employeeId: employee-avery
                        fieldKey: jobTitle
                        source: manual
                        createdAt: '2026-01-15T10:00:00.000Z'
                        updatedAt: '2026-01-15T10:00:00.000Z'
        '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:
    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
    SetEmployeeFieldSourceRequest:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/AssignableEmployeeFieldSourceId'
      required:
        - source
    SetEmployeeFieldSourceResponse:
      type: object
      properties:
        config:
          $ref: '#/components/schemas/EmployeeFieldSourceConfig'
      required:
        - config
    AssignableEmployeeFieldSourceId:
      type: string
      enum:
        - manual
        - scim
        - slack
        - google-workspace
        - google-workspace-individual
        - outlook-calendar
        - adp-workforce-now
        - bamboo-hr
        - charthop
        - darwinbox
        - dayforce
        - deel
        - gusto
        - hibob
        - humaans
        - just-works
        - oracle-hcm
        - paylocity
        - rippling
        - trinet
        - ukg-pro
        - workday
      description: >-
        An owning source. New assignments require a connected source supporting
        the field. Manual is always available; SCIM requires enabled
        provisioning.
      example: manual
    EmployeeFieldSourceConfig:
      type: object
      properties:
        id:
          type: string
          description: Opaque identifier of this configuration record.
          title: Configuration ID
          example: field-config-job-title
        companyId:
          type: string
          description: >-
            Company ID owning this configuration. This is not the company URL
            slug.
          title: Company ID
          example: company-acme
        employeeId:
          type:
            - string
            - 'null'
          description: >-
            Employee ID for a per-employee override. Null identifies a
            company-wide default.
          title: Employee ID
          example: employee-avery
        fieldKey:
          $ref: '#/components/schemas/EmployeeFieldKey'
        source:
          $ref: '#/components/schemas/EmployeeFieldSourceId'
        createdAt:
          type: string
          description: Timestamp when this configuration record was created.
          title: Created at
          example: '2026-01-15T10:00:00.000Z'
        updatedAt:
          type: string
          description: Timestamp when this configuration record was last updated.
          title: Updated at
          example: '2026-01-15T10:00:00.000Z'
      required:
        - id
        - companyId
        - employeeId
        - fieldKey
        - source
        - createdAt
        - updatedAt
    EmployeeFieldSourceId:
      type: string
      enum:
        - manual
        - system
        - scim
        - slack
        - slack-analytics
        - google-workspace
        - google-workspace-individual
        - notion
        - airtable
        - attio
        - gong
        - monday
        - merge
        - adp-workforce-now
        - bamboo-hr
        - charthop
        - darwinbox
        - dayforce
        - deel
        - gusto
        - hibob
        - humaans
        - just-works
        - oracle-hcm
        - outlook-calendar
        - paylocity
        - rippling
        - trinet
        - ukg-pro
        - workday
        - asana
        - bonusly
        - claude
        - clickup
        - codex
        - cursor
        - devin
        - figma
        - front
        - github
        - granola
        - hubspot
        - intercom
        - jira
        - linear
        - pipedrive
        - roam
        - salesforce
        - slack-agent
        - windmill
        - zendesk
        - zendesk-chat
        - zoom
      description: >-
        Public source identifier. Saved configurations may retain a disconnected
        source.
      example: bamboo-hr
  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.