Endpoints in the BMC Digital Workplace Catalog REST API

You can perform the following actions by using the supported API categories in the BMC Digital Workplace Catalog:

Authentication
- To request authentication token
Categories
Services
Requests and questions
Reviews
Ratings
Service migration
- To export selected services
- To import a service zip file

Authentication

Within the Digital Workplace Catalog, users with the role permissions of asset manager and service catalog admin can see all services. The same users in external systems that link to Digital Workplace Catalog have the same access permissions. This support is expected to be removed in the future, where Digital Workplace Catalog will manage role permissions completely independently from the external system.

To request authentication token

Method	Endpoint
POST	/users/login

Parameters

Name	Where	Type	Required	Default	Example	Description
id	body	string	✅️	none	<your_user>	Digital Workplace Catalog user login account (with organization domain).
password	body	string	✅️	none	<your_password>	Password

Example request body

{
"id": "<your_user>",
"password": "<your_password>"
}

Response

Response	Value	Notes
HTTP code	200	Application returns an authentication token that is valid for about half an hour.

Error handling

Failed authentication requests return an error object with the following properties.

Name	Type	Description
message	string	Error message with error code.
data	string	Error message description.

Categories

To retrieve a full category list

Method	URL
GET	/categories

Parameters

Name	Where	Type	Required	Default	Example	Description
perPage	query	integer	No	-1	20	Page size. -1 for non-paginated search.
page	query	integer	No	1	1	Page number

Response

Response	Value	Notes
HTTP code	200	Returns a category list object array.
type	application/json	Not applicable.

type: application/json

{
"pageSize": 5,
"page": 1,
"categories": [
   {
     "id": "000000000000001",
     "guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVD",
     "name": "Accounts, Security, and IDs",
     "categoryGroupId": "000000000000001",
     "parentId": null,
     "childCount": 5,
     "subCategories": null
   },
   {
     "id": "000000000000002",
     "guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVE",
     "name": "User accounts and account access",
     "categoryGroupId": "000000000000001",
     "parentId": "000000000000001",
     "childCount": 0,
     "subCategories": null
   },
   {
     "id": "000000000000003",
     "guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVF",
     "name": "System accounts",
     "categoryGroupId": "000000000000001",
     "parentId": "000000000000001",
     "childCount": 0,
     "subCategories": null
   },
   {
     "id": "000000000000004",
     "guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVG",
     "name": "Access requests",
     "categoryGroupId": "000000000000001",
     "parentId": "000000000000001",
     "childCount": 0,
     "subCategories": null
   },
   {
     "id": "000000000000005",
     "guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVH",
     "name": "IDs, badges, and facility access",
     "categoryGroupId": "000000000000001",
     "parentId": "000000000000001",
     "childCount": 0,
     "subCategories": null
   }
  ],
"total": 123
}

Response properties

Name	Type	Description
pageSize	integer	Pass through request parameter.
page	integer	Pass through request parameter.
categories	array	Category object array.

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code.

To retrieve descendants of a given category

This API returns only categories that contain services that are entitled to the requesting user.

Method	Endpoint
GET	/categories/{categoryId}/categories

Parameters

Name	Where	Type	Required	Default	Example	Description
categoryId	URL		Yes	None	000000000000001	Category ID to retrieve.
depth	query	int	No	1	2	Depth of the category being retrieved. Allowed values: 1, 2, 3.
requestedfor	query	String	No	None	Mary	When a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user.

Response

Response	Value	Notes
HTTP code	200	Returns a category array object. If the requested categoryId does not exist, or does not contain descendants, then an empty array is returned.
type	application/json	Not applicable.

type: application/json

