Ticket API

Search Tickets

Search tickets with filters. Supports filtering by team, assignment, status, escalation level, time range, external ticket key, and parent_ticket_ids (all children of the given tickets — e.g. every task of a journey — matching the parent_ticket_id field on the ticket payload). Without team_ids, a signed-in user’s search covers the teams they belong to plus tickets on any team that they requested, are assigned, or subscribe to, except team-only tickets on teams they are not on; set requester_user_ids to the caller’s own user ID (from Get Current User) to list the tickets they filed. Set max_description_length to keep list responses short.

POST

tickets

Search Tickets

curl --request POST \
  --url https://public.api.serval.com/v2/tickets/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "teamIds": [
    "<string>"
  ],
  "assignedToUserIds": [
    "<string>"
  ],
  "requesterUserIds": [
    "<string>"
  ],
  "statusIds": [
    "<string>"
  ],
  "escalationLevels": [],
  "createdAfter": "2025-01-15T01:30:15.000Z",
  "createdBefore": "2025-01-15T01:30:15.000Z",
  "pageSize": 123,
  "pageToken": "<string>",
  "externalTicketKeys": [
    "<string>"
  ],
  "parentTicketIds": [
    "<string>"
  ],
  "ticketNumbers": [
    123
  ],
  "maxDescriptionLength": 123
}
'

import requests

url = "https://public.api.serval.com/v2/tickets/search"

payload = {
    "teamIds": ["<string>"],
    "assignedToUserIds": ["<string>"],
    "requesterUserIds": ["<string>"],
    "statusIds": ["<string>"],
    "escalationLevels": [],
    "createdAfter": "2025-01-15T01:30:15.000Z",
    "createdBefore": "2025-01-15T01:30:15.000Z",
    "pageSize": 123,
    "pageToken": "<string>",
    "externalTicketKeys": ["<string>"],
    "parentTicketIds": ["<string>"],
    "ticketNumbers": [123],
    "maxDescriptionLength": 123
}
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({
    teamIds: ['<string>'],
    assignedToUserIds: ['<string>'],
    requesterUserIds: ['<string>'],
    statusIds: ['<string>'],
    escalationLevels: [],
    createdAfter: '2025-01-15T01:30:15.000Z',
    createdBefore: '2025-01-15T01:30:15.000Z',
    pageSize: 123,
    pageToken: '<string>',
    externalTicketKeys: ['<string>'],
    parentTicketIds: ['<string>'],
    ticketNumbers: [123],
    maxDescriptionLength: 123
  })
};

