---
title: "Update an incident user-defined field"
method: PATCH
path: "/api/v2/incidents/config/user-defined-fields/{field_id}"
tags: ["Incidents"]
---

# Update an incident user-defined field

`PATCH /api/v2/incidents/config/user-defined-fields/{field_id}`

Update an incident user-defined field.

## Path parameters

- `field_id` string, required

## Query parameters

- `include` string

## Request body

- IncidentUserDefinedFieldUpdateRequest — Request body for updating an incident user-defined field.
  - `data` IncidentUserDefinedFieldUpdateData, required — Data for updating an incident user-defined field.
    - `attributes` IncidentUserDefinedFieldAttributesUpdateRequest, required — Attributes for updating an incident user-defined field. All fields are optional.
      - `category` 'what_happened' | 'why_it_happened', nullable — The section in which the field appears: "what_happened" or "why_it_happened". When null, the field appears in the Attributes section.
      - `collected` 'active' | 'stable' | 'resolved' | 'completed', nullable — The lifecycle stage at which the app prompts users to fill out this field. Cannot be set on required fields.
      - `default_value` string, nullable — The default value for the field. Must be one of the valid values when valid_values is set.
      - `display_name` string — The human-readable name shown in the UI.
      - `ordinal` string, nullable — A decimal string representing the field's display order in the UI.
      - `required` boolean, nullable — When true, users must fill out this field on incidents.
      - `valid_values` IncidentUserDefinedFieldValidValue[], nullable — The list of allowed values for dropdown and multiselect fields. Limited to 1000 values.
        - `description` string — A detailed description of the valid value.
        - `display_name` string, required — The human-readable display name for this value.
        - `short_description` string — A short description of the valid value.
        - `value` string, required — The identifier that is stored when this option is selected.
    - `id` string, required — The unique identifier of the user-defined field to update.
    - `type` 'user_defined_field', required — The incident user defined fields type.

## Response `200`

OK

- IncidentUserDefinedFieldResponse — Response containing a single incident user-defined field.
  - `data` IncidentUserDefinedFieldResponseData, required — Data object for an incident user-defined field response.
    - `attributes` IncidentUserDefinedFieldAttributesResponse, required — Attributes of an incident user-defined field.
      - `category` 'what_happened' | 'why_it_happened', nullable, required — The section in which the field appears: "what_happened" or "why_it_happened". When null, the field appears in the Attributes section.
      - `collected` 'active' | 'stable' | 'resolved' | 'completed', nullable, required — The lifecycle stage at which the app prompts users to fill out this field. Cannot be set on required fields.
      - `created` string, date-time, required — Timestamp when the field was created.
      - `default_value` string, nullable, required — The default value for the field.
      - `deleted` string, date-time, nullable, required — Timestamp when the field was soft-deleted, or null if not deleted.
      - `display_name` string, required — The human-readable name shown in the UI.
      - `metadata` IncidentUserDefinedFieldMetadata, nullable, required — Metadata for autocomplete-type user-defined fields, describing how to populate autocomplete options.
        - `category` string, required — The category of the autocomplete source.
        - `search_limit_param` string, required — The query parameter used to limit the number of autocomplete results.
        - `search_params` object, required — Additional query parameters to include in the search URL.
        - `search_query_param` string, required — The query parameter used to pass typed input to the search URL.
        - `search_result_path` string, required — The JSON path to the results in the response body.
        - `search_url` string, required — The URL used to populate autocomplete options.
      - `modified` string, date-time, nullable, required — Timestamp when the field was last modified.
      - `name` string, required — The unique identifier of the field.
      - `ordinal` string, nullable, required — A decimal string representing the field's display order in the UI.
      - `required` boolean, required — When true, users must fill out this field on incidents.
      - `reserved` boolean, required — When true, this field is reserved for system use and cannot be deleted.
      - `tag_key` string, nullable, required — For metric tag-type fields only, the metric tag key that powers the autocomplete options.
      - `type` integer, nullable, required — The data type of the field. 1=dropdown, 2=multiselect, 3=textbox, 4=textarray, 5=metrictag, 6=autocomplete, 7=number, 8=datetime.
      - `valid_values` IncidentUserDefinedFieldValidValue[], nullable, required — The list of allowed values for dropdown, multiselect, and autocomplete fields.
        - `description` string — A detailed description of the valid value.
        - `display_name` string, required — The human-readable display name for this value.
        - `short_description` string — A short description of the valid value.
        - `value` string, required — The identifier that is stored when this option is selected.
    - `id` string, required — The unique identifier of the user-defined field.
    - `relationships` IncidentUserDefinedFieldRelationships, required — Relationships of an incident user-defined field.
      - `created_by_user` RelationshipToUser, required — Relationship to user.
        - `data` RelationshipToUserData, required — Relationship to user object.
          - `id` string, required — A unique identifier that represents the user.
          - `type` 'users', required — Users resource type.
      - `incident_type` RelationshipToIncidentType, required — Relationship to an incident type.
        - `data` RelationshipToIncidentTypeData, required — Relationship to incident type object.
          - `id` string, required — The incident type's ID.
          - `type` 'incident_types', required — Incident type resource type.
      - `last_modified_by_user` RelationshipToUser, required — Relationship to user.
        - `data` RelationshipToUserData, required — Relationship to user object.
          - `id` string, required — A unique identifier that represents the user.
          - `type` 'users', required — Users resource type.
    - `type` 'user_defined_field', required — The incident user defined fields type.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `429` — Too many requests

---

[API](https://skmtc.net/datadog/apis/api-v2.md) · [All operations](https://skmtc.net/datadog/apis/api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/datadog/api-v2/versions/da68bf029e4c/schema)