Service Desk - Use Examples
REST API
Use Examples
Contents
- Create a Service Request
- Retrieve all Service Requests API
- Retrieve specific fields(activity_type,site_id) for service requests
- Retrieve first 5 records with only activity_type and site_id fields
- Retrieve records by applying specific filter
- Get Specific Service Request API
- Update Service Request API
- Delete Service Request API
- Upload Document to Service Request API
- Download Document Attached to a Service Request API
- Delete Document attached to a Service Request API
Create a Service Request
Endpoint
POST /v1/service-desk/requests
Description
Creates a new service request based on the provided request body. Upon successful creation, it returns the request details along with the newly generated request ID in the response headers.
Consumes
This API call consumes the following media types:
- application/json
Produces
This API call produces the following media types:
- application/json
Request Body
The request body should be a JSON object containing the necessary details for creating a request.
Request
GET /v1/service-desk/requests
- Request Body should contain all the required fields to create request.
{
"activity_type": "REGULATION - ADA COMPLIANCE REVIEW",
"requestor": "AFM",
"prob_type": "HVAC",
"description": "Determine the work required to make the elevator landing on the 17th floor of the HQ building handicap accessible."
}
Response
- Status Code: 201 Created
- Body: A JSON object containing details of the created request, including the generated request ID.
Response Body
Response Body will contain id of the created request.
{"id":14404}
Retrieve all Service Requests API
Endpoint
GET /v1/service-desk/requests
Description
This API retrieves a list of service requests based on optional filters, selected fields, and pagination parameters. It returns all matching records or a paginated subset.
Consumes
This API call consumes the following media types:
- application/json
Produces
This API call produces the following media types:
- application/json
Query Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| fields | List<String> | Specifies which fields to include in the response. If not provided, all fields are returned. | No |
| pageStart | int | The zero-based index of the first record to return (used for pagination). | No |
| pageSize | int | The number of records to retrieve. If 0, all records are returned. | No |
Request Body (Optional)
A JSON array of filter conditions. Each condition is a key-value pair where the key is the field name, and the value is the filter value.
[{
"fieldName": "prob_type",
"filterValue": "%",
"filterOperation": "LIKE"
}]
Retrieve all service requests.
Request
GET /v1/service-desk/requests
Response
Returns list of all the records.
[
{
"activity_log_id": 1,
"activity_type": "REGULATION - ADA COMPLIANCE REVIEW",
"bl_id": "STOWER",
"site_id": "NORTH",
"description": "Determine the work required to make the elevator landing on the 17th floor of the HQ building handicap accessible.",
"key": 1,
"status": "PLANNED"
},
{
"activity_log_id": 2,
"activity_type": "PROPERTY - MAINTENANCE",
"description": "Cleaning",
"key": 2,
"status": "COMPLETED"
},
{
"activity_log_id": 3,
"activity_type": "CORRESPONDENCE - SEND",
"description": "Send formal requests for anticipated art showing during the fall season.",
"key": 3,
"status": "PLANNED"
},
{
"activity_log_id": 4,
"activity_type": "PROPERTY - GENERAL",
"bl_id": "LX",
"site_id": "MARKET",
"description": "Schedule fly over, topographical map.",
"key": 4,
"status": "COMPLETED"
},
{
"activity_log_id": 5,
"activity_type": "PROPERTY - MAINTENANCE",
"bl_id": "I202",
"site_id": "OLDCITY",
"description": "Check for possible underground storage tank leak.",
"key": 5,
"status": "IN PROGRESS"
}
]
Retrieve specific fields(activity_type,site_id) for service requests
Request
GET /v1/service-desk/requests?fields=activity_type,site_id
Response
Returns all the service requests with specific fields (activity_type, site_id).
[
{
"activity_log_id": 1,
"activity_type": "REGULATION - ADA COMPLIANCE REVIEW",
"site_id": "NORTH"
},
{
"activity_log_id": 2,
"activity_type": "PROPERTY - MAINTENANCE"
},
{
"activity_log_id": 3,
"activity_type": "CORRESPONDENCE - SEND"
},
{
"activity_log_id": 4,
"activity_type": "PROPERTY - GENERAL",
"site_id": "MARKET"
},
{
"activity_log_id": 5,
"activity_type": "PROPERTY - MAINTENANCE",
"site_id": "OLDCITY"
},
{
"activity_log_id": 6,
"activity_type": "PROJECT - CONTRACT BID REVIEW"
},
{
"activity_log_id": 7,
"activity_type": "SPECIAL EVENTS - PUT UP HOLIDAY DECORATIONS",
"site_id": "NORTH"
},
{
"activity_log_id": 8,
"activity_type": "SPECIAL EVENTS - PREPARE FOR COMPANY PICNIC",
"site_id": "MARKET"
},
{
"activity_log_id": 9,
"activity_type": "PROJECT - CONTRACT BID AWARD",
"site_id": "JFK"
},
{
"activity_log_id": 10,
"activity_type": "CORRESPONDENCE - SEND",
"site_id": "WEST"
}
]
Retrieve first 5 records with only activity_type and site_id fields
Request
GET /v1/service-desk/requests?fields=activity_type,site_id,bl_id&pageStart=0&pageSize=5
Response
Returns first 5 records with specific fields (activity_type, site_id).
[
{
"activity_log_id": 1,
"activity_type": "REGULATION - ADA COMPLIANCE REVIEW",
"bl_id": "STOWER",
"site_id": "NORTH"
},
{
"activity_log_id": 3,
"activity_type": "CORRESPONDENCE - SEND"
},
{
"activity_log_id": 383,
"activity_type": "SERVICE DESK - HOTELING"
},
{
"activity_log_id": 4,
"activity_type": "PROPERTY - GENERAL",
"bl_id": "LX",
"site_id": "MARKET"
},
{
"activity_log_id": 6,
"activity_type": "PROJECT - CONTRACT BID REVIEW"
}
]
Retrieve records by applying specific filter
Request
Retrieve records where prob_type is not null.
GET /v1/service-desk/requests
Request Body should be like below.
[{
"fieldName": "prob_type",
"filterValue": "%",
"filterOperation": "LIKE"
}]
Response
Returns records where prob_type is not null.
[
{
"activity_log_id": 328,
"rm_id": "106",
"bl_id": "HQ",
"description": "printer gets no power",
"eq_id": "2000000017",
"requestor": "ABERNATHY, ALISON",
"dv_id": "ELECTRONIC SYS.",
"prob_type": "ELECTRICAL",
"activity_type": "SERVICE DESK - MAINTENANCE",
"site_id": "MARKET",
"dp_id": "ENGINEERING",
"fl_id": "18",
"key": 328,
"status": "COMPLETED"
},
{
"activity_log_id": 329,
"rm_id": "207",
"bl_id": "XC",
"description": "replace fridge as soon as possible",
"eq_id": "1900",
"requestor": "ABERNATHY, ALISON",
"dv_id": "ELECTRONIC SYS.",
"prob_type": "OFFICE EQUIPMENT",
"activity_type": "SERVICE DESK - MAINTENANCE",
"site_id": "OLDCITY",
"dp_id": "ENGINEERING",
"fl_id": "04",
"key": 329,
"status": "APPROVED"
},
{
"activity_log_id": 330,
"dv_id": "ELECTRONIC SYS.",
"prob_type": "ELECTRICAL",
"activity_type": "SERVICE DESK - MAINTENANCE",
"site_id": "MARKET",
"description": "electric wires should be hidden in the corridor",
"dp_id": "ENGINEERING",
"key": 330,
"requestor": "ABERNATHY, ALISON",
"status": "IN PROGRESS"
}
]
Request
Retrieve records where site_id value is MARKET.
GET /v1/service-desk/requests
Request Body should be like below.
[{
"fieldName": "site_id",
"filterValue": "MARKET"
}]
Response
Returns records where site_id value is MARKET.
[
{
"activity_log_id": 4,
"activity_type": "PROPERTY - GENERAL",
"bl_id": "LX",
"site_id": "MARKET",
"description": "Schedule fly over, topographical map.",
"key": 4,
"status": "COMPLETED"
},
{
"activity_log_id": 8,
"activity_type": "SPECIAL EVENTS - PREPARE FOR COMPANY PICNIC",
"bl_id": "HQ",
"site_id": "MARKET",
"description": "Summer company picnic site preparations.",
"key": 8,
"status": "PLANNED"
},
{
"activity_log_id": 23,
"activity_type": "PROJECT - CONTRACT BID SOLICITATION",
"bl_id": "HQ",
"site_id": "MARKET",
"description": "Purchase requisition for next fiscal year.",
"key": 23,
"status": "COMPLETED"
}
]
Get Specific Service Request API
Endpoint
GET /v1/service-desk/requests/{id}
Description
This API retrieves details of a service request by its ID. Optionally, specific fields can be queried to limit the response data. If the request is found, it returns a 200 OK status with the requested details. If no request is found, it returns a 404 NOT FOUND status.
Produces
This API call produces the following media types via the Content-Type request header:
- application/json
Path Parameter
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | Integer | The unique ID of the service request to be retrieved. | Yes |
Query Parameter
| Parameter | Type | Description | Required |
|---|---|---|---|
| fields | List<String> | A list of specific field names to include in the response. If not provided, all available fields are returned. | No |
Response
- Status Code: 200 OK (If the request is found)
- Status Code: 404 NOT FOUND (If the request id does not exist)
- Body: A JSON object containing the requested service request details
Request
GET /v1/service-desk/requests/14386
Response (200 OK)
{
"activity_log_id": 14386,
"dv_id": "FACILITIES",
"prob_type": "PREVENTIVE MAINT",
"rm_id": "340MEC",
"activity_type": "SERVICE DESK - MAINTENANCE",
"bl_id": "NB",
"site_id": "BEDFORD",
"eq_id": "AHU_1",
"dp_id": "MAINTENANCE",
"fl_id": "03",
"key": 14386,
"status": "IN PROGRESS"
}
Request
GET /v1/service-desk/requests/14386?fields=activity_type,site_id
Response (200 OK)
{
"activity_log_id": 14386,
"activity_type": "SERVICE DESK - MAINTENANCE",
"site_id": "BEDFORD"
}
Update Service Request API
Endpoint
PATCH /v1/service-desk/requests/{id}
Description
This API updates an existing service request by its ID. The request body should contain the fields that need to be updated. It returns an HTTP 200 OK status upon successful update.
Consumes
This API call consumes the following media types:
- application/json
Produces
This API call produces the following media types:
- application/json
Path Parameter
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | Integer | The unique ID of the service request to be updated. | Yes |
Request Body
- request (required) - Body Parameter
A JSON object containing the fields to be updated. Only the specified fields will be modified.
Example Request Body
{
"activity_log_id": 9,
"bl_id": "STOWER",
"site_id": "NORTH"
}
Response
- Status Code: 200 OK (Request updated successfully)
- Status Code: 400 BAD REQUEST (If the request body is invalid)
- Status Code: 404 NOT FOUND (If the service request ID does not exist)
Example Usage
Request PATCH /v1/service-desk/requests/9
Example Request Body
{
"activity_log_id": 9,
"bl_id": "STOWER",
"site_id": "NORTH"
}
Response
200 OK
Delete Service Request API
Endpoint
DELETE /v1/service-desk/requests/{id}
Description
This API allows the deletion of an existing service request.
Consumes
This API call consumes the following media types:
- application/json
Produces
This API call produces the following media types:
- application/json
Path Parameter
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | Integer | The unique ID of the service request to be deleted. | Yes |
Example Request
DELETE /v1/service-desk/requests/329
Content-Type
- application/json
Request Body
{
"wr_id": 950000129
}
Response
- Status Code: 200 OK (Success)
- No Response Body
- 400 Bad Request: If the request body is invalid or missing required fields.
- 404 Not Found: If no service request exists with the given ID.
Upload Document to Service Request API
Endpoint
POST /v1/service-desk/requests/{id}/doc
Description
This API allows users to upload a document for a specific service request by specifying the request ID and document field name. The file content is sent as a multipart/form-data request.
Consumes
This API call consumes the following media types via the Content-Type request header:
- multipart/form-data
Produces
This API call produces the following media types via the Content-Type request header:
- application/json
Path Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | Integer | The unique ID of the service request to which the document is attached. | Yes |
Request Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| field | String | The document field name (e.g., doc1, doc2) that identifies the document to be uploaded. | Yes |
Request Body
A multipart/form-data request containing the file.\
| Key | Value | Type |
|---|---|---|
| file | (Choose a file from your system) | File |
Example Usage
POST /v1/service-desk/requests/63/doc?field=doc
Response
- Status Code: 200 OK
- No response body
Download Document Attached to a Service Request API
Endpoint
GET /v1/service-desk/requests/{id}/doc
Description
This API allows downloading a document attached to service request. The document is retrieved as a byte stream and returned in the response body.
Produces
This API call produces the following media types:
- application/octet-stream (File data in binary format)
Path Parameter
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | Integer | The unique ID of the service request from which the document should be downloaded. | Yes |
Query Parameter
| Parameter | Type | Description | Required |
|---|---|---|---|
| field | String | The document field name (e.g., doc1, doc2) that identifies the document to be downloaded. | Yes |
Response
- Status Code: 200 OK
- Body: The binary data of the requested document.
Example Usage
Request
GET v1/service-desk/requests/63/doc?field=doc
Response
- 200 OK
- (Binary file data)
Delete Document attached to a Service Request API
Endpoint
DELETE /v1/service-desk/requests/{id}/doc
Produces
- application/json
Description
This API allows the deletion of a document attached to a service request.
Path Parameter
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | Integer | The unique ID of the service request from which the document should be deleted. | Yes |
Query Parameter
| Parameter | Type | Description | Required |
|---|---|---|---|
| field | String | The document field name (e.g., doc1, doc2) that identifies the document to be deleted. | Yes |
Response
- Status Code: 200 OK
- No response body
Example Usage
Request
DELETE v1/service-desk/requests/63/doc?field=doc
Response
200 OK