[
  {
   "id": "000000000000002",
   "guid": null,
   "name": "User accounts and account access",
   "categoryGroupId": "000000000000001",
   "parentId": "000000000000001",
   "childCount": 0,
   "subCategories": null
  },
  {
   "id": "000000000000003",
   "guid": null,
   "name": "System accounts",
   "categoryGroupId": "000000000000001",
   "parentId": "000000000000001",
   "childCount": 0,
   "subCategories": null
  },
  {
   "id": "000000000000004",
   "guid": null,
   "name": "Access requests",
   "categoryGroupId": "000000000000001",
   "parentId": "000000000000001",
   "childCount": 0,
   "subCategories": null
  },
  {
   "id": "000000000000005",
   "guid": null,
   "name": "IDs, badges, and facility access",
   "categoryGroupId": "000000000000001",
   "parentId": "000000000000001",
   "childCount": 0,
   "subCategories": null
  },
  {
   "id": "000000000000006",
   "guid": null,
   "name": "Remote access",
   "categoryGroupId": "000000000000001",
   "parentId": "000000000000001",
   "childCount": 0,
   "subCategories": null
  }
]

Response properties

Name	Type	Description
id	string	Category ID used by the application.
guid	string	Unique ID used by the platform.
name	string	Category name.
categoryGroupId	string	Group to which the category belongs. Currently there is only one category group, referenced as "Type of service".
parentId	string	ID of child's parent category(?) or, if no child, null.
childCount	integer	Number of direct descendant categories.
subCategories	string	Null

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with the error code.

To retrieve category groups

Method	Endpoint
GET	/categories/groups

Parameters

None

Response

Response	Value	Notes
HTTP code	200	Successfulful returns category array.
type	application/json	Not applicable.

type: application/json

[
{
   "id": "000000000000001",
   "guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVC",
   "name": "Type of Service",
   "description": "",
   "systemId": "type-of-service",
   "groupStatus": "ACTIVE",
   "childCount": 18,
   "categories": null
}
]

Response properties

Name	Type
id	string
guid	string
name	string
description	string
systemId	string
groupStatus	string
childCount	integer
categories	string

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code.

To retrieve categories of a given category group

Method	Endpoint
GET	/categories/groups/{categoryGroupId}/categories

Parameters

Name	Where	Type	Required	Default	Example	Description
categoryGroupId	URL		Yes			Not applicable.
depth	body	integer	No	1	2	Depth of the cateogory being retrieved. Allowed values: 1,2,3
requestedfor	query	String	No		Mary	When a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user.

Response

Response	Value	Notes
HTTP code	200	Successful response returns array of category objects.
type	application/json	Not applicable.

type: application/json

[
{
   "id": "000000000000002",
   "guid": null,
   "name": "User accounts and account access",
   "categoryGroupId": "000000000000001",
   "parentId": "000000000000001",
   "childCount": 0,
   "subCategories": null
},
{
   "id": "000000000000003",
   "guid": null,
   "name": "System accounts",
   "categoryGroupId": "000000000000001",
   "parentId": "000000000000001",
   "childCount": 0,
   "subCategories": null
},
{
   "id": "000000000000004",
   "guid": null,
   "name": "Access requests",
   "categoryGroupId": "000000000000001",
   "parentId": "000000000000001",
   "childCount": 0,
   "subCategories": null
},
{
   "id": "000000000000005",
   "guid": null,
   "name": "IDs, badges, and facility access",
   "categoryGroupId": "000000000000001",
   "parentId": "000000000000001",
   "childCount": 0,
   "subCategories": null
},
{
   "id": "000000000000006",
   "guid": null,
   "name": "Remote access",
   "categoryGroupId": "000000000000001",
   "parentId": "000000000000001",
   "childCount": 0,
   "subCategories": null
}
]

Error handling

Failed requests return an error object with the following properties:

Argument	Type	Description
message	string	Error message with error code.

Services

To retrieve details of a single service item

Method	Endpoint
GET	/services/{serviceId}

Parameters

Name	Where	Type	Required	Example	Description
serviceId	URL		Yes		Not applicable.
requestedfor	query parameter	String	No	Mary	When a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user.

Response

Response	Value
HTTP code	200
type	application/json

