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.

Predefined Filters

The following predefined filters 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.

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": "4me 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.4me.com/requests/68673/2sii015q/149/yes",
      "dissatisfied_url": "https://widget.4me.com/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 Resolution
  • rfc: RFC - Request for Change
  • rfi: RFI - Request for Information
  • reservation: Reservation - Request for Reservation
  • order: Order - Request for Purchase
  • fulfillment: Fulfillment - Request for Order Fulfillment
  • complaint: Complaint - Request for Support Improvement
  • compliment: Compliment - Request for Bestowal of Praise
  • other: 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 Required
  • workaround: Workaround - Root Cause Not Removed
  • gone: Gone - Unable to Reproduce
  • duplicate: Duplicate - Same as Another Request of Customer
  • withdrawn: Withdrawn - Withdrawn by Requester
  • no_reply: No Reply - No Reply Received from Customer
  • rejected: Rejected - Rejected by Approver
  • conflict: Conflict - In Conflict with Internal Standard or Policy
  • declined: Declined - Declined by Service Provider
  • 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_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 the dissatisfied_url of the requested_for. In case the requested_by is different form the requested_for, the satisfaction link of the requested_by are also included. Feedback is null in case no feedback for the request can be provided at this time.
feedback_on_knowledge_article
Readonly reference to Knowledge Article — The knowledge article that this request provides feedback on.
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-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: Proposed
  • rejected: Rejected
  • accepted: Accepted
  • resolved: Resolved
  • canceled: 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 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.

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 and completed_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 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

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: Declined
  • on_backlog: On Backlog
  • assigned: Assigned
  • accepted: Accepted
  • in_progress: In Progress
  • waiting_for: Waiting for…
  • waiting_for_customer: Waiting for Customer
  • reservation_pending: Reservation Pending
  • workflow_pending: Workflow 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.
summary
Readonly text - AI Summary created for the current request account. Be aware that the AI summary might not always be fully up to date, because it can take a while for an AI Summary to be generated after adding a new note.
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 Xurrent 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 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.
workflow
Optional reference to Workflow — The Workflow field is used to link the request to a workflow.