Requests API

List requests

List all requests for an account:

GET /requests

Response

Status: 200 OK
[
  {
    "service_instance": {
      "name": "Windows for Sales Tracking Production",
      "id": 126
    },
    "completed_at": null,
    "created_at": "2016-03-14T02:56:11-06:00",
    "category": "rfc",
    "sourceID": null,
    "updated_at": "2016-03-14T03:14:11-06:00",
    "grouped_into": null,
    "member": {
      "name": "Barney Turban",
      "id": 58
    },
    "subject": "Add memory to Sales Tracking production server cluster",
    "id": 70470,
    "impact": null,
    "team": {
      "name": "Windows Servers",
      "id": 14
    },
    "status": "assigned",
    "next_target_at": "best_effort"
  },
  "..."
]

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

States

The following states are available:

Collection Fields

By default the following fields will appear in collections of requests:

id sourceID subject category impact status next_target_at completed_at team member grouped_into service_instance created_at updated_at

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

Sorting

By default a collection of requests is sorted descending by id.

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

id sourceID subject category impact status next_target_at completed_at team member service_instance created_at updated_at

List requests relevant for API user

List all requests which requested by person or requested for person is the API user:

GET /requests/requested_by_or_for_me

List all requests which requested for person belonged to the same organization as the API user at the time the request was created:

GET /requests/requests_of_my_organization

List all requests that are assigned to one of the teams that the API user is a member of:

GET /requests/assigned_to_my_team

List all requests that are assigned to the API user:

GET /requests/assigned_to_me

List all requests which requested by person is the API user and which status is ‘Waiting for Customer’:

GET /requests/waiting_for_me

List all requests that were completed less than 6 months ago and which are linked to a service instance of a service for which the API user is the problem manager:

GET /requests/problem_management_review

Response

The response is similar to the response in List requests

Get a single request

GET /requests/:id

Response

Status: 200 OK
{
  "service_instance": {
    "name": "Data Center Rack Space",
    "id": 29
  },
  "organization": {
    "id": 44,
    "name": "Widget Data Center, External IT"
  },
  "completion_reason": "solved",
  "completed_at": "2014-03-04T02:14:00-06:00",
  "desired_completion_at": "2014-03-04T03:00:00-06:00",
  "requested_by": {
    "name": "Patrick Spratt",
    "id": 56
  },
  "created_by": {
    "name": "Patrick Spratt",
    "id": 56
  },
  "created_at": "2009-02-02T12:18:00-06:00",
  "category": "rfc",
  "sourceID": null,
  "downtime_start_at": null,
  "updated_at": "2016-03-14T03:14:13-06:00",
  "supplier": null,
  "resolution_target_at": null,
  "requester_resolution_target_at": null,
  "new_assignment": false,
  "grouping": "none",
  "grouped_into": null,
  "member": {
    "name": "Carla Cluster",
    "id": 54
  },
  "supplier_requestID": null,
  "subject": "Add new rack in data center",
  "response_target_at": null,
  "id": 68673,
  "requested_for": {
    "name": "Patrick Spratt",
    "id": 56
  },
  "problem": null,
  "change": {
    "id": 238,
    "subject": "Install new rack"
  },
  "project": null,
  "ci": null,
  "downtime_end_at": null,
  "impact": null,
  "team": {
    "name": "Unix Servers",
    "id": 13
  },
  "status": "completed",
  "source": "self service",
  "next_target_at": "no_target",
  "template": null,
  "custom_data": null,
  "waiting_until": null,
  "reviewed": true,
  "satisfaction": "satisfied",
  "knowledge_article": null,
  "urgent": false,
  "addressed": false
}

The response contains these fields.

Create a request

POST /requests

When creating a new request these fields are available.

Requests can also be created using the Mail API. In addition, a specific Events API is available to support monitoring tools that prefer sending HTTP requests rather than email.

Response

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

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

Update a request

PATCH /requests/:id

When updating a request these fields are available.

Response

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

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

Fields

