Endpoints in the REST API v1.0

The BMC Helix Telco Extensions APIs provide a unified and standardized interface for managing critical service operations within telecom environments. These APIs provide a standardized interface for managing the full lifecycle of trouble tickets by supporting the creation and tracking of service-related issues.

BMC Helix Telco Extensions provides the following TMF621 Trouble Ticket API endpoints for creating trouble tickets and retrieving related information.

Before you begin

Users require the following permissions and roles to use the APIs:

Permissions required: Incident and Change Management permission.

Roles required: Incident management and Change Management roles.
Authentication: JWT authentication

Authentication

To request an authentication token

Endpoint

POST /api/rx/authentication/loginrequest

Parameters

Name	Required/Optional	Description	Type	Example	Notes
id	Required	Remedy Server user login account.	String	<your_user>	Locate this parameter in the request body. This parameter is not specified by default.
password	Required	Password.	String	<your_password>	Locate this parameter in the request body. This parameter is not specified by default.

Example request body

{
"userName": "<your_user>",
"password": "<your_password>"
}

Response

Response	Value	Notes
HTTP code	200	Application returns an authentication token that is valid for about half an hour.

POST Trouble Ticket

Create Trouble Ticket

Creates a new trouble ticket.

Endpoint

POST /api/com.bmc.dsm.netops-extensions/v1/troubleTicket

Required headers:

Content-Type:application/json
X-Requested-By:XMLHttpRequest

Path parameters

None

Query parameters

Fields description

Name	Type	Description
fields	String	Optional. Returns only the specified fields for each ticket in the list. Example. fields=status,severity

Request Body parameters

Fields description

Name	Type	Description
name	(String)	Title or summary of the trouble ticket.
description	(String)	Detailed description of the issue.
severity	(String)	Severity level of the issue.
company	(String)	The company to which the ticket belongs.
ticketType	(String)	The type of the ticket (e.g., Incident, Request, etc.).
status	(String)	Current status of the ticket.
requestedResolutionDate	(Datetime - ISO 8601)	Expected resolution date/time in ISO 8601, in double quotes (e.g., "2025-04-15T16:49:50.154Z").
channel	(Object)	Channel through which the ticket was raised.
├─ id	(String)	Identifier of the channel.
└─ name	(String)	Name of the channel.
relatedEntity	(Array of objects)	Entities related to this ticket such as alarms, assets, etc.
├─ role	(String)	Role of the related entity (e.g., "alarm", "asset", "Requested").
├─ @type	"RelatedEntity"	Type definition as per TMF621 model.
└─ entity	(Object)	Entity object with detailed attributes. Other attributes inside entity, such as name, href, alarmType, etc., are optional and may depend on the @referredType.
├─ id	(String)	Unique identifier of the related entity.
├─ name	(String)	Human-readable name of the entity.
└─ @referredType	(String)	Declares the type of entity being referred to. Supported values: "alarm", "asset", "sourceRequest".
relatedParty	(Array of objects)	Parties associated with the ticket.
├─ role	(String)	Role of the party (e.g., "Business", "Technician").
├─ @type	"RelatedPartyRefOrPartyRoleRef"	TMF model-specific type.
└─ partyOrPartyRole	(Object)	Reference to party or party role.
├─ id	(String)	Identifier of the person or group.
├─ name	(String)	Name of the person or group.
├─ @type	"PartyRef"	Declares the referenced object as a party.
└─ @referredType	(String)	Type of the referenced party. Supported values: "User", "Group".
note	(Array of objects)	Notes attached to the ticket.
├─ date	(Datetime - ISO 8601)	Noted date/time in ISO 8601, in double quotes (e.g., "2025-04-15T16:49:50.154Z").
├─ author	(String)	Author of the note.
└─ text	(String)	Content of the note.

Example request body