type: application/json

{
"serviceType": "Desktop",
"templateType": "SERVICE",
"id": "000000000001219",
"name": "Adobe Illustrator",
"description": "Although during its first decade Adobe developed Illustrator primarily for Macintosh, it .....",
"iconUrl": "/mp/media/.........0IjoicG5nIn1dXQ/file.png?sha=d706a107dc3d5cc6",
"rating": 0.8,
"modifiedDate": "2016-01-27T13:46:17.000+0000",
"createdDate": "2016-01-27T13:38:50.000+0000",
"ratingCount": 2,
"supplier": {
 "id": "000000000000001",
 "name": "Coke Services"
 },
"categories": [
 {
 "id": "000000000000041",
 "name": "Computer software",
 "categoryGroupId": "000000000000001",
 "parentId": null,
 "childCount": 0,
 "subCategories": null
 },
 {
 "id": "000000000000047",
 "name": "Graphics and design",
 "categoryGroupId": "000000000000001",
 "parentId": "000000000000041",
 "childCount": 0,
 "subCategories": null
 }
 ],
"price": {
 "paymentType": "Once",
 "currency": "USD"
 },
"onceCost": 120,
"monthlyCost": 0,
"yearlyCost": 0,
"dynamicFields": [
 {
 "title": "Platform",
 "content": "Windows",
 "documents": []
 }
 ],
"bundledServices": [],
"entitled": true,
"media": [
 {
 "type": "IMAGE",
 "url": "/mp/media/......../file.jpg?sha=0d05cab032f35a0b"
 },
 {
 "type": "IMAGE",
 "url": "/mp/media/......../file.jpg?sha=a70919ad560b236a"
 },
 {
 "type": "IMAGE",
 "url": "/mp/media/......../file.jpg?sha=adf9a4581061ead9"
 },
 {
 "type": "VIDEO",
 "url": "https://www.youtube.com/watch?v=d0LTzbksUiU"
 }
 ]
}

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code.

To search for services

Search criteria can be by serviceIds, categoryId, or free text for a single service name or tag.

Note

Multiple search criteria cannot be used in a same call. Wildcards are also not supported.

type: application/json

{
"serviceIds": ["%123%","%456","789%"],
"title": "apple"
}

Method	Endpoint
POST	/services/search

Parameters

Name	Where	Type	Required	Default	Example	Description
perPage	query	integer	No	-1	20	Page size. -1 for non-paginated search.
page	query	integer	No	1	1	Page number to display.
serviceIds	body	string	No			Not applicable.
categoryId	body	string	No			Not applicable.
title	body	string	No			Not applicable.
requestedfor	query	String	No		Mary	When a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user.

type: application/json

{}

{"serviceIds": ["123","456","789"]}

{"title": "apple"}

{"categoryId": "111"}

Response

Response	Value	Notes
HTTP code	200	Successful response receives an array of service objects.
type	application/json

type: application/json

