> Documentation index for AI agents: https://docs.pagerduty.com/llms.txt

# Update a Field

`PUT https://api.pagerduty.com/services/custom_fields/{field_id}`

Update a Custom Field for Services.

Scoped OAuth requires: `custom_fields.write`

## Authorization

- **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=<API_KEY>`

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `field_id` | string | yes | The ID of the field. |

## Header parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. |

## Request body (`application/json`)

| Field | Type | Required | Description |
|---|---|---|---|
| `field` | object | yes | Details of the custom field to be updated. |
| `field.description` | string \| null |  | A description of the data this field contains. Max length: 1000. |
| `field.display_name` | string |  | The human-readable name of the field. This must be unique across an account. Max length: 50. |
| `field.enabled` | boolean |  | Whether the field is enabled. One of: `true`, `false`. |
| `field.field_options` | array of object |  | List of field options to update, insert or delete. This field supports several behaviors: - Empty array: Deletes all field options - Omitting the `field_options` array entirely: Preserves all existing options - Not listing an existing option: Deletes that option (unless it's the current default value) |
| `field.field_options[].data` | object | yes | The data content of the field option. |
| `field.field_options[].data.data_type` | string | yes | The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. |
| `field.field_options[].data.value` | string | yes | The value of the field option. Must be unique within the field. Max length: 200. |
| `field.field_options[].id` | string |  | The unique identifier of the field option. How this field is used determines the behavior: - When included with a valid `id`: Updates the corresponding existing field option - When omitted or null: Creates a new field option. |

Example: Update Field Example - Basic Properties

```json
{
  "field": {
    "description": "The production environment where this service is deployed",
    "display_name": "Production Environment",
    "enabled": true
  }
}
```

Example: Update Field Example - With Field Options

```json
{
  "field": {
    "description": "The production environment where this service is deployed",
    "display_name": "Production Environment",
    "enabled": true,
    "field_options": [
      {
        "data": {
          "data_type": "string",
          "value": "production"
        },
        "id": "OPT1"
      },
      {
        "data": {
          "data_type": "string",
          "value": "staging-new"
        },
        "id": "OPT2"
      },
      {
        "data": {
          "data_type": "string",
          "value": "development-new"
        }
      }
    ]
  }
}
```

## Response 200

The field object updated.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `field` | object |  | Details of the custom field. |
| `field.created_at` | string (date-time) |  | The date/time the object was created at. |
| `field.data_type` | string |  | The kind of data the custom field is allowed to contain. One of: `boolean`, `integer`, `float`, `string`, `datetime`, `url`. |
| `field.description` | string \| null |  | A description of the data this field contains. Max length: 1000. |
| `field.display_name` | string |  | The human-readable name of the field. This must be unique across an account. Max length: 50. |
| `field.enabled` | boolean |  | Whether the field is enabled. One of: `true`, `false`. |
| `field.field_options` | array of object |  | The options for the custom field. Applies only to `single_value_fixed` and `multi_value_fixed` field types. These options are returned only if the `include[]` parameter specifies `field_options`. |
| `field.field_options[].created_at` | string (date-time) |  | The date/time the object was created at. |
| `field.field_options[].data` | object |  |  |
| `field.field_options[].data.data_type` | string |  | The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. |
| `field.field_options[].data.value` | string |  | Max length: 200. |
| `field.field_options[].id` | string |  | The ID of the resource. |
| `field.field_options[].type` | string |  | One of: `field_option`. |
| `field.field_options[].updated_at` | string (date-time) |  | The date/time the object was updated at. |
| `field.field_type` | string |  | The type of data this field contains. In combination with the `data_type` field. One of: `single_value`, `single_value_fixed`, `multi_value`, `multi_value_fixed`. |
| `field.id` | string |  | The ID of the resource. |
| `field.name` | string |  | The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. |
| `field.self` | string \| null (url) |  | The API show URL at which the object is accessible. Read-only. |
| `field.summary` | string \| null |  | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `display_name`. Read-only. |
| `field.type` | string |  | Read-only. One of: `field`. |
| `field.updated_at` | string (date-time) |  | The date/time the object was updated at. |

Example: Response Example

```json
{
  "field": {
    "created_at": "2023-01-01T00:00:00Z",
    "data_type": "string",
    "description": "The production environment where this service is deployed",
    "display_name": "Production Environment",
    "enabled": true,
    "field_options": [
      {
        "created_at": "2023-01-01T00:00:00Z",
        "data": {
          "data_type": "string",
          "value": "production"
        },
        "id": "OPT1",
        "type": "field_option",
        "updated_at": "2023-01-02T00:00:00Z"
      },
      {
        "created_at": "2023-01-01T00:00:00Z",
        "data": {
          "data_type": "string",
          "value": "staging-new"
        },
        "id": "OPT2",
        "type": "field_option",
        "updated_at": "2023-01-02T00:00:00Z"
      },
      {
        "created_at": "2023-01-02T00:00:00Z",
        "data": {
          "data_type": "string",
          "value": "development-new"
        },
        "id": "OPT4",
        "type": "field_option",
        "updated_at": "2023-01-02T00:00:00Z"
      }
    ],
    "field_type": "single_value_fixed",
    "id": "ABCDEF1",
    "name": "environment",
    "self": "https://api.pagerduty.com/services/custom_fields/ABCDEF1",
    "summary": "Production Environment",
    "type": "custom_fields_field",
    "updated_at": "2023-01-02T00:00:00Z"
  }
}
```

## Response 400

Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Response 403

Caller is not authorized to view the requested resource.
While your authentication is valid, the authenticated user or token does not have permission to perform this action.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Response 404

The requested resource was not found.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Response 500

Internal Server Error the PagerDuty server experienced an error.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Developer Agreement

Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement).