Create Custom Field Option

POST

teams

{team_id}

custom-field-options

curl --request POST \
  --url https://public.api.serval.com/v2/teams/{team_id}/custom-field-options \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ticketSubtype": "<string>",
  "fieldName": "<string>",
  "enumOptions": [
    {
      "value": "<string>",
      "displayName": "<string>",
      "displayOrder": 123,
      "description": "<string>"
    }
  ],
  "sectionName": "<string>",
  "hidden": true
}
'

import requests

url = "https://public.api.serval.com/v2/teams/{team_id}/custom-field-options"

payload = {
    "ticketSubtype": "<string>",
    "fieldName": "<string>",
    "enumOptions": [
        {
            "value": "<string>",
            "displayName": "<string>",
            "displayOrder": 123,
            "description": "<string>"
        }
    ],
    "sectionName": "<string>",
    "hidden": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    ticketSubtype: '<string>',
    fieldName: '<string>',
    enumOptions: [
      {
        value: '<string>',
        displayName: '<string>',
        displayOrder: 123,
        description: '<string>'
      }
    ],
    sectionName: '<string>',
    hidden: true
  })
};

fetch('https://public.api.serval.com/v2/teams/{team_id}/custom-field-options', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://public.api.serval.com/v2/teams/{team_id}/custom-field-options",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ticketSubtype' => '<string>',
    'fieldName' => '<string>',
    'enumOptions' => [
        [
                'value' => '<string>',
                'displayName' => '<string>',
                'displayOrder' => 123,
                'description' => '<string>'
        ]
    ],
    'sectionName' => '<string>',
    'hidden' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://public.api.serval.com/v2/teams/{team_id}/custom-field-options"

	payload := strings.NewReader("{\n  \"ticketSubtype\": \"<string>\",\n  \"fieldName\": \"<string>\",\n  \"enumOptions\": [\n    {\n      \"value\": \"<string>\",\n      \"displayName\": \"<string>\",\n      \"displayOrder\": 123,\n      \"description\": \"<string>\"\n    }\n  ],\n  \"sectionName\": \"<string>\",\n  \"hidden\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://public.api.serval.com/v2/teams/{team_id}/custom-field-options")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ticketSubtype\": \"<string>\",\n  \"fieldName\": \"<string>\",\n  \"enumOptions\": [\n    {\n      \"value\": \"<string>\",\n      \"displayName\": \"<string>\",\n      \"displayOrder\": 123,\n      \"description\": \"<string>\"\n    }\n  ],\n  \"sectionName\": \"<string>\",\n  \"hidden\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public.api.serval.com/v2/teams/{team_id}/custom-field-options")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ticketSubtype\": \"<string>\",\n  \"fieldName\": \"<string>\",\n  \"enumOptions\": [\n    {\n      \"value\": \"<string>\",\n      \"displayName\": \"<string>\",\n      \"displayOrder\": 123,\n      \"description\": \"<string>\"\n    }\n  ],\n  \"sectionName\": \"<string>\",\n  \"hidden\": true\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "fieldValue": {
      "id": "<string>",
      "entityId": "<string>",
      "fieldId": "<string>",
      "fieldKey": "<string>",
      "fieldName": "<string>",
      "dataType": "DATA_TYPE_UNSPECIFIED",
      "value": 123,
      "setByUserId": "<string>",
      "setByAppInstanceId": "<string>",
      "createdAt": "2025-01-15T01:30:15.000Z",
      "deletedAt": "2025-01-15T01:30:15.000Z",
      "pinned": true,
      "redacted": true,
      "sensitive": true,
      "setByFormula": true
    },
    "field": {
      "id": "<string>",
      "entityTypeId": "<string>",
      "key": "<string>",
      "name": "<string>",
      "dataType": "DATA_TYPE_UNSPECIFIED",
      "createdAt": "2025-01-15T01:30:15.000Z",
      "updatedAt": "2025-01-15T01:30:15.000Z",
      "createdByUserId": "<string>",
      "updatedByUserId": "<string>",
      "enumOptions": [
        {
          "id": "<string>",
          "value": "<string>",
          "displayName": "<string>",
          "displayOrder": 123,
          "description": "<string>"
        }
      ],
      "isKeyField": true,
      "isNameField": true,
      "fieldId": "<string>",
      "refEntityTypeId": "<string>",
      "refEntityTypeIds": [
        "<string>"
      ],
      "description": "<string>",
      "sourceEntityTypeId": "<string>",
      "viewerCanViewValues": true,
      "viewerCanEdit": true,
      "helpAgentVisible": true,
      "sensitive": true,
      "sectionId": "<string>",
      "displayOptions": {
        "boolean": {
          "style": "STYLE_UNSPECIFIED"
        }
      },
      "valueSource": "FIELD_VALUE_SOURCE_UNSPECIFIED",
      "formula": "<string>",
      "defaultFormula": "<string>",
      "formulaDisabledAt": "2025-01-15T01:30:15.000Z",
      "autoNumber": {
        "prefix": "<string>",
        "digits": 123,
        "scope": "AUTO_NUMBER_SCOPE_UNSPECIFIED"
      }
    },
    "hidden": true
  }
}