{
"services": [
    {
     "serviceType": "Cloud Software 1",
     "templateType": "SERVICE",
     "id": "000000000000101",
     "name": "Office 365",
     "excerpt": "Get the most secure Office for your business",
     "iconUrl": "/mp/media/.../file.png?sha=b63f635628db7722",
     "rating": 0,
     "modifiedDate": "2015-12-03T18:43:35.000+0000",
     "createdDate": "2015-12-03T18:35:48.000+0000",
     "ratingCount": 0,
     "categories": [
        {
         "id": "000000000000138",
         "name": "Collaboration tools",
         "categoryGroupId": "000000000000002",
         "parentId": "000000000000135",
         "childCount": 0,
         "subCategories": null
        },
        {
         "id": "000000000000141",
         "name": "Productivity",
         "categoryGroupId": "000000000000002",
         "parentId": "000000000000135",
         "childCount": 0,
         "subCategories": null
        }
      ],
     "price": {
       "paymentType": "Recurring",
       "currency": "USD",
       "paymentSchedule": "Monthly"
      },
     "onceCost": 0,
     "monthlyCost": 8.25,
     "yearlyCost": 99,
     "provisioningTime": {
       "type": "ProvisioningTimeMetric",
       "value": 30,
       "timeUnit": "MIN"
      },
     "bundledServices": [],
     "entitled": true
    },
    {
     "serviceType": "Cloud Software 1",
     "templateType": "SERVICE",
     "id": "000000000000108",
     "name": "Evernote Premium",
     "excerpt": "Evernote Premium unites writing, collection, discussion, and presentation in a single workspace. Instead of jumping between apps, keep focus in one place and your best work will follow.",
     "iconUrl": "/mp/media/..../file.png?sha=54ce415746fe5a0d",
     "rating": 0,
     "modifiedDate": "2015-12-04T01:43:03.000+0000",
     "createdDate": "2015-12-03T20:04:32.000+0000",
     "ratingCount": 0,
     "categories": [
        {
         "id": "000000000000164",
         "name": "Computer software",
         "categoryGroupId": "000000000000002",
         "parentId": null,
         "childCount": 0,
         "subCategories": null
        },
        {
         "id": "000000000000167",
         "name": "Collaboration tools",
         "categoryGroupId": "000000000000002",
         "parentId": "000000000000164",
         "childCount": 0,
         "subCategories": null
        },
        {
         "id": "000000000000166",
         "name": "Business",
         "categoryGroupId": "000000000000002",
         "parentId": "000000000000164",
         "childCount": 0,
         "subCategories": null
        }
      ],
     "price": {
       "paymentType": "Recurring",
       "currency": "USD",
       "paymentSchedule": "Yearly"
      },
     "onceCost": 0,
     "monthlyCost": 4.17,
     "yearlyCost": 49.99,
     "bundledServices": [],
     "entitled": true
    }
  ],
"pageSize": 10
"page": 1,
"total": 2
}

Error handling

Failed requests return an error object with the following properties:

Argument	Type	Description
message	string	Error message with error code.

To retrieve the full catalog view setting of ON or OFF

Method	Endpoint
GET	/services/fullcatalogview

Parameters

None

Response

Response	Value	Notes
HTTP code	200	Successful response returns a boolean value. true = ON, false = OFF.
type	application/json	Not applicable.

type: application/json

true
false

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code.

Requests and questions

To initiate a request for a service by ID

Method	Endpoint
POST	/services/{serviceId}/requests

Parameters

Name	Where	Type	Required	Default	Example	Description
serviceId	URL		✅️			ID of the service.
requestedfor	query	string		(current user)	"Mary"	User ID to request on behalf of someone else. If this parameter is not presented, the request is for the current user.

Response

Response	Value	Notes
HTTP code	200	Successful response returns array of questions. Note: Structure of questionnaire may vary between services. Refer to documentation of questionnaire.
type	application/json	Not applicable.

type: application/json

{
   "requestId": "1111",
   "externalId": 2222,
   "questionnaire": {
       "id": "1",
       "pages": [
           {
               "id": "0",
               "title": "Default Page",
               "pageItems": [
                   {
                       "type": "Dropdown",
                       "id": "0",
                       "visible": true,
                       "label": "machine name",
                       "description": "",
                       "required": true,
                       "defaultAnswer": null,
                       "options": [
                           {
                               "dataValue": "SCCM-2012",
                               "displayValue": "SCCM-2012"
                           },
                           {
                               "dataValue": "WIN-7X64",
                               "displayValue": "WIN-7X64"
                           }
                        ]
                   },
                   {
                       "type": "TextField",
                       "id": "1",
                       "visible": true,
                       "label": "question answers",
                       "description": "",
                       "required": true,
                       "defaultAnswer": "null",
                       "maxLength": 254
                   },
                   {
                       "type": "TextField",
                       "id": "2",
                       "visible": true,
                       "label": "user name",
                       "description": "",
                       "required": true,
                       "defaultAnswer": "null",
                       "maxLength": 254
                   }
                ]
           }
        ]
   }
}

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code.

