Skip to main content
POST
Connect to External Ticket

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

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:issueId" (the ID Serval's Jira ingestion uses); a bare issue key or numeric issue ID is also accepted, as is the legacy "cloudId:projectId:issueId" form
  • 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

Struct represents a structured data value, consisting of fields which map to dynamically typed values. In some languages, Struct might be supported by a native representation. For example, in scripting languages like JS a struct is represented as an object. The details of that representation are described together with the proto support for the language.

The JSON representation for Struct is JSON object.

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

200 - application/json

Success

The response is of type ConnectTicketToExternalTicketResponse · object.