This documentation supports the 20.02 version of BMC Digital Workplace Advanced.

To view an earlier version, select the version from the Product Version menu.

Endpoints in the BMC Digital Workplace Catalog REST API

This topic was edited by a BMC Contributor and has not been approved.  More information.

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

Related topics

Integrating BMC Digital Workplace Catalog REST API with the service catalog

Using the Digital Workplace Catalog 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 an authentication token

POST /users/login

Parameters

NameRequired/OptionalDescriptionTypeExampleNotes
idRequired

BMC Digital Workplace Catalog user login account (with the organization domain).

String<your_user>Locate this parameter in the request body. This parameter is not specified by default.
passwordRequiredPassword.String<your_password>Locate this parameter in the request body. This parameter is not specified by default.
 Example request body
{
	"id": "<your_user>",
	"password": "<your_password>"
}

Response

ResponseValueNotes
HTTP code200Application 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:

NameDescriptionType
messageError message with the error code.String
dataError message description.String

Categories

To retrieve a full category list

GET /categories

Parameters

NameRequired/OptionalDescriptionTypeExampleNotes
perPageOptionalPage size.Integer20This is a query parameter. Default for non-paginated search -1.
pageOptional

Page number.

Integer1This is a query parameter. Default 1.
 Example request body
{
  "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

ResponseValueNotes
HTTP code200Returns a category list object array.
typeapplication/jsonNot applicable.


Response properties

NameDescriptionType
pageSizePass through the request parameter.Integer
pagePass through the request parameter.Integer
categoriesCategory object array.Array
 Error handling

Failed requests return an error object with the following properties:

NameDescriptionType
messageError message with the error code.String

To retrieve descendants of a given category

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

GET /categories/{categoryId}/categories

Parameters

Name
Required
Description
Type
Example
Notes
categoryIdRequiredCategory ID to retrieve.String000000000000001Locate this parameter in the request URL. This parameter is not specified by default.
depthOptional

Depth of the category being retrieved.

Integer2This is a query parameter. Default 1. Allowed values: 1, 2, 3.
requestedforOptionalWhen a user is specified, the entitlement check is performed against the user. Otherwise, the entitlement check is performed against the current user.String"Mary"This is a query parameter. This parameter is not specified by default.
 Example request body
[
  {
    "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

Response
Value
Notes
HTTP code200Returns a category array object. If the requested categoryId does not exist or does not contain descendants, then an empty array is returned.
typeapplication/jsonNot applicable.


Response properties

NameDescriptionTypeNotes
idCategory ID used by the application.StringNot applicable.
guid

Unique ID used by the platform.

StringNot applicable.
nameCategory name.StringNot applicable.
categoryGroupId

Group to which the category belongs.

StringCurrently, there is only one category group, referenced as "Type of service".
parentIdID of the child's parent category.StringIf the parent ID is not available, null.
childCountNumber of direct descendant categories.IntegerNot applicable.
subCategoriesNullStringNot applicable.


 Error handling

Failed requests return an error object with the following properties:

Name
Description
Type
messageError message with the error code.String

To retrieve category groups

GET /categories/groups

Parameters

None.

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

Response

Response

Value
Notes
HTTP code200Application returns the category array.
typeapplication/jsonNot applicable.


Response properties

Name
Description
Type
idCategory group ID used by the application.String
guidUnique ID used by the platform.String
nameCategory group name.String
descriptionDescription of the category group.String
systemId

System ID of the category group.

String
groupStatusStatus of of the category group.String
childCountNumber of direct descendant categories.Integer
categoriesNullString


 Error handling

Failed requests return an error object with the following properties:

Name
Description
Type
messageError message with the error code.String

To retrieve categories of a given category group

GET /categories/groups/{categoryGroupId}/categories

Parameters

Name

Required/Optional

Description

Type

Example

Notes

categoryGroupIdRequiredCategory group ID to retrieve.String000000000000001Locate this parameter in the request URL. This parameter is not specified by default.
depthOptionalDepth of the category being retrieved.Integer2This is a query parameter. Default 1. Allowed values: 1, 2, 3.
requestedforOptionalWhen a user is specified, the entitlement check is performed against the user. Otherwise, the entitlement check is performed against the current user.
String"Mary"This is a query parameter. This parameter is not specified by default.


 Example request body
[
  {
    "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

Response

Value

Notes

HTTP code

200

Successful response returns the array of category objects.

type

application/json

Not applicable.


 Error handling

Failed requests return an error object with the following properties:

Name
Description
Type
messageError message with the error code.String

Services

To retrieve details of a single service item

GET /services/{serviceId}

Parameters

Name

Required/Optional

Description

Type

Example

Notes

serviceIdRequiredNot applicable.String 000000000000001Locate this parameter in the request URL.
requestedforOptionalWhen a user is specified, the entitlement check is performed against the user. Otherwise, the entitlement check is performed against the current user.
String"Mary"This is a query parameter.
 Example request body
{
  "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"
    }
  ]
}


Response

Response

Value

Notes

HTTP code

200

Successful response returns the array of service details.

type

application/json

Not applicable.
 Error handling

Failed requests return an error object with the following properties:

Name
Type
Description
messageStringError message with the error code.

To search for services

Search criteria can be 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.

{
	"serviceIds": ["%123%","%456","789%"],
	"title": "apple"
}
POST /services/search


Parameters

Name

Required/Optional

Description

Type

Example

Notes

perPageRequiredPage size.Integer20This is a query parameter. Default for non-paginated search -1.
pageRequired

Page number.

Integer1This is a query parameter. Default 1.
serviceIdsRequiredID of the service.String456Locate this parameter in the request body.
categoryIdRequiredID of the category.String476 Locate this parameter in the request body.
titleRequiredTitle of the service.String"Apple"Locate this parameter in the request body.
requestedforRequiredWhen a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user.String"Mary"This is a query parameter.
 Example request body
{
  "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
}


Response

Response

Value

Notes

HTTP code

200

Successful response receives an array of service objects.

type

application/json

Not applicable.


 Error handling

Failed requests return an error object with the following properties:

Name
Description
Type
messageError message with the error code.String

To retrieve the full catalog view setting of ON or OFF

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.


 Example response
true
false


 Error handling

Failed requests return an error object with the following properties:

Name
Description
Type
messageError message with the error code.String

Requests and questions

To initiate a request for a service by ID

POST /requests

Parameters

Name

Required/Optional

Description

Type

Example

Notes

serviceIdRequiredID of the service.String 456Locate this parameter in the request body.
excludedServiceIdsRequiredA list of service revision IDs that will be excluded from the request bundle.String457Locate this parameter in the request body.
requestForUserIds Required

A list of user IDs for which the service is requested.

Best Practice

BMC recommends that you limit the number of users per request to 20.
List of strings["Mary", "Peter"]Locate this parameter in the request body. By default, the current user is displayed.
dependenciesRequiredNot applicable.String{serviceRequestId: string}Locate this parameter in the request body.
quantityRequiredThe service request quantity.Integer1Locate this parameter in the request body. Default 1.
referenceRequestIdOptionalA prior request ID, if relevant.String5678Locate this parameter in the request body.
myStuffItemIdRequiredThe My Stuff item ID.String9012Locate this parameter in the request body.
onBehalfOfUserIdRequiredThe user ID on behalf of which the service request is being made.String9013Locate this parameter in the request body.
questionsOptionalA list of common answers for relevant service request questions.List of strings
 Example request body
Example
{ ID: string id 
Example: AGGADGG8ECDC0AP5X5L1P5A76XAIJO guid: 
string GUID Example: AGGADGG8ECDC0AP5X5L1P5A76XAIJO
createDate: date-time 
When the record was created 
Example: 2018-09-27T18:37:18.000+0000 
modifiedDate: date-time 
When the record was last modified 
Example: 2018-09-27T18:37:18.000+0000 
rxId: string 
The request identifier in the server database 
(value is auto-generated) 
Example: 1 
QuestionnaireId: string 
The questionnaire ID, provided the question 
belongs to a questionnaire (value is auto-generated). 
Example: 12803 
Question Id: string* 
The question ID for the question being answered. 
Example: 97f8a510-4281-f441-888b-682eaf7c340e 
serviceRequestId: string 
The service request ID 
Example: 40597
displayValueOfAnswers: [ A list of answer display values
corresponding to *answers* entries string ] 
answers: [ A list of acceptable answers for the
question identified by *questionId*.
]* }
Locate this parameter in the request body. If you choose to include it in the response, you must provide at least the questionId and the associated answer. If your service request is for multiple users, they all must have provided the same answer. Multiple answers for a single question are typically only relevant for the multiple-choice questions string.

 Example request body
{
  "serviceId" : "2417"
}


 Example request body for the bulk order
{
  "serviceId" : "202",
  "requestForUserIds":["hannah_admin"],
  "questions":[{
  	"answers": ["Peter"],
  	"questionId": "7f5c973a-9faa-54a8-0806-f756c7cfb13e"
  }]
}

You can obtain the question ID in advance. 

Response

Response

Value

Notes

HTTP code

200

Successful response returns the array of questions.

Note

The structure of the questionnaire may vary between services, see Creating service questionnaires.

type

application/json

Not applicable.
 Example error request
{
    "serviceId": "2417",
    "bundleRequestId": null,
    "requests": [
        {
            "requestId": "2920",
            "externalId": null,
            "dependencies": null,
            "questionnaire": null,
            "onStartChanges": {},
            "serviceId": "2417"
        }
    ],
    "requestErrors": []
}


 Error handling

Failed requests return an error object with the following properties:

Name
Description
Type
messageError message with the error code.String

To get a service request questionnaire

This step is optional if you request a bulk order.

GET /requests/{id}/questionnaire

Parameters

Name

Required/Optional

Description

Type

Notes

idRequiredThe service request ID of a new request.StringLocate this parameter in the request URL.
prefillRequestIdsOptional

A list of completed service request IDs to search for saved answers while re-requesting a service.

StringThis a query parameter.
 Example request body
{
    "questionnaire": {
        "id": "203",
        "guid": null,
        "createDate": null,
        "modifiedDate": null,
        "rxId": null,
        "summary": null,
        "workflowId": null,
        "questionnaireGroupId": null,
        "name": null,
        "bulkRequestedForUserLimit": 1,
        "pages": [
            {
                "id": "662576ab-d01d-ba5c-fffd-380e7aacbb00",
                "externalId": null,
                "perUser": false,
                "title": "",
                "pageItems": [
                    {
                        "type": "TextField",
                        "id": "7f5c973a-9faa-54a8-0806-f756c7cfb13e",
                        "externalId": null,
                        "perUser": false,
                        "visible": true,
                        "useDefaultLocale": false,
                        "label": "Your name",
                        "description": "<p>What is your name</p>",
                        "required": false,
                        "hidden": false,
                        "readOnly": false,
                        "answerSource": "SAVED",
                        "tags": [],
                        "defaultAnswer": "Peter",
                        "maxLength": null,
                        "confidential": false
                    }
                ]
            }
        ],
        "useDefaultLanguage": false
    }
}


Response

Response

Value

HTTP code

200

type

application/json


 Error handling

Failed requests return an error object with the following properties:

Name
Description
Type
messageError message with the error code.String

To send an answer to a question

This step is optional if you request a bulk order. 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.

POST /services/{serviceId}/questionnaire/answers

Parameters

Name

Required

Description

Type

Notes

serviceIdRequiredThe ID of the service.StringLocate this parameter in the request URL.
questionnaireIdOptionalThe ID of the questionnaire.StringLocate this parameter in the request body.
questionIdOptionalThe ID of the question.StringLocate this parameter in the request body.
answersOptionalAnswers to the questionnaire.List of stringsLocate this parameter in the request body.
serviceRequestIdOptionalThe ID of the service request.StringLocate this parameter in the request body.
 Example request body
{
  "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.

 Example response
{
    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:

Name
Description
Type
messageError message with the error code.String

To submit a bulk service request order

POST /orders

Parameters

Name

Required/Optional

Description

Type

Where

requests Required

A list of request IDs representing the requests being placed.

List of stringsLocate this parameter in the request body.
 Example request body
{
  "requests" : [{"id" : "2920"},{"id" : "2921"},{"id" : "2922"}]
}

Response

Response

Value

Notes

HTTP code

200

Successful response returns an empty content body.

type

application/json

Not applicable.


 Error handling

Failed requests return an error object with the following properties:

Name
Description
Type
messageError message with the error code.String
 Example error request
{
    "id": "2916",
    "requestErrors": [],
    "requestDetails": [],
    "expectedDate": null
}

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

GET /services/{serviceId}/myrequests

Parameters

Name

Required/Optional

Description

Type

Notes

Example

serviceIdRequiredID of the service.StringLocate this parameter in the request URL.456
perPageOptional

Page size.

IntegerThis is a query parameter. Default 10.20
pageOptionalPage number.IntegerThis is a query parameter. Default 1.1
 Example request body
{
    "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"
        }
    ]
}

Response

Response

Value

HTTP code

200

type

application/json


 Error handling

Failed requests return an error object with the following properties:

Name
Description
Type
messageError message with the error code.String

To find requests

Use this endpoint to display a list of service requests on the user's request timeline. If a user is not specified, all requests are displayed.

GET /services/requests

Parameters

Name

Required/Optional

Description

Type

Notes

Example

requestedfor

Required

Filter requests that are requested for the specified user.

String

This is a query parameter.

"Mary"

requestedby

Required

Filter requests that are requested by the specified user.

String

This is a query parameter.

"Francie"

sinceRequiredFilter requests that are updated since the specified date.StringThis is a query parameter.

Tue, 08 Mar 2016 17:49:05 GMT

maxRequiredMaximum amount of requests that will be retrieved.IntegerThis is a query parameter.30
 Example request body
[
  {
    "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
  }
]


Response

Response

Value

Notes

HTTP code

200

Successful response returns a requests object array.

type

application/json

Not applicable.


 Error handling

Failed requests return an error object with the following properties:

Name
Description
Type
messageError message with the error code.String

To find requests by IDs

POST /services/requests/search

Parameters

Name

Required/Optional

Description

Type

Example

Notes

serviceIdRequiredService request ID numbers represented as a list of string values.String
["4402", "4302", "4301"]
Locate this parameter in the request body.
 Example request body
["4402", "4302", "4301"]

Response

Response

Value

Notes

HTTP code

200

Successful response returns the array of service request objects.

type

application/json

Not applicable.
 Example response
[
  {
    "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:

Name
Description
Type
messageError message with the error code.String

To find a request by its ID

GET /services/requests/{requestId}

Parameters

Name

Required/Optional

Description

Type

Example

Notes

requestIdRequiredID of the request.String"4402"Locate this parameter in the request URL.
 Example request body
  {
    "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
  }


 Response

Response

Value

Notes

HTTP code

200

Successful response returns a service request object.

type

application/json

Not applicable.


 Error handling

Failed requests return an error object with the following properties:

Argument
Description
Type
messageError message with the error code.String

To find all answers submitted for the given request

GET /services/requests/{requestId}/answers

Parameters

Name

Required/Optional

Description

Type

Notes

requestIdRequiredID of the request.StringLocate this parameter in the request URL.
 Example request body
[
  {
    "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"
    ]
  }
]


Response

Response

Value

Notes

HTTP code

200

Successful response returns a question object with completed answers.

type

application/json

Not applicable.


 Error handling

Failed requests return an error object with the following properties:

Name
Description
Type
messageError message with the error code.String

Reviews

To retrieve all reviews

GET /reviews

Parameters

Name

Required/Optional

Description

Type

Example

Notes

serviceId

Optional

Retrieves reviews of a given service.

String

123

This is a query parameter.
userIdOptionalRetrieves reviews of a given user. The platform variable $USER$ can be sent as the userId of the current user.String"hannah"This is a query parameter.

perPage

Optional

Page size.

Integer

20

This is a query parameter. Default -1 for non-paginated search.

page

Optional

Page number.

Integer

1

This is a query parameter. Default 1.

sortBy

Optional

Sorting criteria.

String

modifiedDate

This is a query parameter. Currently, only "modifiedDate" is available.

sortDirection

Optional

Sorting direction: either ascending or descending.

String

asc

This is a query parameter. Default asc.
requestedforOptionalWhen a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user.
String"Mary"This is a query parameter.


 Example request body
{
  "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
}


Response

Response

Value

Notes

HTTP code

200

Successful response returns the array of reviews objects.

type

application/json

Not applicable.


 Error handling

Failed requests return an error object with the following properties:

Name
Description
Type
messageError message with the error code.String

To create a review for a given service

POST /reviews 

Parameters

Name

Required/Optional

Description

Type

Example

Notes

serviceIdRequiredID of the service.String"123"Locate this parameter in the request body.
titleRequired

Title of the review.

String"review title1"Locate this parameter in the request body.
contentRequiredContent of the review.String"review content1"Locate this parameter in the request body.
 Example request body
{
  "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:

Name
Description
Type

HTTP code

Service ID is not found.

201

messageError message with the error code.String
data

Error message description.

String
 Example error handling
{
  "message": "Service of id {id} not found."
}

To retrieve a review by its ID

GET /reviews/{reviewId}

Parameters

Name

Required/Optional

Description

Example

Notes

reviewIdRequiredID of the review. 465Locate this parameter in the request URL.
requestedforOptionalWhen a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user.
"Mary"This is a query parameter.


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

Response

Response

Value

Notes

HTTP code

200

Successful response returns a review object.

type

application/json

Not applicable.


 Error handling

Failed requests return an error object with the following properties:

Name
Description
Type
HTTP codeReview with the requested ID not found.404
messageError message with the error code.String
data

Error message description.

String


 Example error request
{
  "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.

PUT /reviews/{reviewId} 


Parameters

Name

Required/Optional

Description

Type

Example

Notes

reviewIdRequiredID of the review to be updated.String 675Locate this parameter in the request URL.
titleOptional

Updated title.

String"new title"Locate this parameter in the request body. If both the title and the content parameters are empty, change will be ignored.
contentOptionalUpdated content.String"new content"Locate this parameter in the request body. If both the title and the content parameters are empty, change will be ignored.
 Example request body
{    
  "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:

Name
Description
Type
messageError message with the error code.String

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.

DELETE /reviews/{reviewId} 

Parameters

Name

Required/Optional

Description

Type

Notes

reviewIdRequiredID of the review to be deleted.StringLocate this parameter in the request URL.

Response

Response

Value

Notes

HTTP code

200

Successful response returns no content.


 Error handling

Failed requests return an error object with the following properties:

Name
Description
Type
messageError message with the error code.String

Ratings

Rating is given as percentage (between 0 and 1).

To retrieve all ratings

GET /ratings

Parameters

Name

Required/Optional

Description

Type

Example

Notes

serviceId

Optional

Retrieves ratings of a given service.

String

123

Locate this parameter in the request body.

userId

Optional

Retrieves ratings from a given user. $USER$ can be used for current user.

String

20

Locate this parameter in the request body.

perPage

Optional

Page size.

Integer

20

Locate this parameter in the request body. Default -1 for non-paginated search..

page

Optional

Page number.

Integer

1

Locate this parameter in the request body. Default 1.
requestedforOptionalWhen a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user.
String "Hannah"This is a query parameter.
 Example request body
{
  "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
}

Response

Response

Value

Notes

HTTP code

200

Successful response returns an array of ratings objects.

type

application/json

Not applicable.


 Error handling

Failed requests return an error object with the following properties.

Argument
Description
Type
messageError message with the error code.String

To create a rating for a service

POST /ratings

Parameters

Name

Required/Optional

Description

Type

Example

Where

serviceIdRequiredID of the service to be rated.String"123"Locate this parameter in the request body.
ratingRequiredRating value submitted as a percentage (number between 0 and 1).Float0.8Locate this parameter in the request body.
 Example request body
{
  "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:

Name
Description
Type
messageError message with the error code.String

To retrieve a rating by its ID

GET /ratings/{ratingId}

Parameters

Name

Required/Optional

Description

Type

Example

Notes

ratingIdRequiredID of the rating to retrieve.String 456Locate this parameter in the request URL.
requestedforRequiredWhen a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user.
String"Mary"This is query parameter.

Response

Response

Value

Notes

HTTP code

200

Successful response returns a rating object.

type

application/json

Not applicable.
 Example response
{
  "id": "1",
  "serviceId": "123",
  "userId": "2345",
  "rating": 0.8
}


 Error handling

Failed requests return an error object with the following properties:

Name
Description
Type
messageError message with the error code.String

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.

PUT /ratings/{ratingId}

Parameters

Name

Required/Optional

Description

Type

Example

Notes

ratingIdRequiredThe ID of the rating to update.String"4321"Locate this parameter in the request URL.
ratingRequired

The rating value submitted as a percentage (number between 0 and 1).

Float0.6Locate this parameter in the request body.
 Example request body
{
  "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:

Name
Description
Type
messageError message with the error code.String

Service migration

To export selected services

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

POST /services/export

Parameters

NameRequired/OptionalDescriptionTypeExampleNotes
(array list) YesList of the service IDs to be exported.String["000000000012912", "000000000012913"]Locate this parameter in the request body.
 Example request body
[
  "000000000012912", "000000000012913", ...
]

Response

A .zip file with the exported services.

To import a service .zip file

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

POST /services/import


Parameters

NameRequired/OptionalDescriptionTypeNotes
(uploaded file)Required

The service IDs to be imported.

Binary data (.zip file)Locate this parameter in the request body.

The following form setting is required:

Content-Disposition: form-data; name="file"; filename="{file name}" Content-Type: application/x-zip-compressed

Response

Response

Value

Notes

HTTP code

200

Import is successful.
Was this page helpful? Yes No Submitting... Thank you

Comments