addressed
Optional boolean, default: false — When the Satisfaction field of the request is set to ‘Dissatisfied’, a person who has the Service Desk Manager role, can check the Addressed box to indicate that the requester has been conciliated.
assignment_count_
Readonly integer — The Assignment count field is automatically set to the number of times that the Team field of the request has been set to a Team that is registered in the Account from which the request data is retrieved.
category
Required enum — The Category field is used to select the category of the request. Valid values are:
  • incident: Incident - Request for Incident Resolution
  • rfc: RFC - Request for Change
  • rfi: RFI - Request for Information
  • complaint: Complaint - Request for Support Improvement
  • compliment: Compliment - Request for Bestowal of Praise
  • other: Other - Request is Out of Scope
change
Optional reference to Change — The Change field is used to link the request to a change.
ci
Optional reference to Configuration Item — The Configuration item field is used to relate a CI to the request. When this field is used to update an existing request, all configuration items that are linked to this request will be replaced by the new configuration item.

Multiple configuration items can be added to, or removed from, a request using the Requests - Configuration Items API.

completed_at
Readonly datetime — The Completed at field is automatically set to the date and time at which the request is saved with the status “Completed”.
completion_reason
Optional enum — The Completion reason field is used to select the appropriate completion reason for the request when it has been completed. Valid values are:
  • solved: Solved - Root Cause Analysis Not Required
  • workaround: Workaround - Root Cause Not Removed
  • gone: Gone - Unable to Reproduce
  • withdrawn: Withdrawn - Withdrawn by Requester
  • conflict: Conflict - In Conflict with Internal Standard or Policy
  • unsolvable: Unsolvable - Unable to Solve
created_at
Readonly datetime — The date and time at which the request was created.
created_by
Required reference to Person — The Created by field is automatically set to the person who submitted the request.
custom_data
Optional hash — Custom data provided in JSON format by the UI Extension that is linked to the related request template.
downtime_end_at
Optional datetime — The Downtime end field is used to specify the actual date and time at which the service became available again.
downtime_start_at
Optional datetime — The Downtime start field is used to specify the actual date and time at which the service outage started.
desired_completion_at
Optional datetime — The Desired completion field can be set to the date and time that has been agreed on for the completion of the request. The desired completion overwrites the automatically calculated resolution target of any affected SLA that is related to the request when the desired completion is later than the affected SLA’s resolution target. By default, the person selected in the Requested by field receives a notification based on the ‘Desired Completion Set for Request’ email template whenever the value in the Desired completion field is set, updated or removed.
grouped_into
Optional reference to Request — The Grouped into field displays the request group that is used to group the requests that have been submitted for the resolution of exactly the same incident, for the implementation of exactly the same change, for the provision of exactly the same information, etc.
grouping
Readonly enum, default: none — Valid values are:
  • none: None
  • group: Group
  • grouped: Grouped