fetch('https://public.api.serval.com/v2/tickets/search', 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/tickets/search",
  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([
    'teamIds' => [
        '<string>'
    ],
    'assignedToUserIds' => [
        '<string>'
    ],
    'requesterUserIds' => [
        '<string>'
    ],
    'statusIds' => [
        '<string>'
    ],
    'escalationLevels' => [
        
    ],
    'createdAfter' => '2025-01-15T01:30:15.000Z',
    'createdBefore' => '2025-01-15T01:30:15.000Z',
    'pageSize' => 123,
    'pageToken' => '<string>',
    'externalTicketKeys' => [
        '<string>'
    ],
    'parentTicketIds' => [
        '<string>'
    ],
    'ticketNumbers' => [
        123
    ],
    'maxDescriptionLength' => 123
  ]),
  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/tickets/search"

	payload := strings.NewReader("{\n  \"teamIds\": [\n    \"<string>\"\n  ],\n  \"assignedToUserIds\": [\n    \"<string>\"\n  ],\n  \"requesterUserIds\": [\n    \"<string>\"\n  ],\n  \"statusIds\": [\n    \"<string>\"\n  ],\n  \"escalationLevels\": [],\n  \"createdAfter\": \"2025-01-15T01:30:15.000Z\",\n  \"createdBefore\": \"2025-01-15T01:30:15.000Z\",\n  \"pageSize\": 123,\n  \"pageToken\": \"<string>\",\n  \"externalTicketKeys\": [\n    \"<string>\"\n  ],\n  \"parentTicketIds\": [\n    \"<string>\"\n  ],\n  \"ticketNumbers\": [\n    123\n  ],\n  \"maxDescriptionLength\": 123\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/tickets/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"teamIds\": [\n    \"<string>\"\n  ],\n  \"assignedToUserIds\": [\n    \"<string>\"\n  ],\n  \"requesterUserIds\": [\n    \"<string>\"\n  ],\n  \"statusIds\": [\n    \"<string>\"\n  ],\n  \"escalationLevels\": [],\n  \"createdAfter\": \"2025-01-15T01:30:15.000Z\",\n  \"createdBefore\": \"2025-01-15T01:30:15.000Z\",\n  \"pageSize\": 123,\n  \"pageToken\": \"<string>\",\n  \"externalTicketKeys\": [\n    \"<string>\"\n  ],\n  \"parentTicketIds\": [\n    \"<string>\"\n  ],\n  \"ticketNumbers\": [\n    123\n  ],\n  \"maxDescriptionLength\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public.api.serval.com/v2/tickets/search")

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  \"teamIds\": [\n    \"<string>\"\n  ],\n  \"assignedToUserIds\": [\n    \"<string>\"\n  ],\n  \"requesterUserIds\": [\n    \"<string>\"\n  ],\n  \"statusIds\": [\n    \"<string>\"\n  ],\n  \"escalationLevels\": [],\n  \"createdAfter\": \"2025-01-15T01:30:15.000Z\",\n  \"createdBefore\": \"2025-01-15T01:30:15.000Z\",\n  \"pageSize\": 123,\n  \"pageToken\": \"<string>\",\n  \"externalTicketKeys\": [\n    \"<string>\"\n  ],\n  \"parentTicketIds\": [\n    \"<string>\"\n  ],\n  \"ticketNumbers\": [\n    123\n  ],\n  \"maxDescriptionLength\": 123\n}"

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

{
  "data": [
    {
      "id": "<string>",
      "friendlyIdentifier": "<string>",
      "teamId": "<string>",
      "name": "<string>",
      "description": "<string>",
      "createdAt": "2025-01-15T01:30:15.000Z",
      "completedAt": "2025-01-15T01:30:15.000Z",
      "escalatedAt": "2025-01-15T01:30:15.000Z",
      "createdByUserId": "<string>",
      "assignedToUserId": "<string>",
      "requesterUserId": "<string>",
      "statusId": "<string>",
      "escalationLevel": "AI",
      "priorityId": "<string>",
      "slaStartedAt": "2025-01-15T01:30:15.000Z",
      "slaBreachesAt": "2025-01-15T01:30:15.000Z",
      "labelIds": [
        "<string>"
      ],
      "type": "TICKET_TYPE_UNSPECIFIED",
      "dueDate": {
        "year": 123,
        "month": 123,
        "day": 123
      },
      "isOverdue": true,
      "dueAt": "2025-01-15T01:30:15.000Z",
      "childTicketIds": [
        "<string>"
      ],
      "linkedTicketIds": [
        "<string>"
      ],
      "duplicateTicketIds": [
        "<string>"
      ],
      "dependsOnTicketIds": [
        "<string>"
      ],
      "parentTicketId": "<string>",
      "conversationThreadTicketIds": [
        "<string>"
      ],
      "conversationThreadParentTicketId": "<string>",
      "nameTranslations": {},
      "descriptionTranslations": {},
      "categoryOptionId": "<string>",
      "assignedToGroupId": "<string>",
      "url": "<string>",
      "statusName": "<string>"
    }
  ],
  "nextPageToken": "<string>"
}

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	`tickets:read`
Team-scoped API key	Search specified teams: `tickets:read` Search the organization: Unsupported
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.

Search specified teams: Supply team_ids. Every requested team must be allowed.
Search the organization: Omitting team_ids searches the organization and requires an organization-scoped key. A signed-in user instead sees their own teams plus tickets on any team that they requested, are assigned, or subscribe to, except team-only tickets on teams they are not on.

Authorizations

Authorization

string

header

required

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

Body

application/json

teamIds

string[]

Optional. Filter to specific teams. If not provided, searches all accessible teams.

assignedToUserIds

string[]

Optional. Only return tickets assigned to any of these users.

requesterUserIds

string[]

Optional. Only return tickets requested by any of these users.

statusIds

string[]

Optional. Filter by status IDs. Returns tickets matching ANY of the specified statuses.

escalationLevels

enum<string>[]

Optional. Filter by escalation levels. Returns tickets matching ANY of the specified levels.

Available options:

AI,

HUMAN

createdAfter

string<date-time> | null

A timestamp in RFC 3339 format (e.g., "2025-01-15T01:30:15Z").

Example:

"2025-01-15T01:30:15.000Z"

createdBefore

string<date-time> | null

A timestamp in RFC 3339 format (e.g., "2025-01-15T01:30:15Z").

Example:

"2025-01-15T01:30:15.000Z"

pageSize

integer<int32> | null

Maximum number of results to return. Default is 1000, maximum is 5000.

pageToken

string | null

Token for pagination. Leave empty for the first request.

externalTicketKeys

string[]

Optional. Only return tickets linked to any of these external tickets. Matches a Jira key ("GMD-29"), a ServiceNow number ("INC0010001", "RITM0010001", or "HRC0010001"), or the internal external ticket id. Matches are exact and case-sensitive.

parentTicketIds

string[]

Optional. Only return tickets whose parent is any of these tickets — the same relationship the response exposes as parent_ticket_id. For a journey ticket this returns its tasks in one request (and for a task, its subtasks), replacing per-ticket child lookups.

ticketNumbers

integer<int32>[]

Optional. Only return tickets with any of these ticket numbers — the numeric half of the human-readable identifier ("5" for "DEV-5"). Numbers are unique only WITHIN a team, so combine this with team_ids; without it the search spans every accessible team and can return one ticket per team for the same number.

maxDescriptionLength

integer<int32> | null

Optional. Shortens each returned description to at most this many characters and omits description_translations; 0 omits descriptions. Use Get Ticket for a ticket's full description.

Response

200 - application/json

Success

data

Ticket · object[]

Show child attributes

nextPageToken

string | null

Token for retrieving the next page of results. Empty if no more results.

Search Tickets

curl --request POST \
  --url https://public.api.serval.com/v2/tickets/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "teamIds": [
    "<string>"
  ],
  "assignedToUserIds": [
    "<string>"
  ],
  "requesterUserIds": [
    "<string>"
  ],
  "statusIds": [
    "<string>"
  ],
  "escalationLevels": [],
  "createdAfter": "2025-01-15T01:30:15.000Z",
  "createdBefore": "2025-01-15T01:30:15.000Z",
  "pageSize": 123,
  "pageToken": "<string>",
  "externalTicketKeys": [
    "<string>"
  ],
  "parentTicketIds": [
    "<string>"
  ],
  "ticketNumbers": [
    123
  ],
  "maxDescriptionLength": 123
}
'

