> Documentation index for AI agents: https://docs.pagerduty.com/llms.txt # Create a Field `POST https://api.pagerduty.com/services/custom_fields` Creates a new Custom Field for Services, along with the Field Options if provided. Scoped OAuth requires: `custom_fields.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## 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 created. | | `field.data_type` | string | yes | 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 | yes | 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 | | | | `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_type` | string | yes | 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.name` | string | yes | 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. | Example: Example: With field_options and single-value ```json { "field": { "data_type": "string", "description": "The environment that the service operates in", "display_name": "Environment", "enabled": true, "field_options": [ { "data": { "data_type": "string", "value": "production" } }, { "data": { "data_type": "string", "value": "staging" } }, { "data": { "data_type": "string", "value": "development" } } ], "field_type": "single_value_fixed", "name": "environment" } } ``` Example: Example: With field_options and multi-value ```json { "field": { "data_type": "string", "description": "The regions where this service is deployed", "display_name": "Supported Regions", "enabled": true, "field_options": [ { "data": { "data_type": "string", "value": "us-east-1" } }, { "data": { "data_type": "string", "value": "us-west-1" } }, { "data": { "data_type": "string", "value": "eu-west-1" } }, { "data": { "data_type": "string", "value": "ap-southeast-1" } } ], "field_type": "multi_value_fixed", "name": "supported_regions" } } ``` Example: Example: Without field_options ```json { "field": { "data_type": "string", "description": "The team that owns this service", "display_name": "Team Owner", "enabled": true, "field_type": "single_value", "name": "team_owner" } } ``` ## Response 201 The field object created, along with the Field Options if provided. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field` | object | yes | 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: Example: With field_options and single-value ```json { "field": { "created_at": "2023-01-01T00:00:00Z", "data_type": "string", "description": "The environment that the service operates in", "display_name": "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-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "staging" }, "id": "OPT2", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "development" }, "id": "OPT3", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" } ], "field_type": "single_value_fixed", "id": "ABCDEF1", "name": "environment", "self": "https://api.pagerduty.com/services/custom_fields/ABCDEF1", "summary": "Environment", "type": "custom_fields_field", "updated_at": "2023-01-01T00:00:00Z" } } ``` Example: Example: With field_options and multi-value ```json { "field": { "created_at": "2023-01-01T00:00:00Z", "data_type": "string", "description": "The regions where this service is deployed", "display_name": "Supported Regions", "enabled": true, "field_options": [ { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "us-east-1" }, "id": "OPT4", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "us-west-1" }, "id": "OPT5", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "eu-west-1" }, "id": "OPT6", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "ap-southeast-1" }, "id": "OPT7", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" } ], "field_type": "multi_value_fixed", "id": "ABCDEF2", "name": "supported_regions", "self": "https://api.pagerduty.com/services/custom_fields/ABCDEF2", "summary": "Supported Regions", "type": "custom_fields_field", "updated_at": "2023-01-01T00:00:00Z" } } ``` Example: Example: Without field_options ```json { "field": { "created_at": "2023-01-01T00:00:00Z", "data_type": "string", "description": "The team that owns this service", "display_name": "Team Owner", "enabled": true, "field_type": "single_value", "id": "ABCDEF3", "name": "team_owner", "self": "https://api.pagerduty.com/services/custom_fields/ABCDEF3", "summary": "Team Owner", "type": "custom_fields_field", "updated_at": "2023-01-01T00: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 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).