Authentication and permissions

Token requirements: User-based token (OAuth) or Organization-scoped API key or Team-scoped API key. Send a bearer access token for one of these identities. The permissions and resource restrictions below also apply.

Credential	Access requirements
Organization-scoped API key	`ticket-fields:write`
Team-scoped API key	`ticket-fields:write`
User-based token (OAuth)	Supported, subject to permissions

Permissions joined by + are all required; or separates alternatives. Full-access keys still cannot call endpoints marked unsupported. Team keys must allow every team checked by the request. OAuth access depends on the user’s roles and resource access.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

team_id

string

required

The ID of the team to create the custom field definition on.

Body

application/json

ticketType

enum<string>

The ticket type the field belongs to. Each ticket type carries its own field schema — a field created on REQUEST does not exist on JOURNEY.

Available options:

TICKET_TYPE_UNSPECIFIED,

TICKET_TYPE_REQUEST,

TICKET_TYPE_TASK,

TICKET_TYPE_MAJOR_INCIDENT,

TICKET_TYPE_CONVERSATION,

TICKET_TYPE_JOURNEY,

TICKET_TYPE_INCIDENT,

TICKET_TYPE_CHANGE,

TICKET_TYPE_CUSTOM,

TICKET_TYPE_PROBLEM

ticketSubtype

string | null

Required for CHANGE tickets — each subtype (normal, standard, emergency, custom) has its own field schema. Omit for non-change types.

fieldName

string

Display name of the field, e.g. "System". Must be unique within the ticket type's schema.

dataType

enum<string>

Available options:

DATA_TYPE_UNSPECIFIED,

TEXT,

NUMBER,

BOOL,

TIMESTAMP,

ENUM,

ENTITY_REF,

USER_REF,

UNIQUE,

MULTI_SELECT,

FILE,

TICKET_REF

enumOptions

EnumOptionInput · object[]

Required for ENUM and MULTI_SELECT, rejected for every other data type. Each option must set both value and display_name.

Show child attributes

sectionName

string

Group the field under a named section, creating the section on first reference. Omit to leave the field unsectioned (the Overview tab).

hidden

boolean

Create the field default-hidden: excluded from ticket-view field groups and list-view columns/filters, but still readable and writable.

Response

200 - application/json

Success

data

data · object

The created definition, shaped like the items ListCustomFieldOptions returns: field populated, field_value empty.

Show child attributes

Create Custom Field Option

curl --request POST \
  --url https://public.api.serval.com/v2/teams/{team_id}/custom-field-options \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ticketSubtype": "<string>",
  "fieldName": "<string>",
  "enumOptions": [
    {
      "value": "<string>",
      "displayName": "<string>",
      "displayOrder": 123,
      "description": "<string>"
    }
  ],
  "sectionName": "<string>",
  "hidden": true
}
'

import requests

url = "https://public.api.serval.com/v2/teams/{team_id}/custom-field-options"

payload = {
    "ticketSubtype": "<string>",
    "fieldName": "<string>",
    "enumOptions": [
        {
            "value": "<string>",
            "displayName": "<string>",
            "displayOrder": 123,
            "description": "<string>"
        }
    ],
    "sectionName": "<string>",
    "hidden": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    ticketSubtype: '<string>',
    fieldName: '<string>',
    enumOptions: [
      {
        value: '<string>',
        displayName: '<string>',
        displayOrder: 123,
        description: '<string>'
      }
    ],
    sectionName: '<string>',
    hidden: true
  })
};