To send an answer to a question

Respond to a question ID from the list returned from the request.

Note

Each required question must be answered before the request can be submitted.

Method	Endpoint
POST	/services/{serviceId}/questionnaire/answers

Parameters

Name	Where	Type	Required	Description
serviceId: the id of the service	url		Yes	The ID of the service.
questionnaireId	body	string	No	Not applicable.
questionId	body	string	No	Not applicable.
answers	body	string	No	Not applicable.
serviceRequestId	body	string	No	Not applicable.

type: application/json

{
"questionnaireId": "000000000000001",
"questionId": "0",
"answers": ["My First Name"],
"serviceRequestId": "000000000000007"
}

Response

Response	Value	Notes
HTTP code	200	Successful response shows the changes of visibility by ID based on answers submitted.
type	application/json	Not applicable.

Returned values indicate how the answer being submitted impacts answers, options and visibilities of other questions by ID.

type: application/json

{
1:[
"answers": ["aa", "bb"],
"options": [ {"dataValue": "1","displayValue": "ONE"},
{"dataValue": "2","displayValue": "TWO"}
],
"visible": true
]
}

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code.

To submit the specified request to the specified service

Method	Endpoint
POST	/services/{serviceId}/requests/{requestId}/submissions

Parameters

Name	Where	Required	Description
serviceId	URL	Yes	ID of the service.
requestId	URL	Yes	ID of the request.

Response

Response	Value	Notes
HTTP code	200	Successful returns an empty content body.
type	application/json	Not applicable.

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code.

To retrieve all requests of a specific service by the current user

Method	Endpoint
GET	/services/{serviceId}/myrequests

Parameters

Name	Where	Type	Required	Default	Example	Description
serviceId	URL		Yes			ID of the service.
perPage	query	integer	No	10	20	Page size.
page	query	integer	No	1	1	Page number.

Response

Response	Value
HTTP code	200
type	application/json

type: application/json

{
   "totalSize": 2,
   "data": [
       {
           "id": "1204",
           "serviceId": "000000000000511",
           "status": "COMPLETED",
           "startTime": "2015-08-24T20:58:06.581+0000",
           "lastModifiedTime": "2015-08-24T20:58:06.606+0000",
"completeTime": "2015-08-24T20:58:06.606+0000"
       },
       {
           "id": "1205",
           "serviceId": "000000000000511",
           "status": "COMPLETED",
           "startTime": "2015-08-24T21:06:00.244+0000",
           "lastModifiedTime": "2015-08-24T21:06:00.245+0000",
           "completeTime": "2015-08-24T21:06:00.245+0000"
       }
    ]
}

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code.

To find requests

This call endpoint can be used to display a list of service requests on the user's request timeline. If a user is not specified, all requests are displayed.

Method	Endpoint
GET	/services/requests

Parameters

Name	Where	Type	Example	Description
requestedfor	query	string	"Mary"	Filter requests that are requested for the specified user.
requestedby	query	string	"Francie"	Filter requests that are requested by the specified user.
since	query	date	Tue, 08 Mar 2016 17:49:05 GMT	Filter requests that are updated since the specified timestamp.
max	query	integer	30	Maximum amount of requests that will be retrieved.

Response

Response	Value	Notes
HTTP code	200	Successful response returns a requests object array.
type	application/json	Not applicable.

type: application/json

