Connect to External Ticket - Serval Documentation

POST

tickets

{ticket_id}

connect

Connect to External Ticket

curl --request POST \
  --url https://public.api.serval.com/v2/tickets/{ticket_id}/connect \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "channelTarget": {
    "email": {}
  },
  "externalTicketId": "<string>",
  "externalTicketData": {},
  "externalTicketSubtype": "<string>",
  "accountedForMessageIds": [
    "<string>"
  ]
}
'

import requests

url = "https://public.api.serval.com/v2/tickets/{ticket_id}/connect"

payload = {
    "channelTarget": { "email": {} },
    "externalTicketId": "<string>",
    "externalTicketData": {},
    "externalTicketSubtype": "<string>",
    "accountedForMessageIds": ["<string>"]
}
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({
    channelTarget: {email: {}},
    externalTicketId: '<string>',
    externalTicketData: {},
    externalTicketSubtype: '<string>',
    accountedForMessageIds: ['<string>']
  })
};

fetch('https://public.api.serval.com/v2/tickets/{ticket_id}/connect', 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/{ticket_id}/connect",
  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([
    'channelTarget' => [
        'email' => [
                
        ]
    ],
    'externalTicketId' => '<string>',
    'externalTicketData' => [
        
    ],
    'externalTicketSubtype' => '<string>',
    'accountedForMessageIds' => [
        '<string>'
    ]
  ]),
  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/{ticket_id}/connect"

	payload := strings.NewReader("{\n  \"channelTarget\": {\n    \"email\": {}\n  },\n  \"externalTicketId\": \"<string>\",\n  \"externalTicketData\": {},\n  \"externalTicketSubtype\": \"<string>\",\n  \"accountedForMessageIds\": [\n    \"<string>\"\n  ]\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/{ticket_id}/connect")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"channelTarget\": {\n    \"email\": {}\n  },\n  \"externalTicketId\": \"<string>\",\n  \"externalTicketData\": {},\n  \"externalTicketSubtype\": \"<string>\",\n  \"accountedForMessageIds\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public.api.serval.com/v2/tickets/{ticket_id}/connect")

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  \"channelTarget\": {\n    \"email\": {}\n  },\n  \"externalTicketId\": \"<string>\",\n  \"externalTicketData\": {},\n  \"externalTicketSubtype\": \"<string>\",\n  \"accountedForMessageIds\": [\n    \"<string>\"\n  ]\n}"

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

{}

{
  "message": "<string>",
  "detail": {
    "type": "<string>",
    "value": "<string>",
    "debug": {}
  }
}

Authorizations

Authorization

string

header

required

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

Path Parameters

ticket_id

string

required

The Serval ticket ID to connect

Body

application/json

channelTarget

Email · object

The channel containing the external ticket

Email
Slack Channel
Slack Dm
Ticket Source

Show child attributes

externalTicketId

string

The external ticket ID (format depends on the channel type):

For Slack (slack_channel or slack_dm): MUST be in the format "channelId:threadTs" Example: "C9DDYQ1B4:1779146751.061339" where channelId is the Slack channel ID (e.g., "C9DDYQ1B4") and threadTs is the Slack message timestamp (e.g., "1779146751.061339")
For Jira: the canonical format is "cloudId:projectId:issueId" (the ID Serval's Jira ingestion uses); a bare issue key or numeric issue ID is also accepted
For ServiceNow and other integrations: the sys_id or unique identifier from the external system This should be a globally unique identifier for the external ticket.

externalTicketData

external_ticket_data · object | null

Optional: Raw external ticket data/metadata to store with the connection. This should be the JSON-serialized external ticket object from the external system. For ServiceNow, this should be the RequestedItem or Incident object. For Jira, this should contain the issue with a non-empty key (e.g. {"issue": {"id": "10123", "key": "PROJ-42"}}); if omitted or missing the key, Serval fetches the issue from Jira and stores that snapshot in place of the provided data. If the issue cannot be resolved, the connection is still created with the provided data, but the ticket's "View in Jira" link will be unavailable until the ticket is reconnected with resolvable data. For other channel types, if not provided, external links may not display correctly.

Show child attributes

externalTicketSubtype

string | null

Optional: Subtype of the external ticket within the integration. For ServiceNow, use "incident" or "requested_item" to specify the type. This determines which sync handler is used for ongoing synchronization.

accountedForMessageIds

string[]

Optional: Serval message IDs on this ticket to register as already present in the external ticket's channel. Registered messages are skipped by the egresser, so they will not be re-sent to the external system after the connection is established. Use this when you have already posted a summary of the prior conversation to the external system and do not want the individual historical messages replayed on top of it. Each message must belong to this ticket.

Response

Success

The response is of type ConnectTicketToExternalTicketResponse · object.

Connect to External Ticket

curl --request POST \
  --url https://public.api.serval.com/v2/tickets/{ticket_id}/connect \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "channelTarget": {
    "email": {}
  },
  "externalTicketId": "<string>",
  "externalTicketData": {},
  "externalTicketSubtype": "<string>",
  "accountedForMessageIds": [
    "<string>"
  ]
}
'

import requests

url = "https://public.api.serval.com/v2/tickets/{ticket_id}/connect"

payload = {
    "channelTarget": { "email": {} },
    "externalTicketId": "<string>",
    "externalTicketData": {},
    "externalTicketSubtype": "<string>",
    "accountedForMessageIds": ["<string>"]
}
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({
    channelTarget: {email: {}},
    externalTicketId: '<string>',
    externalTicketData: {},
    externalTicketSubtype: '<string>',
    accountedForMessageIds: ['<string>']
  })
};

fetch('https://public.api.serval.com/v2/tickets/{ticket_id}/connect', 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/{ticket_id}/connect",
  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([
    'channelTarget' => [
        'email' => [
                
        ]
    ],
    'externalTicketId' => '<string>',
    'externalTicketData' => [
        
    ],
    'externalTicketSubtype' => '<string>',
    'accountedForMessageIds' => [
        '<string>'
    ]
  ]),
  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/{ticket_id}/connect"

	payload := strings.NewReader("{\n  \"channelTarget\": {\n    \"email\": {}\n  },\n  \"externalTicketId\": \"<string>\",\n  \"externalTicketData\": {},\n  \"externalTicketSubtype\": \"<string>\",\n  \"accountedForMessageIds\": [\n    \"<string>\"\n  ]\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/{ticket_id}/connect")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"channelTarget\": {\n    \"email\": {}\n  },\n  \"externalTicketId\": \"<string>\",\n  \"externalTicketData\": {},\n  \"externalTicketSubtype\": \"<string>\",\n  \"accountedForMessageIds\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public.api.serval.com/v2/tickets/{ticket_id}/connect")

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  \"channelTarget\": {\n    \"email\": {}\n  },\n  \"externalTicketId\": \"<string>\",\n  \"externalTicketData\": {},\n  \"externalTicketSubtype\": \"<string>\",\n  \"accountedForMessageIds\": [\n    \"<string>\"\n  ]\n}"

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

{}

{
  "message": "<string>",
  "detail": {
    "type": "<string>",
    "value": "<string>",
    "debug": {}
  }
}