{
"name": "Petramco Simple Trouble ticket with all incident requred fields",
"description": "PPetramco Simple Trouble ticket with all incident requred fields",
"severity": "Medium",
"company": "Petramco",
"ticketType": "Incident",
"status": "Pending",
"requestedResolutionDate": "2025-05-17T05:09:14.000Z",
"channel": {
"id": "501",
"name": "Channel A"
},
"relatedEntity": [
  {
  "role": "alarm",
  "@type": "RelatedEntity",
  "entity": {
   "@referredType": "alarm",
   "href": "alarm link",
   "id": "1234",
   "name": "Network 402",
   "sourceSystemId": "Postman",
   "alarmType": "communicationsAlarm",
   "perceivedSeverity": "major",
   "probableCause": "cause in network cabel",
   "state": "Ack",
   "alarmRaisedTime": "2025-05-18T09:48:48Z",
   "alarmObjectType": "",
   "alarmDetails": "Fault in network - new alarm",
   "isRootCause": "Yes",
   "plannedOutageIndicator": "not set",
   "proposedRepairedActions": "check all wire connections",
   "reportingSystemId": "",
   "serviceAffecting": "Yes",
   "specificProblem": "not identified",
   "ackState": "",
   "ackSystemId": "",
   "ackUserId": "",
   "alarmEscalation": "Yes",
   "isPrimary": "True",
   "alarmChangedTime": "",
   "alarmClearedTime": "",
   "alarmReportingTime": "2025-05-17T09:48:48Z",
   "clearSystemId": "",
   "clearUserId": ""
   }
  },
  {
  "role": "asset",
  "@type": "RelatedEntity",
  "entity": {
   "id": "REGIIBOZBGFZTASMGHRQSMGHRQ3CYT",
   "name": "Network 401",
   "@type": "EntityRef",
   "@referredType": "asset"
   }
  },
  {
  "role": "Requested",
  "@type": "RelatedEntity",
  "entity": {
   "id": "90001",
   "name": "Dummy Source Request",
   "@type": "EntityRef",
   "@referredType": "sourceRequest"
   }
  }
],
"relatedParty": [
  {
  "role": "Business",
  "@type": "RelatedPartyRefOrPartyRoleRef",
  "partyOrPartyRole": {
   "id": "GPL000000000166",
   "name": "Sammy Adams",
   "@type": "PartyRef",
   "@referredType": "User"
   }
  },
  {
  "role": "Business",
  "@type": "RelatedPartyRefOrPartyRoleRef",
  "partyOrPartyRole": {
   "id": "GGP000000000020",
   "name": "GB Support 3",
   "@type": "PartyRef",
   "@referredType": "Group"
   }
  }
],
"note": [
  {
  "date": "2025-05-08T22:41:49.000Z",
  "author": "sadams",
  "text": "A Test note for testing - 01"
  }
]
}

Response

Response	Value	Notes
HTTP code	201	-
type	application/json	Not applicable.

Response example