[
 {
 "id": "4402",
 "requestingUserId": "Allen",
 "requestForUserId": "Allen",
 "name": "New environment test",
 "description": "test",
 "excerpt": "test",
 "price": {
 "paymentType": "Free",
 "currency": "USD"
 },
 "status": {
 "id": "4402",
 "serviceId": "000000000004201",
 "status": "ACTIVE",
 "startTime": "2016-03-08T20:32:12.000+0000",
 "lastModifiedTime": "2016-03-08T20:32:12.000+0000"
 },
 "quantity": 1,
 "logoUrl": "/mp/media/.../file.png?sha=c9eb1a96d6eea52f",
 "onceCost": 0,
 "monthlyCost": 0,
 "yearlyCost": 0
 },
 {
 "id": "4302",
 "requestingUserId": "Allen",
 "requestForUserId": "Allen",
 "name": "New environment test",
 "description": "test",
 "excerpt": "test",
 "price": {
 "paymentType": "Free",
 "currency": "USD"
 },
 "status": {
 "id": "4302",
 "serviceId": "000000000004201",
 "status": "FAILED",
 "startTime": "2016-03-08T19:21:27.000+0000",
 "lastModifiedTime": "2016-03-08T19:21:27.000+0000"
 },
 "quantity": 1,
 "logoUrl": "/mp/media/.../file.png?sha=c9eb1a96d6eea52f",
 "onceCost": 0,
 "monthlyCost": 0,
 "yearlyCost": 0
 },
 {
 "id": "4301",
 "requestingUserId": "Allen",
 "requestForUserId": "Allen",
 "name": "SJ Bundle 1",
 "description": "fhyfgjhgjghghghjgh ",
 "excerpt": "yhytrtrtytryghhghhfhfh",
 "price": {
 "paymentType": "Once",
 "currency": "USD",
 "paymentSchedule": ""
 },
 "status": {
 "id": "4301",
 "serviceId": "000000000001716",
 "status": "COMPLETED",
 "startTime": "2016-03-08T19:12:08.000+0000",
 "lastModifiedTime": "2016-03-08T19:12:08.000+0000"
 },
 "provisioningTime": {
 "type": "ProvisioningTimeMetric",
 "value": 10,
 "timeUnit": "DAY"
 },
 "quantity": 1,
 "logoUrl": "/mp/media/.../file.png?sha=3e8a0899fe7e867f",
 "onceCost": 200,
 "monthlyCost": 200,
 "yearlyCost": 2400
 }
]

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code.

To find requests by IDs

Method	Endpoint
POST	/services/requests/search

Parameters

Name	Where	Type	Required	Example	Description
	body	string	✅️	["4402", "4302", "4301"]	Service request ID numbers represented as a list of string values.

type: application/json

["4402", "4302", "4301"]

Response

Response	Value	Notes
HTTP code	200	Successful response returns array of service request objects.
type	application/json	Not applicable.

type: application/json

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code.

To find a request by its ID

Method	Endpoint
GET	/services/requests/{requestId}

Parameters

Name	Where	Required	Example	Description
requestId	URL	✅️	"4402"	ID of the request.

Response

Response	Value	Notes
HTTP code	200	Successful response returns a service request object.
type	application/json	Not applicable.

type: application/json

{
 "id": "4402",
 "requestingUserId": "Allen",
 "requestForUserId": "Allen",
 "name": "New environment test",
 "description": "test",
 "excerpt": "test",
 "price": {
 "paymentType": "Free",
 "currency": "USD"
 },
 "status": {
 "id": "4402",
 "serviceId": "000000000004201",
 "status": "ACTIVE",
 "startTime": "2016-03-08T20:32:12.000+0000",
 "lastModifiedTime": "2016-03-08T20:32:12.000+0000"
 },
 "quantity": 1,
 "logoUrl": "/mp/media/.../file.png?sha=c9eb1a96d6eea52f",
 "onceCost": 0,
 "monthlyCost": 0,
 "yearlyCost": 0
 }

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code.

To find all answers submitted for the given request

Method	Endpoint
GET	/services/requests/{requestId}/answers

Parameters

Name	Where	Required	Description
requestId	URL	✅️	ID of the request.

Response

Response	Value	Notes
HTTP code	200	Successful response returns a question object with completed answers.
type	application/json	Not applicable.

type: application/json

