--- title: "Create an incident user-defined field" method: POST path: "/api/v2/incidents/config/user-defined-fields" tags: ["Incidents"] --- # Create an incident user-defined field `POST /api/v2/incidents/config/user-defined-fields` ## Request - Base URL: `https://api.datadoghq.com` - URL: `https://api.datadoghq.com/api/v2/incidents/config/user-defined-fields` - Auth: one of: - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY` - OAuth 2 - Authorization code: `/oauth2/v1/authorize` - Token URL: `/oauth2/v1/token` scopes: `incident_settings_write` Create an incident user-defined field. ## Query parameters - `include` string ## Request body - IncidentUserDefinedFieldCreateRequest: Request body for creating an incident user-defined field. - `data` IncidentUserDefinedFieldCreateData, required: Data for creating an incident user-defined field. - `attributes` IncidentUserDefinedFieldAttributesCreateRequest, required: Attributes for creating an incident user-defined field. - `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. Defaults to a formatted version of the name if not provided. - `name` string, required: The unique identifier of the field. Must start with a letter or digit and contain only letters, digits, underscores, or periods. - `ordinal` string, nullable: A decimal string representing the field's display order in the UI. - `required` boolean: When true, users must fill out this field on incidents. - `tag_key` string, nullable: For metric tag-type fields only, the metric tag key that powers the autocomplete options. - `type` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8, 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[]: 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. - `relationships` IncidentUserDefinedFieldCreateRelationships, required: Relationships for creating an incident user-defined field. - `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. - `type` 'user_defined_field', required: The incident user defined fields type. ## Response `201` CREATED - 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.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/da68bf029e4c?raw)