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:

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 User
  • medium: Medium - Service Down for One User
  • high: High - Service Degraded for Several Users
  • top: 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.