[
{
   "questionnaireId": "1",
   "questionId": "0",
   "questionType": "TextField",
   "label": "text field 1",
   "options": [
     {
       "dataValue": "text 1",
       "displayValue": "text 1"
     }
    ],
   "answers": [
     "text 1"
    ]
},
{
   "questionnaireId": "1",
   "questionId": "1",
   "questionType": "TextField",
   "label": "text field 2",
   "options": [
     {
       "dataValue": "text 2",
       "displayValue": "text 2"
     }
    ],
   "answers": [
     "text 2"
    ]
}
]

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code.

Reviews

To retrieve all reviews

Method	Endpoint
GET	/reviews

Parameters

Name	Where	Type	Required	Default	Example	Description
serviceId	query	string	No		123	Retrieves reviews of a given service.
userId	query	string	No		hannah	Retrieves reviews of a given user. The platform variable $USER$ can be sent as the userId of the current user.
perPage	query	integer	No	-1	20	Page size. -1 for non-paginated search.
page	query	integer	No	1	1	Page number
sortBy	query	string	No		modifiedDate	Sorting criteria. Currently only "modifiedDate"
sortDirection	query	string	No	asc	asc	Sorting direction: either ascending or descending.
requestedfor	query	String	No		Mary	When a specific user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user.

Response

Response	Value	Notes
HTTP code	200	Successful response returns array of reviews objects.
type	application/json	Not applicable.

type: application/json

{
"reviews": [
   {
"id": "1",
"serviceId": "123",
"userId": "2345",
"title": "review title1",
"content": "review content1",
       "modifiedDate": "2015-08-20T00:24:22.000+0000"
},
{
"id": "2",
"serviceId": "124",
"userId": "2346",
"title": "review title2",
"content": "review content2",
       "modifiedDate": "2015-08-21T00:24:22.000+0000"
}
  ],
"pageSize": 10,
"page": 1,
"total": 2
}

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code.

To create a review for a given service

Method	Endpoint
POST	/reviews

Parameters

Name	Where	Type	Required	Example	Description
serviceId	body	string	✅️	"123"	ID of the service.
title	body	string	✅️	"review title1"	Title of the review.
content	body	string	✅️	"review content1"	Content of the review.

type: application/json

{
"serviceId": "123",
"title": "review title1",
"content": "review content1"
}

Response

Response	Value	Notes
HTTP code	201	Successful response returns no content.

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
HTTP code	422	Service ID is not found.
message	string	Error message with error code.
data	string	Error message description.

type: application/json

{
"message": "Service of id {id} not found."
}

To retrieve a review by its ID

Method	Endpoint
GET	/reviews/{reviewId}

Parameters

Name	Where	Required	Example	Description
reviewId	URL	Yes		ID of the review.
requestedfor	query	No	Mary	When a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user.

Response

Response	Value	Notes
HTTP code	200	Successful response returns a review object.
type	application/json	Not applicable.

type: application/json

{
"id": "1",
"serviceId": "123",
"userId": "2345",
"title": "review title1",
"content": "review content1",
"modifiedDate": "2015-08-20T00:24:22.000+0000"
}

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
HTTP code	404	Review with requested ID not found.
message	string	Error message with error code.
data	string	Error message description.

type: application/json

{
"message": "ERROR (302): Entry does not exist in database"
}

To update a review

Reviews can be updated only if the review was originally entered under the current user's account. Admin users cannot update reviews submitted by other users.

Method	Endpoint
PUT	/reviews/{reviewId}

Parameters

Name	Where	Type	Required	Example	Description
reviewId	URL		Yes		ID of the review to be updated.
title	body	string	No	"new title"	Updated title. If title and content are both empty, change will be ignored.
content	body	string	No	"new content"	Updated content. If title and content are both empty, the change will be ignored.

type: application/json

{
"title": "new title",
"content": "new content"
}

Response

Response	Value	Notes
HTTP code	200	Successful response returns no content.

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code.

