Services API
List services
List all services for an account:
GET /services
Response
Status: 200 OK
[
{
"name": "Conference Room",
"created_at": "2016-03-14T03:10:37-06:00",
"sourceID": null,
"updated_at": "2016-03-14T03:10:37-06:00",
"support_team": {
"name": "End-User Support, Houston",
"id": 9
},
"id": 10,
"disabled": false,
"provider": {
"name": "Widget Data Center, Internal IT",
"id": 32
}
},
{
"name": "Customer Relationship Management (Siebel)",
"created_at": "2016-03-14T03:10:37-06:00",
"sourceID": null,
"updated_at": "2016-03-14T03:10:37-06:00",
"support_team": {
"name": "Application Development",
"id": 7
},
"id": 11,
"disabled": false,
"provider": {
"name": "Widget Data Center, External IT",
"id": 30
}
},
"..."
]
The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of services.
Predefined Filters
The following predefined filters are available:
/services/disabled
: List all disabled services/services/enabled
: List all enabled services
Collection Fields
By default the following fields will appear in collections of services:
id
sourceID
name
provider
support_team
created_at
updated_at
Obtain a different set of fields using the ?fields= parameter.
Filtering
Filtering is available for the following fields:
id
source
sourceID
name
disabled
provider
support_team
created_at
updated_at
Sorting
By default a collection of services is sorted ascending by name
.
The following fields are accepted by the ?sort= parameter:
id
sourceID
name
provider
support_team
created_at
updated_at
Get a single service
GET /services/:id
Response
Status: 200 OK
{
"attachments": [],
"knowledge_manager": {
"id": 75,
"name": "Barney Turban",
"account": {
"id": "widget",
"name": "Widget International"
}
},
"availability_manager": {
"id": 75,
"name": "Barney Turban",
"account": {
"id": "widget",
"name": "Widget International"
}
},
"capacity_manager": {
"id": 75,
"name": "Barney Turban",
"account": {
"id": "widget",
"name": "Widget International"
}
},
"change_manager": {
"id": 212,
"name": "Grace Weller",
"account": {
"id": "widget",
"name": "Widget International"
}
},
"continuity_manager": {
"id": 353,
"name": "Luis Thomas",
"account": {
"id": "widget",
"name": "Widget International"
}
},
"created_at": "2017-05-21T18:34:09-05:00",
"description": "The Email service provides the ability to send email messages to, and receive emails from, email users within the organization and email users connected to the internet.",
"disabled": false,
"first_line_team": {
"id": 2,
"name": "Service Desk",
"account": {
"id": "virtualsupport",
"name": "VirtualSupport"
}
},
"id": 21,
"impact": "low",
"name": "Email",
"picture_uri": "https://itrp-demo-defaults.s3.amazonaws.com/avatars/services/original/email3.svg",
"problem_manager": {
"id": 75,
"name": "Barney Turban",
"account": {
"id": "widget",
"name": "Widget International"
}
},
"provider": {
"id": 44,
"name": "Widget Data Center, External IT",
"account": {
"id": "widget",
"name": "Widget International"
}
},
"release_manager": {
"id": 281,
"name": "Jo-Ann Stock",
"account": {
"id": "widget",
"name": "Widget International"
}
},
"service_category": {
"id": 8,
"name": "Communication",
"localized_name": "Communication"
},
"service_owner": {
"id": 281,
"name": "Jo-Ann Stock",
"account": {
"id": "widget",
"name": "Widget International"
}
},
"source": null,
"sourceID": null,
"support_team": {
"id": 15,
"name": "Windows Servers"
},
"updated_at": "2017-05-29T13:46:44-05:00",
"localized_description": "The Email service provides the ability to send email messages to, and receive emails from, email users within the organization and email users connected to the internet.",
"localized_name": "Email"
}
The response contains these fields.
Create a service
POST /services
When creating a new service these fields are available.
Response
Status: 201 Created
{
"availability_manager": "...",
"...": "..."
}
The response contains all fields of the created service and is similar to the response in Get a single service
Update a service
PATCH /services/:id
When updating a service these fields are available.
Response
Status: 200 OK
{
"availability_manager": "...",
"...": "..."
}
The response contains all fields of the updated service and is similar to the response in Get a single service
Fields
- attachments
- Readonly aggregated Attachments
- availability_manager
- Optional reference to Person — The Availability manager field is used to select the person who is responsible for ensuring that the availability targets specified in the active SLAs for the service are met.
- capacity_manager
- Optional reference to Person — The Capacity manager field is used to select the person who is responsible for ensuring that the service is not affected by incidents that are caused by capacity shortages.
- change_manager
- Optional reference to Person — The Change manager field is used to select the person who is responsible for coordinating the changes of the service.
- continuity_manager
- Optional reference to Person — The Continuity manager field is used to select the person who is responsible for creating and maintaining the continuity plans for the service’s instances that have an active SLA with a continuity target.
- created_at
- Readonly datetime — The date and time at which the service was created.
- custom_fields
- Optional custom fields — Custom fields provided in JSON format by the UI Extension that is linked to the service.
- custom_fields_attachments
- Writeonly attachments The attachments used in Custom fields.
- description
- Optional text (max 64KB) — The Description field is used to enter a high-level description of the service’s core functionality.
- description_attachments
- Writeonly attachments The attachments used in the Description field.
- disabled
- Optional boolean, default:
false
— The Disabled box is checked when the service may no longer be related to other records. - first_line_team
- Optional reference to Team — The First line team field is used to select the team that will, by default, be selected in the First line team field of a new service instance when it is being registered for the service.
- id
- Readonly integer — The unique ID of the service.
- impact
- Readonly enum — The Impact field shows the impact based on the highest impact of the affected SLAs for which the current user has read access. Valid values are:
-
low
: Low - Service Degraded for One Usermedium
: Medium - Service Down for One Userhigh
: High - Service Degraded for Several Userstop
: Top - Service Down for Several Users
- keywords
- Optional string (max 2048) — The Keywords field contains a comma-separated list of words that can be used to find the service via search.
- knowledge_manager
- Optional reference to Person — The Knowledge manager field is used to select the person who is responsible for the quality of the knowledge articles for the service.
- localized_description
- Readonly text (max 64KB) — Translated Description in the current language, defaults to
description
in case no translation is provided. - localized_keywords
- Readonly text (max 64KB) — Translated Keywords in the current language, defaults to
keywords
in case no translation is provided. - localized_name
- Readonly string (max 80) — Translated Name in the current language, defaults to
name
in case no translation is provided. - name
- Required string (max 80) — The Name field is used to enter the name of the service. The service name may be followed by the name of its core application placed between brackets.
- picture_uri
- Optional string — The hyperlink to the image file for the service.
- problem_manager
- Optional reference to Person — The Problem manager field is used to select the person who is responsible for coordinating the problems that directly affect the service.
- provider
- Required reference to Organization
- release_manager
- Optional reference to Person — The Release manager field is used to select the person who is responsible for coordinating the releases of the service.
- service_owner
- Optional reference to Person — The Service owner field is used to select the Person who is responsible for ensuring that the service level targets specified in the SLAs for the service are met.
- source
- Optional string (max 30) - See source
- sourceID
- Optional string (max 128) - See source
- support_team
- Optional reference to Team — The Support team field is used to select the team that will, by default, be selected in the Support team field of a service instance when one is registered for the service. Similarly, this team will be selected in the Team field of a Problem when the service is related to it.
- survey
- Optional reference to Survey — The Survey field is used to select the survey that will be presented to users to give their rating for this service.
- ui_extension
- Readonly reference to UI Extension — The UI extension field indicates the UI extension that is applied to the service.
- updated_at
- Readonly datetime — The date and time of the last update of the service. If the service has no updates it contains the
created_at
value.