fetch('https://public.api.serval.com/v2/teams/{team_id}/custom-field-options', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://public.api.serval.com/v2/teams/{team_id}/custom-field-options",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ticketSubtype' => '<string>',
    'fieldName' => '<string>',
    'enumOptions' => [
        [
                'value' => '<string>',
                'displayName' => '<string>',
                'displayOrder' => 123,
                'description' => '<string>'
        ]
    ],
    'sectionName' => '<string>',
    'hidden' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://public.api.serval.com/v2/teams/{team_id}/custom-field-options"

	payload := strings.NewReader("{\n  \"ticketSubtype\": \"<string>\",\n  \"fieldName\": \"<string>\",\n  \"enumOptions\": [\n    {\n      \"value\": \"<string>\",\n      \"displayName\": \"<string>\",\n      \"displayOrder\": 123,\n      \"description\": \"<string>\"\n    }\n  ],\n  \"sectionName\": \"<string>\",\n  \"hidden\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://public.api.serval.com/v2/teams/{team_id}/custom-field-options")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ticketSubtype\": \"<string>\",\n  \"fieldName\": \"<string>\",\n  \"enumOptions\": [\n    {\n      \"value\": \"<string>\",\n      \"displayName\": \"<string>\",\n      \"displayOrder\": 123,\n      \"description\": \"<string>\"\n    }\n  ],\n  \"sectionName\": \"<string>\",\n  \"hidden\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public.api.serval.com/v2/teams/{team_id}/custom-field-options")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ticketSubtype\": \"<string>\",\n  \"fieldName\": \"<string>\",\n  \"enumOptions\": [\n    {\n      \"value\": \"<string>\",\n      \"displayName\": \"<string>\",\n      \"displayOrder\": 123,\n      \"description\": \"<string>\"\n    }\n  ],\n  \"sectionName\": \"<string>\",\n  \"hidden\": true\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "fieldValue": {
      "id": "<string>",
      "entityId": "<string>",
      "fieldId": "<string>",
      "fieldKey": "<string>",
      "fieldName": "<string>",
      "dataType": "DATA_TYPE_UNSPECIFIED",
      "value": 123,
      "setByUserId": "<string>",
      "setByAppInstanceId": "<string>",
      "createdAt": "2025-01-15T01:30:15.000Z",
      "deletedAt": "2025-01-15T01:30:15.000Z",
      "pinned": true,
      "redacted": true,
      "sensitive": true,
      "setByFormula": true
    },
    "field": {
      "id": "<string>",
      "entityTypeId": "<string>",
      "key": "<string>",
      "name": "<string>",
      "dataType": "DATA_TYPE_UNSPECIFIED",
      "createdAt": "2025-01-15T01:30:15.000Z",
      "updatedAt": "2025-01-15T01:30:15.000Z",
      "createdByUserId": "<string>",
      "updatedByUserId": "<string>",
      "enumOptions": [
        {
          "id": "<string>",
          "value": "<string>",
          "displayName": "<string>",
          "displayOrder": 123,
          "description": "<string>"
        }
      ],
      "isKeyField": true,
      "isNameField": true,
      "fieldId": "<string>",
      "refEntityTypeId": "<string>",
      "refEntityTypeIds": [
        "<string>"
      ],
      "description": "<string>",
      "sourceEntityTypeId": "<string>",
      "viewerCanViewValues": true,
      "viewerCanEdit": true,
      "helpAgentVisible": true,
      "sensitive": true,
      "sectionId": "<string>",
      "displayOptions": {
        "boolean": {
          "style": "STYLE_UNSPECIFIED"
        }
      },
      "valueSource": "FIELD_VALUE_SOURCE_UNSPECIFIED",
      "formula": "<string>",
      "defaultFormula": "<string>",
      "formulaDisabledAt": "2025-01-15T01:30:15.000Z",
      "autoNumber": {
        "prefix": "<string>",
        "digits": 123,
        "scope": "AUTO_NUMBER_SCOPE_UNSPECIFIED"
      }
    },
    "hidden": true
  }
}

Get started

Authentication

Endpoints

Development

Authentication and permissions

Authorizations

Path Parameters

Body

Response

​Authentication and permissions

Authorizations

Path Parameters

Body

Response

Authentication and permissions