Limited support This version of the product is in limited support. However, the documentation is available for your convenience. You will not be able to leave comments. Click here to view the documentation for the current version.

Endpoints in the BMC Digital Workplace Catalog REST API


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": "<p>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": "<p>test</p>",
    "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": "<p>test</p>",
    "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": "<p>fhyfgjhgjghghghjgh<br/></p>",
    "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
[
  {
    "id": "4402",
    "requestingUserId": "Allen",
    "requestForUserId": "Allen",
    "name": "New environment test",
    "description": "<p>test</p>",
    "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": "<p>test</p>",
    "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": "<p>fhyfgjhgjghghghjgh<br/></p>",
    "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 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": "<p>test</p>",
    "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

Default

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.

 

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*