Service Instances API

List service instances

List all service instances for an account:

GET /service_instances

Response

Status: 200 OK
[
  {
    "name": "Amsterdam Network",
    "created_at": "2016-03-14T03:10:38-06:00",
    "sourceID": null,
    "updated_at": "2016-03-14T03:10:38-06:00",
    "service": {
      "name": "Network Connectivity",
      "id": 20,
      "provider": {
        "name": "Widget Data Center, External IT",
        "id": 30
      }
    },
    "support_team": {
      "name": "Operations",
      "id": 11
    },
    "id": 23,
    "status": "in_production"
  },
  {
    "name": "AT&T Smart Phone for Widget Data Center, External IT",
    "created_at": "2016-03-14T03:10:39-06:00",
    "sourceID": null,
    "updated_at": "2016-03-14T03:11:39-06:00",
    "service": {
      "name": "Smart Phone",
      "account": {
        "name": "Widget North America",
        "id": "wna"
      },
      "id": 45,
      "provider": {
        "name": "Widget North America, Information Technology",
        "account": {
          "name": "Widget North America",
          "id": "wna"
        },
        "id": 45
      }
    },
    "account": {
      "name": "Widget North America",
      "id": "wna"
    },
    "support_team": {
      "name": "End-User Support, Chicago",
      "account": {
        "name": "Widget North America",
        "id": "wna"
      },
      "id": 16
    },
    "id": 133,
    "status": "in_production"
  },
  "..."
]

The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of service instances.

States

The following states are available:

Collection Fields

By default the following fields will appear in collections of service instances:

id sourceID name status service support_team created_at updated_at

Obtain a different set of fields using the ?fields= parameter.

Sorting

By default a collection of service instances is sorted ascending by name.

The following fields are accepted by the ?sort= parameter:

id sourceID name status service support_team created_at updated_at

Get a single service instance

GET /service_instances/:id

Response

Status: 200 OK
{
  "name": "ITRP Production",
  "remarks": null,
  "created_at": "2016-03-14T03:10:38-06:00",
  "sourceID": null,
  "updated_at": "2016-03-14T03:10:53-06:00",
  "service": {
    "name": "IT Resource Planning (ITRP)",
    "account": {
      "name": "ITRP Institute",
      "id": "itrp"
    },
    "id": 1,
    "provider": {
      "name": "ITRP Institute, Inc.",
      "account": {
        "name": "ITRP Institute",
        "id": "itrp"
      },
      "id": 1
    }
  },
  "account": {
    "name": "ITRP Institute",
    "id": "itrp"
  },
  "support_team": {
    "name": "Service Desk",
    "account": {
      "name": "ITRP Institute",
      "id": "itrp"
    },
    "id": 1
  },
  "id": 1,
  "status": "in_production",
  "source": null
}

The response contains these fields.

Create a service instance

POST /service_instances

When creating a new service instance these fields are available.

Response

Status: 201 Created
{
  "created_at": "...",
  "...": "..."
}

The response contains all fields of the created service instance and is similar to the response in Get a single service instance

Update a service instance

PATCH /service_instances/:id

When updating a service instance these fields are available.

Response

Status: 200 OK
{
  "created_at": "...",
  "...": "..."
}

The response contains all fields of the updated service instance and is similar to the response in Get a single service instance

Fields

created_at
Readonly datetime — The date and time at which the service instance was created.
first_line_team
Optional reference to Team — The First line team field is used to select the team that will automatically be selected in the Team field of requests to which the service instance is linked after they have been submitted using Self Service or when they are generated using the Requests API, Mail API or Events API.
id
Readonly integer — The unique ID of the service instance.
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
name
Required string (max 80) — The Name field is used to enter the name of the service instance.
remarks
Optional text (max 64KB)
service
Required reference to Service — The Service field is used to select the Service which functionality the service instance provides.
source
Optional string (max 30) - See source
sourceID
Optional string (max 128) - See source
status
Optional enum, default: being_prepared — The Status field is used to select the current status of the service instance. Valid values are:
  • being_prepared: Being Prepared
  • in_production: In Production
  • discontinued: Discontinued
support_team
Optional reference to Team — The Support team field is used to select the team that will, by default, be selected in the Team field of a request when the service instance is manually selected in the Service instance field of the request, or when the service instance is applied from the Service Hierarchy Browser.
updated_at
Readonly datetime — The date and time of the last update of the service instance. If the service instance has no updates it contains the created_at value.