{

"severity": "Medium",

"note": [

{

"date": "2025-05-08T22:41:49.000Z",

"author": "sadams",

"text": "A Test note for testing - 01"

{

"date": "2025-06-23T11:41:57.000Z",

"author": "ppan",

"text": "The Network 402 CI lookup process did not return any matches. Attach the correct instance of the CI to the request."

}

"@type": "TroubleTicket",

"relatedEntity": [

{

"entity": {

"name": "Dummy Source Request",

"@referredType": "SourceRequest",

"id": "90001",

"href": "/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1E7XSY1E7XHW70/sourceRequest/90001",

"@type": "EntityRef"

"@type": "RelatedEntity",

"role": "Requested"

{

"entity": {

"name": "Network 401",

"@referredType": "Asset",

"id": "REGIIBOZBGFZTASMGHRQSMGHRQ3CYT",

"href": "/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1E7XSY1E7XHW70/asset/REGIIBOZBGFZTASMGHRQSMGHRQ3CYT",

"@type": "EntityRef"

"@type": "RelatedEntity",

"role": "asset"

{

"entity": {

"name": "Network 402",

"@referredType": "Alarm",

"id": "1234",

"href": "/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1E7XSY1E7XHW70/alarm/1234",

"@type": "EntityRef"

"@type": "RelatedEntity",

"role": "alarm"

}

"channel": {

"@type": "ChannelRef",

"name": "Channel A",

"id": "501"

"description": "PPetramco Simple Trouble ticket with all incident requred fields",

"creationDate": "2025-06-23T11:41:57.000Z",

"relatedParty": [

{

"partyOrPartyRole": {

"@referredType": "User",

"name": "sadams",

"id": "GPL000000000166",

"href": "/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1E7XSY1E7XHW70/relatedParty/GPL000000000166"

"role": "Business",

"@type": "RelatedPartyRefOrPartyRoleRef"

{

"partyOrPartyRole": {

"@referredType": "Group",

"name": "GGP000000000020",

"id": "GGP000000000020",

"href": "/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1E7XSY1E7XHW70/relatedParty/GGP000000000020"

"role": "Business",

"@type": "RelatedPartyRefOrPartyRoleRef"

}

"lastUpdate": "2025-06-23T11:41:57.000Z",

"name": "Petramco Simple Trouble ticket with all incident requred fields",

"id": "AGGADGG8ECDC1ASY1E7XSY1E7XHW70",

"href": "https://is-hostname/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1E7XSY1E7XHW70",

"requestedResolutionDate": "2025-05-17T05:09:14.000Z",

"incidentNumber": "INC000000000003",

"status": "Assigned"

}

Adding custom fields via TMF621 REST APIs

You can use the TMF621 trouble ticket API (POST and GET operations) to include custom fields that reflect your organization’s operational needs. These fields enhance ticket metadata, enabling more effective automation, routing, and reporting.

To add custom fields

Add custom fields in BMC Helix ITSM.
Define the required fields in the BMC Helix ITSM backend forms by using Developer Studio. Make sure these fields are available in Smart IT views.

Supported field types:
- Character
- Selection
- date
- dateTime
- Time
- Boolean
- Integer or Number
  
  For more information, see the "To add custom fields to views" section in the Process of adding custom fields to Smart IT views in the BMC Helix ITSM online documentation.
Map the fields in BMC Helix Innovation Studio.
Map the defined fields to the appropriate record definitions in BMC Helix Innovation Studio to make sure they are available for API operations.

Available record definitions for Network Service Operations:
- TMF621 -V1- Related Party Mapping
- TMF621 -V1- Related Entity Mapping – Source Request
- TMF621 -V1- Related Entity Mapping – Alarm
- TMF621 -V1- Trouble Ticket – Incident Field Mapping
  
  For more information, see the Adding a field in the BMC Helix Innovation Studio record definition to map a custom field in the BMC Helix Multi-Cloud Broker online documentation.
Add the mapped fields to TMF621 API payloads.
After mapping, include the custom fields in the TMF621 REST API payloads.

Important
When you add custom fields via the TMF621 API, the GET operation will also retrieve the added custom fields.

TMF API custom fields

GET Trouble Ticket(s)

Retrieve a Trouble Ticket by ID

Returns the details of a specific trouble ticket identified by its ID.

Endpoint

GET /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}

Required headers:

Content-Type:application/json
X-Requested-By:XMLHttpRequest

Path parameters

Fields description

Name	Type	Description
id	String	Trouble Ticket Id

Query parameters

Fields description

Name	Type	Description
fields	String	Optional. Returns only the specified fields. Useful for partial responses. fields=id,status,relatedEntity
relatedEntityPageSize	String	Optional. Related Entities page size.
(none)	(no query param)	If fields are not provided, the full Trouble Ticket is returned including all populated fields (sub-resources may be limited for performance).

Request example

{{server}}/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC0ASVZS3FSVZS3F09Q3?fields=severity

Response

Response example

{
    "severity": "Low",
    "@type": "TroubleTicket",
    "id": "AGGADGG8ECDC0ASVZS3FSVZS3F09Q3",
    "href": "https://is-hostname/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC0ASVZS3FSVZS3F09Q3",
    "incidentNumber": "INC000000000124"
}

Response	Value	Notes
HTTP code	200	-
type	application/json	Not applicable.

Get a list of Trouble Tickets

Returns the list of trouble tickets.

Endpoint

GET /api/com.bmc.dsm.netops-extensions/v1/troubleTicket

Required headers:

Content-Type:application/json
X-Requested-By:XMLHttpRequest

Path parameters

None

Query parameters

Fields description

Name	Type	Description
fields	String	Optional. Returns only the specified fields for each ticket in the list. Example. fields=status,severity
offset	String	Optional. Skips the first n results. Used for pagination. Example. offset=0
limit	String	Optional. Limits the number of tickets returned. Example. limit=50
attribute=value	String	Optional. Filters tickets by status. Attribute filtering applies to first-level fields. See "TMF630_REST_API_Design_Guidelines_Part1_v4", section 4.3. Query partial Resource representation or attribute selection for details. Example. severity=High

Notes:

Filtering is based on name=value query parameters.
Multiple filters are ANDed together.
OR logic is supported by using:
- Comma-separated values: severity=High,Low

Request example - GET with Attribute filtering and pagination

{{server}}/api/com.bmc.dsm.netops-extensions/v1/troubleTicket?severity=High,Low&offset=0&limit=10

This request retrieves Trouble Tickets where the severity is either High or Low, and applies pagination by using offset and limit.

Response

Response example

[
{
  "severity": "Low",
  "note": [],
  "@type": "TroubleTicket",
  "description": "This is incident 2",
  "creationDate": "2023-05-02T09:03:01.000Z",
  "relatedParty": [],
  "lastUpdate": "2023-05-10T12:11:04.000Z",
  "name": "Outlook Web App connectivity (External) transaction failures.",
  "company": "Petramco",
  "id": "IDGDTQ9WI25NDARUAXENRUAXEN7GNE",
  "href": "https://is-hostname/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/IDGDTQ9WI25NDARUAXENRUAXEN7GNE",
  "incidentNumber": "INC999000000002",
  "status": "acknowledged"
},
{
  "severity": "High",
  "note": [],
  "@type": "TroubleTicket",
  "channel": {
   "@type": "ChannelRef",
   "name": "Demo Channel",
   "id": "666"
  },
  "description": "Includes related entities (alarm, asset, source request), related parties and notes",
  "creationDate": "2025-05-07T12:59:57.000Z",
  "relatedParty": [],
  "lastUpdate": "2025-05-07T13:00:00.000Z",
  "name": "Trouble ticket with all fields and array types",
  "company": "Petramco",
  "id": "AGGADGG8ECDC0ASVWGRXSVWGRXD6SX",
  "href": "https://is-hostname/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC0ASVWGRXSVWGRXD6SX",
  "incidentNumber": "INC000000000120",
  "status": "acknowledged"
}
]

Response	Value	Notes
Status Code	200	-
content-type	application/json	-
X-Total-Count	62	The total number of matching records available on the server, regardless of how many were returned in the current response.
X-Result-Count	2	The number of items actually returned in the current API response.

Get Trouble Ticket related parties

Returns the details about related parties associated with a trouble ticket.

Endpoint

GET /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}/relatedParty/{relatedPartyId}

Required headers:

Content-Type:application/json
X-Requested-By:XMLHttpRequest

Path parameters

Fields description

Name	Type	Description
id	String	Trouble Ticket Id
relatedPartyId	String	Related Party Id

Query parameters

None

Request example

{{server}}/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1E7XSY1E7XHW70/relatedParty/GGP000000000020

This request retrieves a Trouble Ticket Related Party.

Response

Response example

{
"partyOrPartyRole": {
  "@referredType": "Group",
  "name": "GGP000000000020",
  "id": "GGP000000000020",
  "href": "/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1E7XSY1E7XHW70/relatedParty/GGP000000000020"
},
"role": "Business",
"@type": "RelatedPartyRefOrPartyRoleRef"
}

Response	Value	Notes
Status Code	200	-
content-type	application/json	-

Get Trouble Ticket related entities

Returns details of entities linked to a trouble ticket.

Endpoint

GET /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}/relatedEntity

Required headers:

Content-Type:application/json
X-Requested-By:XMLHttpRequest

Path parameters

Fields description

Name	Type	Description
id	String	Trouble Ticket Id

Query parameters

Fields description

Name	Type	Description
entityType	String	Optional. The entityType query parameter can be used to filter related entities by their type. It supports multiple values, by using comma-separated format for OR filtering. Supported entity types: Alarm, Asset, SourceRequest Example. entityType=Alarm,Asset
offset	Integer	Optional. Skips the first n results. Used for pagination. Example. offset=0
limit	Integer	Optional. Limits the number of tickets returned. Example. limit=50

Request example - GET with Attribute filtering and pagination

{{server}}/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASU9MHSSU9MHSS9V7/relatedEntity?offset=0&limit=5&entityType=Alarm,Asset,SourceRequest

This request retrieves a paged list of related entities linked to a specific Trouble Ticket, filtered by entity type, and applies pagination by using offset and limit.

Response

Response example

Response	Value	Notes
Status Code	200	-
content-type	application/json	-
X-Total-Count	62	The total number of matching records available on the server, regardless of how many were returned in the current response.
X-Result-Count	2	The number of items actually returned in the current API response.

Get Trouble Ticket notes

Returns notes or comments added to a trouble ticket.

Endpoint

GET /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}/note

Required headers:

Content-Type:application/json
X-Requested-By:XMLHttpRequest

Path parameters

Fields description

Name	Type	Description
id	String	Trouble Ticket Id

Query parameters

None

Request example

{{server}}/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1TK6SY1TK60J3U/note

This request retrieves Trouble Ticket notes.

Response

Response example

[
{
"date": "2025-05-08T22:41:49.000Z",
"author": "pbunyon",
"text": "A Test note for testing."
}
]

Response	Value	Notes
Status Code	200	-
content-type	application/json	-

Get Trouble Ticket alarm

Returns alarm information associated with a trouble ticket.

Endpoint

GET /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}/alarm/{alarmId}

Required headers:

Content-Type:application/json
X-Requested-By:XMLHttpRequest

Path parameters

Fields description

Name	Type	Description
id	String	Trouble Ticket Id
alarmId	String	Alarm Id

Query parameters

None

Request example

{{server}}/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1BSGSY1BSGHM5W/alarm/1234

This request retrieves a Trouble Ticket alarm.

Response

Response example

{
"reportingSystemId": "",
"alarmRaisedTime": "2025-05-18T09:48:48Z",
"alarmClearedTime": "",
"@type": "Alarm",
"proposedRepairedActions": "check all wire connections",
"alarmReportingTime": "2025-05-17T09:48:48Z",
"alarmEscalation": false,
"alarmChangedTime": "",
"perceivedSeverity": "major",
"probableCause": "cause in network cabel",
"isPrimary": false,
"ackSystemId": "",
"state": "Ack",
"id": "1234",
"href": "/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1BSGSY1BSGHM5W/alarm/1234",
"clearSystemId": "",
"isRootCause": false,
"ackUserId": "",
"sourceSystemId": "Postman",
"serviceAffecting": false,
"clearUserId": "",
"ackState": "",
"alarmType": "communicationsAlarm",
"alarmObjectType": "",
"specificProblem": "not identified",
"name": "Network 402",
"plannedOutageIndicator": "not set",
"alarmDetails": "Fault in network - new alarm"
}

Response	Value	Notes
Status Code	200	-
content-type	application/json	-

Get Trouble Ticket source request

Returns the original request or event that triggered the creation of the trouble ticket.

Endpoint

GET /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}/sourceRequest/{sourceRequestId}

Required headers:

Content-Type:application/json
X-Requested-By:XMLHttpRequest

Path parameters

Fields description

Name	Type	Description
id	String	Trouble Ticket Id
sourceRequestId	String	Source Request Id

Query parameters

Fields description

Name	Type	Description
fields	String	Optional. Returns only the specified fields for each ticket in the list. Example. fields=customField

Request example

{{server}}/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1BNBSY1BNBHLRG/sourceRequest/REHAA5V0GQBORANBH63AI85CJ2JMLY

This request retrieves a Trouble Ticket source request.

Response

Response example

{
"@referredType": "SourceRequest",
"@type": "relatedEntity",
"name": "632XF1S",
"id": "REHAA5V0GQBORANBH63AI85CJ2JMLY",
"href": "/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1BNBSY1BNBHLRG/sourceRequest/REHAA5V0GQBORANBH63AI85CJ2JMLY"
}

Response	Value	Notes
Status Code	200	-
content-type	application/json	-

Get Trouble Ticket asset

Returns asset details related to a trouble ticket.

Endpoint

GET /api/com.bmc.dsm.netops-extensions/v1/troubleTicket/{id}/asset/{assetId}

Required headers:

Content-Type:application/json
X-Requested-By:XMLHttpRequest

Path parameters

Fields description

Name	Type	Description
id	String	Trouble Ticket Id
assetId	String	Asset Id

Query parameters

Fields description

Name	Type	Description
fields	String	Optional. Returns only the specified fields for each ticket in the list. Example. fields=customField

Request example

{{server}}/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1UVOSY1UVO03Z0/asset/REHAA5V0GQBORANBH631IKTA4IJMQ1

This request retrieves a Trouble Ticket asset.

Response

Response example

{
"role": "asset",
"type": "RelatedEntity",
"entity": {
"referredType": "Asset",
"createdDate": "2025-06-23T21:11:48.000Z",
"name": "1LLZ6BS",
"href": "/api/com.bmc.dsm.netops-extensions/v1/troubleTicket/AGGADGG8ECDC1ASY1UVOSY1UVO03Z0/asset/REHAA5V0GQBORANBH631IKTA4IJMQ1",
"id": "REHAA5V0GQBORANBH631IKTA4IJMQ1",
"displayId": "000000000000025",
"type": "EntityRef"
}
}

Response	Value	Notes
Status Code	200	-
content-type	application/json	-

Endpoints in the REST API v1.0

Before you begin

Authentication

To request an authentication token

Endpoint

Parameters

Response

POST Trouble Ticket

Create Trouble Ticket

Endpoint

Path parameters

Query parameters

Request Body parameters

Response

Adding custom fields via TMF621 REST APIs

To add custom fields

GET Trouble Ticket(s)

Retrieve a Trouble Ticket by ID

Endpoint

Path parameters

Query parameters

Response

Get a list of Trouble Tickets

Endpoint

Path parameters

Query parameters

Response

Get Trouble Ticket related parties

Endpoint

Path parameters

Query parameters

Response

Get Trouble Ticket related entities

Endpoint

Path parameters

Query parameters

Response

Get Trouble Ticket notes

Endpoint

Path parameters

Query parameters

Response

Get Trouble Ticket alarm

Endpoint

Path parameters

Query parameters

Response

Get Trouble Ticket source request

Endpoint

Path parameters

Query parameters

Response

Get Trouble Ticket asset

Endpoint

Path parameters

Query parameters

Response

BMC Helix Telco Extensions 25.3

On this page