The platform REST API references

You can use the POST method to create and update records such as incidents, change requests, problem investigations, and service requests in BMC Helix ITSM. BMC Helix ITSM provides the following interface forms that you can use for integrating with third-party applications:

Interface form	Purpose
HPD:IncidentInterface_Create	To create an incident
HPD:IncidentInterface	To search, read, or update an existing incident
PBM:ProblemInterface_Create	To create a problem investigation
CHG:ChangeInterface_Create	To create a change request
CHG:ChangeInterface	To update an existing change request
CHG:WorkLog	To update work info of a change request
HPD:WorkLog	To update work info of an incident
TMS:TaskInterface	To update tasks and work information
CHG:Associations	To associate a CI to a change request

For information related to authentication and endpoints, see Endpoints in AR REST API and Access and authentication for the REST API in AR System documentation.

To use the REST API to create an incident

Request URL: http://serverName:port/api/arsys/v1/entry/HPD:IncidentInterface_Create?fields=values(Incident Number)

Operation: POST

Result: An incident is created, and an incident ID is returned.

JSON to create an incident

{
"values": {
   "First_Name": "Allen",
   "Last_Name": "Allbrook",
   "Description": "REST API: Incident Creation",
   "Impact": "1-Extensive/Widespread",
   "Urgency": "1-Critical",
   "Status": "Assigned",
   "Reported Source": "Direct Input",
   "Service_Type": "User Service Restoration"
}
}

To use the REST API to create a change request

Request URL: http://serverName:port/api/arsys/v1/entry/CHG:ChangeInterface_Create

Operation: POST

Result: A change request is created.

JSON to create an incident

{
"values": {
   "First Name": "Paul",
   "z1D_Action": "CREATE",
   "Last Name": "Bunyon",
   "Description": "REST API: Change Creation",
   "Impact": "1-Extensive/Widespread",
   "Urgency": "1-Critical",
   "Risk Level": "Risk Level 3",
   "Status": "Draft",
   "Company": "Petramco",
   "Location Company": "Petramco",
   "Change Type": "Project",
   "Change Timing": "Standard"
}
}

To use the REST API to create a problem investigation

Request URL: http://serverName:port/api/arsys/v1/entry/PBM:ProblemInterface_Create?fields=values(Problem Investigation ID)

Operation: POST

Result: A problem investigation is created, and a problem investigation ID is returned.

Type of problem record	z1D_Action
Problem Investigation	"z1D_Action":"PROBLEM"
Solution Database	“z1D_Action” :"SOLUTION"
Known Error	“z1D_Action” : "KNOWNERROR"

JSON to create a problem investigation

{
"values": {"Status" : "Draft",
"Investigation Driver": "High Impact Incident",
"Last Name":"Allbrook",
"First Name":"Allen",
"Assigned Group Pblm Mgr":"Backoffice Support",
"Investigation Justification":"",
"Company":"Calbro Services",
"Description":"REST API Test problem creation",
"z1D_Action":"PROBLEM",
"Impact":"2-Significant/Large",
"Urgency":"2-High"}
}

JSON to create a known error

{
"values": {"Known Error Status": "Assigned",
"Company":"Petramco",
"Contact Company":"Petramco",
"Description":"REST API Test Known Error creation",
"Detailed Description" : "REST API Test Known Error creation Notes",
"View Access": "Internal",
"Target Resolution Date": "2021-03-24T18:30:00.000+0000",
"z1D_Action":"KNOWNERROR",
"Urgency": "2-High",
"Impact": "2-Significant/Large"}
}

To use the REST API to create a change request

Request URL: http://serverName:port/api/arsys/v1/entry/CHG:ChangeInterface_Create

Operation: POST

Result: A change request is created.

JSON to create an incident

{
"values": {
   "First Name": "Paul",
   "z1D_Action": "CREATE",
   "Last Name": "Bunyon",
   "Description": "REST API: Change Creation",
   "Impact": "1-Extensive/Widespread",
   "Urgency": "1-Critical",
   "Risk Level": "Risk Level 3",
   "Status": "Draft",
   "Company": "Petramco",
   "Location Company": "Petramco",
   "Change Type": "Project",
   "Change Timing": "Standard"
}
}

