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

# Set an employee custom field value

> Set or overwrite a custom field value on an employee. Idempotent. Returns the updated field (definition + value). For SELECT supply the option id (string); for MULTI_SELECT supply an array of option ids. Option ids can be read from the `getEmployeeCustomFields` endpoint.

<span className="badge-write">Key: Write</span><span className="badge-company">Scope: Company</span>


## OpenAPI

````yaml https://api.getprimo.com/openapi.json put /employees/{employeeId}/custom-fields/{customFieldId}
openapi: 3.1.1
info:
  title: Public API - BETA
  description: Read docs on https://docs.getprimo.com/
  version: '1.0'
  contact: {}
servers:
  - url: https://api.getprimo.com
security:
  - apikey: []
tags: []
paths:
  /employees/{employeeId}/custom-fields/{customFieldId}:
    put:
      tags:
        - Employees
      summary: Set an employee custom field value
      description: >-
        Set or overwrite a custom field value on an employee. Idempotent.
        Returns the updated field (definition + value). For SELECT supply the
        option id (string); for MULTI_SELECT supply an array of option ids.
        Option ids can be read from the `getEmployeeCustomFields` endpoint.
      operationId: setEmployeeCustomFieldValue
      parameters:
        - name: employeeId
          required: true
          in: path
          schema:
            type: string
        - name: customFieldId
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetEmployeeCustomFieldValueBody'
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeCustomFieldItem_Output'
components:
  schemas:
    SetEmployeeCustomFieldValueBody:
      type: object
      properties:
        value:
          description: >-
            Value to set. Must conform to the field type. Pass null to clear an
            existing value. For SELECT supply the option id (string). For
            MULTI_SELECT supply an array of option ids.
          anyOf:
            - type: boolean
            - type: number
            - type: string
            - type: array
              items:
                type: string
            - type: 'null'
      required:
        - value
    EmployeeCustomFieldItem_Output:
      type: object
      properties:
        field:
          type: object
          properties:
            id:
              description: CustomField id (MongoDB ObjectId string).
              type: string
            label:
              type: string
            fieldType:
              description: Type of data this field holds.
              type: string
              enum:
                - SELECT
                - MULTI_SELECT
                - CHECKBOX
                - TEXT
                - DATE
                - NUMBER
                - URL
            applyTo:
              type: array
              items:
                type: string
                enum:
                  - DEVICE
                  - ACCESSORY
                  - EMPLOYEE
                  - ORDER
            options:
              description: >-
                Option catalog. Non-empty only for SELECT / MULTI_SELECT fields.
                Use option `id` when writing values.
              type: array
              items:
                type: object
                properties:
                  id:
                    description: >-
                      Stable UUID of the option. Use this id for SELECT /
                      MULTI_SELECT value writes.
                    type: string
                    format: uuid
                    pattern: >-
                      ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  value:
                    description: >-
                      Display label of the option (mutable — ids are the stable
                      identity).
                    type: string
                required:
                  - id
                  - value
                additionalProperties: false
          required:
            - id
            - label
            - fieldType
            - applyTo
            - options
          additionalProperties: false
        value:
          description: >-
            Current stored value for this field on this employee, or null when
            unset. For SELECT / MULTI_SELECT the value is the option id (or
            array of ids). For CHECKBOX it is a boolean. For DATE it is an ISO
            date string.
          anyOf:
            - type: boolean
            - type: number
            - type: string
            - type: array
              items:
                type: string
            - type: 'null'
      required:
        - field
        - value
      additionalProperties: false
  securitySchemes:
    apikey:
      scheme: bearer
      bearerFormat: API key
      type: http
      description: >-
        Use your Primo API key in the Authorization header as `Bearer
        <API_KEY>`.

````