import requests

url = "https://public.api.serval.com/v2/tickets/search"

payload = {
    "teamIds": ["<string>"],
    "assignedToUserIds": ["<string>"],
    "requesterUserIds": ["<string>"],
    "statusIds": ["<string>"],
    "escalationLevels": [],
    "createdAfter": "2025-01-15T01:30:15.000Z",
    "createdBefore": "2025-01-15T01:30:15.000Z",
    "pageSize": 123,
    "pageToken": "<string>",
    "externalTicketKeys": ["<string>"],
    "parentTicketIds": ["<string>"],
    "ticketNumbers": [123],
    "maxDescriptionLength": 123
}
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({
    teamIds: ['<string>'],
    assignedToUserIds: ['<string>'],
    requesterUserIds: ['<string>'],
    statusIds: ['<string>'],
    escalationLevels: [],
    createdAfter: '2025-01-15T01:30:15.000Z',
    createdBefore: '2025-01-15T01:30:15.000Z',
    pageSize: 123,
    pageToken: '<string>',
    externalTicketKeys: ['<string>'],
    parentTicketIds: ['<string>'],
    ticketNumbers: [123],
    maxDescriptionLength: 123
  })
};

fetch('https://public.api.serval.com/v2/tickets/search', 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/tickets/search",
  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([
    'teamIds' => [
        '<string>'
    ],
    'assignedToUserIds' => [
        '<string>'
    ],
    'requesterUserIds' => [
        '<string>'
    ],
    'statusIds' => [
        '<string>'
    ],
    'escalationLevels' => [
        
    ],
    'createdAfter' => '2025-01-15T01:30:15.000Z',
    'createdBefore' => '2025-01-15T01:30:15.000Z',
    'pageSize' => 123,
    'pageToken' => '<string>',
    'externalTicketKeys' => [
        '<string>'
    ],
    'parentTicketIds' => [
        '<string>'
    ],
    'ticketNumbers' => [
        123
    ],
    'maxDescriptionLength' => 123
  ]),
  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/tickets/search"

	payload := strings.NewReader("{\n  \"teamIds\": [\n    \"<string>\"\n  ],\n  \"assignedToUserIds\": [\n    \"<string>\"\n  ],\n  \"requesterUserIds\": [\n    \"<string>\"\n  ],\n  \"statusIds\": [\n    \"<string>\"\n  ],\n  \"escalationLevels\": [],\n  \"createdAfter\": \"2025-01-15T01:30:15.000Z\",\n  \"createdBefore\": \"2025-01-15T01:30:15.000Z\",\n  \"pageSize\": 123,\n  \"pageToken\": \"<string>\",\n  \"externalTicketKeys\": [\n    \"<string>\"\n  ],\n  \"parentTicketIds\": [\n    \"<string>\"\n  ],\n  \"ticketNumbers\": [\n    123\n  ],\n  \"maxDescriptionLength\": 123\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/tickets/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"teamIds\": [\n    \"<string>\"\n  ],\n  \"assignedToUserIds\": [\n    \"<string>\"\n  ],\n  \"requesterUserIds\": [\n    \"<string>\"\n  ],\n  \"statusIds\": [\n    \"<string>\"\n  ],\n  \"escalationLevels\": [],\n  \"createdAfter\": \"2025-01-15T01:30:15.000Z\",\n  \"createdBefore\": \"2025-01-15T01:30:15.000Z\",\n  \"pageSize\": 123,\n  \"pageToken\": \"<string>\",\n  \"externalTicketKeys\": [\n    \"<string>\"\n  ],\n  \"parentTicketIds\": [\n    \"<string>\"\n  ],\n  \"ticketNumbers\": [\n    123\n  ],\n  \"maxDescriptionLength\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public.api.serval.com/v2/tickets/search")

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  \"teamIds\": [\n    \"<string>\"\n  ],\n  \"assignedToUserIds\": [\n    \"<string>\"\n  ],\n  \"requesterUserIds\": [\n    \"<string>\"\n  ],\n  \"statusIds\": [\n    \"<string>\"\n  ],\n  \"escalationLevels\": [],\n  \"createdAfter\": \"2025-01-15T01:30:15.000Z\",\n  \"createdBefore\": \"2025-01-15T01:30:15.000Z\",\n  \"pageSize\": 123,\n  \"pageToken\": \"<string>\",\n  \"externalTicketKeys\": [\n    \"<string>\"\n  ],\n  \"parentTicketIds\": [\n    \"<string>\"\n  ],\n  \"ticketNumbers\": [\n    123\n  ],\n  \"maxDescriptionLength\": 123\n}"

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

{
  "data": [
    {
      "id": "<string>",
      "friendlyIdentifier": "<string>",
      "teamId": "<string>",
      "name": "<string>",
      "description": "<string>",
      "createdAt": "2025-01-15T01:30:15.000Z",
      "completedAt": "2025-01-15T01:30:15.000Z",
      "escalatedAt": "2025-01-15T01:30:15.000Z",
      "createdByUserId": "<string>",
      "assignedToUserId": "<string>",
      "requesterUserId": "<string>",
      "statusId": "<string>",
      "escalationLevel": "AI",
      "priorityId": "<string>",
      "slaStartedAt": "2025-01-15T01:30:15.000Z",
      "slaBreachesAt": "2025-01-15T01:30:15.000Z",
      "labelIds": [
        "<string>"
      ],
      "type": "TICKET_TYPE_UNSPECIFIED",
      "dueDate": {
        "year": 123,
        "month": 123,
        "day": 123
      },
      "isOverdue": true,
      "dueAt": "2025-01-15T01:30:15.000Z",
      "childTicketIds": [
        "<string>"
      ],
      "linkedTicketIds": [
        "<string>"
      ],
      "duplicateTicketIds": [
        "<string>"
      ],
      "dependsOnTicketIds": [
        "<string>"
      ],
      "parentTicketId": "<string>",
      "conversationThreadTicketIds": [
        "<string>"
      ],
      "conversationThreadParentTicketId": "<string>",
      "nameTranslations": {},
      "descriptionTranslations": {},
      "categoryOptionId": "<string>",
      "assignedToGroupId": "<string>",
      "url": "<string>",
      "statusName": "<string>"
    }
  ],
  "nextPageToken": "<string>"
}

Get started

Authentication

Endpoints

Development

Search Tickets

Authentication and permissions

Authorizations

Body

Response

​Authentication and permissions

Authorizations

Body

Response

Authentication and permissions