id
Readonly integer — The unique ID of the request.
impact
Optional enum — The Impact field is used to select the extent to which the service instance is impacted. 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
internal_note
Optional text (max 64KB) — The Internal note field is used to provide information that is visible only for people who have the Auditor, Specialist or Account Administrator role of the account for which the internal note is intended. The X-ITRP-Account header can be included in an API PATCH request to add an internal note for a specific account (see Multiple Accounts).
knowledge_article
Optional reference to Knowledge Article — The Knowledge Article field is automatically set to the latest knowledge article that was applied to the request.
member
Optional reference to Person — The Member field is used to select the person to whom the request is to be assigned.
new_assignment
Readonly boolean, default: true — The New assignment field is set to true when the request’s status is ‘Assigned’ or ‘Declined’.
next_target_at
Readonly datetime — The Next target field value is empty when the status of the request is ‘Completed’. The next target equals the response target when a response target exists and the response target is less than the desired completion. Otherwise, the next target equals the desired completion when a desired completion exists. Otherwise, if the status is ‘Waiting for Customer’ the next target is clock_stopped when an affected SLA is linked to the request which Accountability field is set to provider or supplier. Otherwise, if the status is ‘Waiting for Customer’ the next target is best_effort. Otherwise the next target is the resolution target when a resolution target exists. In all other cases, the next target is best_effort.
note
Optional text (max 64KB) — The Note field is used to provide any additional information that could prove useful for resolving the request and/or to provide a summary of the actions that have been taken since the last entry.
organization
Readonly reference to Organization — The Organization field is automatically set when the request is saved for the first time to the organization that the person, who is selected in the Requested for field, belongs.
problem
Optional reference to Problem — The Problem field is used to link the request to a problem.
project
Optional reference to Project — The Project field is used to link the request to a project.
resolution_target_at
Readonly datetime — The Resolution target field automatically indicates when the current assignment team needs to have completed the request. The target displayed in this field is the most stringent resolution target of the affected SLAs that are related to the request and for which the current assignment team is responsible.
response_target_at
Readonly datetime — The Response target field automatically indicates when the current assignment team needs to have responded to the request. The target displayed in this field is the most stringent response target of the affected SLAs that are related to the request and for which the current assignment team is responsible.
requested_by
Required reference to Person — The Requested by field is used to select the person who submitted the request.
requested_for
Required reference to Person — The Requested for field is used to select the person for whom the request was submitted. The person selected in the Requested by field is automatically selected in this field, but another person can be selected if the request is submitted for another person.
requester_resolution_target_at
Readonly datetime — The Requester resolution target field is automatically set to the most stringent resolution target of the request’s affected SLAs, which Accountability field is not set to sla_not_affected and which are linked to an SLA for which the person who is selected in the Requested for field has coverage.
reviewed
Optional boolean, default: false — A request can be marked as reviewed by the problem manager of the service of the service instance that is linked to the request. Marking a request as reviewed excludes it from the ‘Requests for Problem Identification’ view.

This field is automatically set to true when the Service instance field is empty, when the request is linked to a problem or change, or when the Grouping field is set to grouped. This field is also set to true when the completion_reason is solved and the impact is different from top.

satisfaction
Readonly enum — The Satisfaction field is set when a requester uses the hyperlinks defined in the ‘Request Set to Completed’ email template to indicate whether or not he/she is satisfied with the manner in which a request has been handled. Valid values, apart from the default null, are:
  • dissatisfied: Dissatisfied
  • satisfied: Satisfied
service_instance
Optional reference to Service Instance — The Service instance field is used to select the Service Instance in which the cause of the incident resides, for which the change is requested, or about which information is needed.
source
Optional string (max 30) - See source
sourceID
Optional string (max 128) - See source
status
Optional enum, default: assigned — The Status field is used to select the current status of the request. Valid values are:
  • declined: Declined
  • assigned: Assigned
  • accepted: Accepted
  • in_progress: In Progress
  • waiting_for: Waiting for…
  • waiting_for_customer: Waiting for Customer
  • change_pending: Change Pending
  • project_pending: Project Pending
  • completed: Completed
subject
Required string (max 255) — The Subject field is used to enter a short description of the request.
supplier
Optional reference to Organization — The Supplier field is used to select the supplier organization that has been asked to assist with the request. The supplier organization is automatically selected in this field after a service instance has been selected that is provided by an external service provider organization.
supplier_requestID
Optional string (max 255) — The Supplier request ID field is used to enter the identifier under which the request has been registered at the supplier organization. If the supplier provided a link to the request, enter the entire URL in this field.
support_domain
Used to specify the support domain account ID in which the request is to be registered. This parameter needs to be specified when the current user’s Person record is registered in a directory account. The ID of an ITRP account can be found in the ‘Account Overview’ section of the Settings console.
team
Required reference to Team — The Team field is used to select the Team to which the request is to be assigned. By default, the first line team of the service instance that is related to the request will be selected. If a first line team has not been specified for the service instance, the support team of the service instance will be selected instead.
template
Optional reference to Request Template — The Template field contains the link to the request template that was last applied to the request.
updated_at
Readonly datetime — The date and time of the last update of the request. If the request has no updates it contains the created_at value.
urgent
Optional boolean, default: false — When the request has been marked as urgent, the Urgent field is set to true.
waiting_until
Optional datetime — The Waiting until field is used to specify the date and time at which the status of the request is to be updated from waiting_for to assigned. This field is available only when the Status field is set to waiting_for.