Requests API
- List requests
- Get a request
- Create a request
- Update a request
- Archive a request
- Trash a request
- Restore a request
- Fields
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.
Predefined Filters
The following predefined filters are available:
/requests/completed
: List all completed requests/requests/open
: List all open requests/requests/requested_by_or_for_me
: List all requests which requested by person or requested for person is the API user/requests/assigned_to_my_team
: List all requests that are assigned to one of the teams that the API user is a member of/requests/assigned_to_me
: List all requests that are assigned to the API user/requests/waiting_for_me
: List all requests which requested by person is the API user and which status is ‘Waiting for Customer’/requests/problem_management_review
: 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/requests/sla_accountability
: List all requests that one of the teams of the API user can be held accountable for
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.
Filtering
Filtering is available for the following fields:
id
source
sourceID
subject
category
impact
status
workflow
next_target_at
completed_at
created_by
grouping
grouped_into
knowledge_article
requested_by
requested_for
service_instance
supplier_requestID
created_at
updated_at
team
member
template
major_incident_status
organization
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
Response
The response is similar to the response in List requests
Get a 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
},
"resolution_duration": null,
"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,
"workflow": {
"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": "R-Service Self Service",
"next_target_at": "no_target",
"template": null,
"custom_fields": null,
"waiting_until": null,
"reviewed": true,
"satisfaction": "satisfied",
"knowledge_article": null,
"urgent": false,
"addressed": false,
"feedback": {
"requested_by": {
"satisfied_url": "https://widget.r-service.tech/requests/68673/2sii015q/149/yes",
"dissatisfied_url": "https://widget.r-service.tech/requests/68673/2sii015q/149/no"
}
}
}
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
Archive a Request
POST /requests/:id/archive
Moves a given request to the Archive. This action requires the Account Administrator or Directory Administrator role in the account of the request.
Response
Status: 200 OK
{
"archived": "true",
"category": "...",
"...": "..."
}
The response contains all fields of the archived request and is similar to the response in Get a single request
Trash a Request
POST /requests/:id/trash
Moves a given request to the Trash. This action requires the Account Administrator or Directory Administrator role in the account of the request.
Response
Status: 200 OK
{
"trashed": "true",
"category": "...",
"...": "..."
}
The response contains all fields of the archived request and is similar to the response in Get a single request
Restore a Request
POST /requests/:id/restore
Moves a given request from the Archive or the Trash back into the view of “Completed Requests”. This action requires the Account Administrator or Directory Administrator role in the account of the request.
Response
Status: 200 OK
{
"category": "...",
"...": "..."
}
The response contains all fields of the archived request and is similar to the response in Get a single request
Fields
Note: if a request is visible in multiple accounts, the following fields in the response of an API request are account specific,
which means that the value can be different for the same request depending on the account that has been specified in the X-4me-Account
header of the API call:
assignment_count
completed_at
completion_reason
created_at
major_incident_status
member
next_target_at
reopen_count
status
supplier
supplier_requestID
team
- 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. - agile_board
- Optional reference to Agile Board — The Agile board on which the request is placed.
- agile_board_column
- Optional reference to Agile Board Column — The column of the agile board on which the request is placed.
- agile_board_column_position
- Optional integer — The Position field is used to specify the position of the request, relative to the other items within the column of the agile board. The topmost item has position 1.
- 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.
- attachments
- Readonly aggregated Attachments
- Use Requests - Notes API to get note attachments.
- category
- Required enum — The Category field is used to select the category of the request. Valid values are:
-
incident
: Incident - Request for Incident Resolutionrfc
: RFC - Request for Changerfi
: RFI - Request for Informationreservation
: Reservation - Request for Reservationorder
: Order - Request for Purchasefulfillment
: Fulfillment - Request for Order Fulfillmentcomplaint
: Complaint - Request for Support Improvementcompliment
: Compliment - Request for Bestowal of Praiseother
: Other - Request is Out of Scope
- 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.
- checked_items
- Optional array of string — The names of the checklist items that are checked within the instructions field.
- 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 Requiredworkaround
: Workaround - Root Cause Not Removedgone
: Gone - Unable to Reproduceduplicate
: Duplicate - Same as Another Request of Customerwithdrawn
: Withdrawn - Withdrawn by Requesterno_reply
: No Reply - No Reply Received from Customerrejected
: Rejected - Rejected by Approverconflict
: Conflict - In Conflict with Internal Standard or Policydeclined
: Declined - Declined by Service Providerunsolvable
: 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_fields
- Optional custom fields — Custom fields provided in JSON format by the UI Extension that is linked to the related request template.
- custom_fields_attachments
- Writeonly attachments The attachments used in Custom fields.
- 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.
- feedback
- Readonly hash — Hash containing the
satisfied_url
and thedissatisfied_url
of therequested_for
. In case therequested_by
is different form therequested_for
, the satisfaction link of therequested_by
are also included. Feedback isnull
in case no feedback for the request can be provided at this time. - 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
: Nonegroup
: Groupgrouped
: 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 Usermedium
: Medium - Service Down for One Userhigh
: High - Service Degraded for Several Userstop
: 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-4me-Account header
can be included in an API PATCH request to add an internal note for a specific account (see Multiple Accounts). -
The Internal note field cannot be specified in the ?fields= parameter.
- internal_note_attachments
- Writeonly attachments The attachments used in the Internal Note field.
- knowledge_article
- Optional reference to Knowledge Article — The Knowledge Article field is used to relate a KnowledgeArticle to the request. When this field is used to update an existing request, all knowledge articles that are linked to this request will be replaced by the new knowledge article.
- major_incident_status
- Optional enum — The Major Incident Status field is used to indicate the status in the major incident management process. Valid values are:
-
proposed
: Proposedrejected
: Rejectedaccepted
: Acceptedresolved
: Resolvedcanceled
: Canceled
- 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 totrue
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 toprovider
orsupplier
. Otherwise, if the status is ‘Waiting for Customer’ the next target isbest_effort
. Otherwise the next target is the resolution target when a resolution target exists. In all other cases, the next target isbest_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.
-
The Note field cannot be specified in the ?fields= parameter.
- note_attachments
- Writeonly attachments The attachments used in the Note field.
- 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.
- planned_effort
- Optional integer (max 600000) — The Planned effort field is used to specify the number of minutes the member is expected to spend working on the request.
- problem
- Optional reference to Problem — The Problem field is used to link the request to a problem.
- product_backlog
- Optional reference to Product Backlog — The Product backlog field is used to place the request on a product backlog. When a request is placed on a product backlog without specifying a
product_backlog_position
it is placed at the bottom of the product backlog. - product_backlog_position
- Optional integer — The Product backlog position field is used to determine the relative position of the request on the product backlog (the top most item has position 1). When a request is placed on a product backlog without specifying a
product_backlog_position
it is placed at the bottom of the product backlog. - project
- Optional reference to Project — The Project field is used to link the request to a project.
- provider_not_accountable
- Optional boolean — The Provider not accountable field value is used to indicate when the provider is currently not to be accountable.
- provider_was_not_accountable
- Readonly boolean — The Provider was not accountable field value is automatically set to
true
when the provider has at any point in time indicated not to be accountable. - reopen_count
- Readonly integer — The Reopen count field is automatically set to the number of times that the status of the request has changed from ‘Completed’ to a different value in the Account from which the request data is retrieved.
- reservation
- Optional reference to Reservation — The Reservations field is used to link the request to a reservation.
- resolution_duration
- Readonly integer — The number of minutes it took to complete this request, which is calculated as the difference between the
created_at
andcompleted_at
values. - 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 workflow, or when the Grouping field is set togrouped
. This field is also set totrue
when the completion_reason issolved
and the impact is different fromtop
. - 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
: Dissatisfiedsatisfied
: Satisfied
It is also possible to set the value of this field via the Request Satisfaction API.
- 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 workflow 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
: Declinedon_backlog
: On Backlogassigned
: Assignedaccepted
: Acceptedin_progress
: In Progresswaiting_for
: Waiting for…waiting_for_customer
: Waiting for Customerreservation_pending
: Reservation Pendingworkflow_pending
: Workflow Pendingproject_pending
: Project Pendingcompleted
: 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 a R-Service account can be found in the ‘Account Overview’ section of the Settings console.
- task
- Optional reference to Task — The Task field is visible only when the request was automatically generated by a task. When visible, this field contains the task that caused the request to be generated.
- 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.
- time_spent
- Optional integer — The Time spent field is used to enter the time that you have spent working on the request since you started to work on it or, if you already entered some time for this request, since you last added your time spent in it.
-
This field cannot be specified in the ?fields= parameter.
- time_spent_effort_class
- Optional reference to Effort Class — The Effort class field is used to select the effort class that best reflects the type of effort for which time spent is being registered.
-
This field cannot be specified in the ?fields= parameter.
- 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 totrue
. - 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
toassigned
. This field is available only when the Status field is set towaiting_for
. - workflow
- Optional reference to Workflow — The Workflow field is used to link the request to a workflow.