To use the REST API to create a task related to an incident

Request URL: http://<arserver_name>:8008/api/arsys/v1/entry/TMS:Task

Operation: POST

Result: A task is created and is associated to the incident.

JSON to create a task related to an incident

{"values":
{
"TaskName": "Task RESTAPI",
"Summary": "Task Inc",
"TaskType": "Manual",
"Status": "Pending",
"Location Company": "Calbro Services",
"RootRequestName": "INC_CAL_1000015",
"RootRequestID": "INC_CAL_1000015",
"RootRequestInstanceID": "AG00123F73CF5Eqc4TSQvOExAgYUQB",
"Company": "Calbro Services",
"First Name": "Ian",
"Last Name": "Plyment",
"Customer Company": "Calbro Services",
"Customer First Name": "Mary",
"Customer Last Name": "Mann",
"RootRequestMode": "0",
"RootRequestFormName": "HPD:Help Desk"
}
}

To use the REST API to create a service request

Request URL: http://<servername>:<port>/api/arsys/v1/entry/SRM:RequestInterface_Create

Operation: POST

Result: A service request is created.

The Source Keyword field on SRM:Request form has the following values:

Source of a service request	Source Keyword
Incident Management	IM
Workorder Management	WO
Change Management	CM
Request Entry console	blank

JSON to create a service request

{
   "values": {

       "z1D Action": "CREATE",
       "Source Keyword": "Test",
       "TitleInstanceID": "SR005056B551A03T5GSw6d6ccAIn4E",
       "First Name": "Allen",
       "Last Name": "Allbrook",
       "Customer First Name": "Bob",
       "Customer Last Name": "Baxter",
       "OfferingTitle": "REST API TEST SRM Request 1",
       "Short Description": "REST API TEST SRM Request 1",
       "Status": "Submitted",
       "Company": "Calbro Services",
       "Customer Company": "Calbro Services",
       "Location Company": "Calbro Services"
   }
}

To use the REST API to create a work log entry for an incident

Request URL: http://<arserver_name>:8008/api/ arsys/v1/mergeEntry/HPD:WorkLog

Operation: POST

Result: A work log is created and associated to the incident.

JSON to create a work log entry for an incident

{
"values": {
"Submitter": "Allen",
"Short Description": "New activity log from REST API",
"Assignee Groups": "1000000005;",
"Description": "New activity log from REST API",
"Detailed Description": "New activity log from REST API",
"Work Log Submitter": "Allen",
"Incident Number": "INC000000000701",
"Work Log Type": "General Information"
},
   "mergeOptions" : {
       "ignorePatterns" : false,
       "ignoreRequired" : false,
       "workflowEnabled" : false,
       "associationsEnabled" : false,
       "mergeType" : "DUP_NEW_ID",
       "multimatchOption" : 1
   },
   "qualification" : "'Incident Number' = \"INC000000000701\""
}

To retrieve an incident entry

Request URL: http://serverName:port/api/arsys/v1/entry/HPD:IncidentInterface_Create/incidentNumber

Operation: GET

For more information, see Example-of-using-the-platform-REST-API-to-retrieve-an-incident-entry.

To retrieve work information related to an incident

Request URL: http://serverName/api/arsys/v1/entry/HPD:Help Desk

Operation: GET

For more information, see Example-of-using-the-platform-REST-API-to-retrieve-work-information-related-to-an-incident.

To modify an incident entry

Request URL: http://serverName:port/api/arsys/v1/entry/HPD:IncidentInterface/RequestIDOfAnIncidentOnHPD:IncidentInterface

Operation: PUT

Result: The incident status is updated.

JSON to modify an incident entry

{
"values": {
"Description" : "Rest API: Resolve Incident using Rest
API",
"Status" : "Resolved",
"Status_Reason" : "Future Enhancement",
"Resolution" : "Resolve through Rest API"
}
}

The platform REST API references

To use the REST API to create an incident

To use the REST API to create a change request

To use the REST API to create a problem investigation

To use the REST API to create a change request

To use the REST API to create a task related to an incident

To use the REST API to create a service request

To use the REST API to create a work log entry for an incident

To retrieve an incident entry

To retrieve work information related to an incident

To modify an incident entry

On this page