To delete a review

Reviews can be deleted only if the review was originally entered under the current user's account. Admin users cannot delete reviews submitted by other users.

Method	Endpoint
DELETE	/reviews/{reviewId}

Parameters

Name	Where	Type	Required	Description
reviewId	URL		✅️	ID of the review to be deleted.

Response

Response	Value	Notes
HTTP code	200	Successful response returns no content.

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code.

Ratings

Rating is given as percentage (between 0 and 1)

To retrieves all ratings

Method	Endpoint
GET	/ratings

Parameters

Param Name	Where	Type	Required	Default	Example	Description
serviceId	body	string	No		123	Retrieves ratings of a given service.
userId	body	string	No		20	Retrieves ratings from a given user. $USER$ can be used for current user.
perPage	body	integer	No	-1	20	Page size. -1 for non-paginated search.
page	body	integer	No	-1	1	Page number.
requestedfor	query	String	No			When a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user.

Response

Response	Value	Notes
HTTP code	200	Successful response returns an array of ratings objects.
type	application/json	Not applicable.

type: application/json

{
"ratings": [
   {
"id": "1",
"serviceId": "123",
"userId": "2345",
"rating": 0.8,
       "modifiedDate": "2015-08-20T00:24:22.000+0000"
},
{
"id": "2",
"serviceId": "124"
"userId": "2345",
"rating": 0.7,
       "modifiedDate": "2015-08-20T00:24:22.000+0000"
}
  ],
"pageSize": 10,
"page": 1,
"total": 2
}

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code.

To create a rating for a service

Method	Endpoint
POST	/ratings

Parameters

Name	Where	Type	Required	Example	Description
serviceId	body	string	Yes	"123"	ID of the service to be rated.
rating	body	float	Yes	0.8	Rating value submitted as a percentage (number between 0 and 1).

type: application/json

{
"serviceId": "123",
"rating": 0.8
}

Response

Response	Value	Notes
HTTP code	201	Successful response returns no content.

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code.

To retrieve a rating by its ID

Method	Endpoint
GET	/ratings/{ratingId}

Parameters

Name	Where	Type	Example	Description
ratingId	URL			ID of the rating to retrieve.
requestedfor	query	String	Mary	When a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user.

Response

Response	Value	Notes
HTTP code	200	Successful response returns a rating object.
type	application/json	Not applicable.

type: application/json

{
"id": "1",
"serviceId": "123",
"userId": "2345",
"rating": 0.8
}

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code.

To update a rating

Ratings can be updated only if the rating was originally entered under the current user's account. Admin users cannot update ratings submitted by other users.

Method	Endpoint
PUT	/ratings/{ratingId}

Parameters

Name	Where	Type	Required	Example	Description
ratingId	URL		Yes	4321	The ID of the rating to update
rating	body	float	Yes	0.6	The rating value submitted as a percentage (number between 0 and 1).

type: application/json

{
"rating": 0.6
}

Response

Response	Value	Notes
HTTP code	200	Successful response returns no content.

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code.

Service migration

To export selected services

This endpoint packages service data and media files into a binary zip archive. Includes full catalog profiles, images, workflows, and questions

Method	Endpoint
POST	/services/export

Parameters

Name	Where	Type	Required	Example	Description
(array list)	body	string	Yes	["000000000012912", "000000000012913"]	List of service ids that are to be exported.

type: application/json

[
"000000000012912", "000000000012913", ...
]

Response

A zip file containing the exported services.

To import a service zip file

Extracts an uploaded binary zip file and creates services with full catalog profiles, images, workflows, and questions.

Method	Endpoint
POST	/services/import

Parameters

Name	Where	Type	Required	Description
(uploaded file)	body	binary data (zip file)	Yes	Upload requires the following form setting: Content-Disposition: form-data; name="file"; filename="{file name}" Content-Type: application/x-zip-compressed

Response

Response	Value	Notes
HTTP code	200	When import is successful.