Service Desk - Use Examples

Last updated
Save as PDF

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