This documentation supports the 22.1 version of BMC Helix Digital Workplace Basic and BMC Helix Digital Workplace Advanced. Icons distinguish capabilities available only for the Advanced and External license levels. For more information, see License types and features.

Endpoints in the BMC Helix Digital Workplace Catalog REST API

BMC Helix Digital Workplace Catalog API follows the REST architectural style. JSON is used for request and response bodies. The following headers are the most common for all requests: 

  • default-bundle-scope—myit-sb
  • Content-Type—application/json
  • X-Requested-By—<any_value>

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

Related topics

Implementing BMC Helix Digital Workplace Catalog REST API

Using the Digital Workplace Catalog API Open link

Authentication

Within BMC Helix 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 BMC Helix Digital Workplace Catalog have the same access permissions. 

To request an authentication token

POST /users/login

Parameters

NameRequired/OptionalDescriptionTypeExampleNotes
idRequired

BMC Helix Digital Workplace Catalog user login account.

Stringhannah_admin@calbro.comLocate 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.
{
	"id": "<your_user>",
	"password": "<your_password>"
}

Response

ResponseValueNotes
HTTP code200Application returns an authentication token that is valid for about half an hour.

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.

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
{
  "pageSize": 5,
  "page": 1,
  "categories": [
    {
      "id": "1234",
      "guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVD",
      "name": "Accounts, Security, and IDs",
      "categoryGroupId": "1234",
      "parentId": null,
      "childCount": 5,
      "subCategories": null
    },
    {
      "id": "1234",
      "guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVE",
      "name": "User accounts and account access",
      "categoryGroupId": "1234",
      "parentId": "1234",
      "childCount": 0,
      "subCategories": null
    },
    {
      "id": "1234",
      "guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVF",
      "name": "System accounts",
      "categoryGroupId": "1234",
      "parentId": "1234",
      "childCount": 0,
      "subCategories": null
    },
    {
      "id": "1234",
      "guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVG",
      "name": "Access requests",
      "categoryGroupId": "1234",
      "parentId": "1234",
      "childCount": 0,
      "subCategories": null
    },
    {
      "id": "1234",
      "guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVH",
      "name": "IDs, badges, and facility access",
      "categoryGroupId": "1234",
      "parentId": "1234",
      "childCount": 0,
      "subCategories": null
    }
  ],
  "total": 123
}

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.String1234Locate 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.

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.
[
  {
    "id": "1234",
    "guid": null,
    "name": "User accounts and account access",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  },
  {
    "id": "1234",
    "guid": null,
    "name": "System accounts",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  },
  {
    "id": "1234",
    "guid": null,
    "name": "Access requests",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  },
  {
    "id": "1234",
    "guid": null,
    "name": "IDs, badges, and facility access",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  },
  {
    "id": "1234",
    "guid": null,
    "name": "Remote access",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  }
]
  

To retrieve category groups

GET /categories/groups

Parameters

None.

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
[
  {
    "id": "1234",
    "guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVC",
    "name": "Type of Service",
    "description": "",
    "systemId": "type-of-service",
    "groupStatus": "ACTIVE",
    "childCount": 18,
    "categories": null
  }
]


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.String1234Locate 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.

Response

Response

Value

Notes

HTTP code

200

Successful response returns the array of category objects.

type

application/json

Not applicable.
[
  {
    "id": "1234",
    "guid": null,
    "name": "User accounts and account access",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  },
  {
    "id": "1234",
    "guid": null,
    "name": "System accounts",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  },
  {
    "id": "1234",
    "guid": null,
    "name": "Access requests",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  },
  {
    "id": "1234",
    "guid": null,
    "name": "IDs, badges, and facility access",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  },
  {
    "id": "1234",
    "guid": null,
    "name": "Remote access",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  }
]

Services

To retrieve details of a single service item

GET /services/{serviceversionId}

Parameters

Name

Required/Optional

Description

Type

Example

Notes

serviceversionIdRequiredNot applicable.String 1234Locate 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.

Response

Response

Value

Notes

HTTP code

200

Successful response returns the array of service details.

type

application/json

Not applicable.
{
  "serviceType": "Desktop",
  "templateType": "SERVICE",
  "id": "1234",
  "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": "1234",
    "name": "Coke Services"
  },
  "categories": [
    {
      "id": "1234",
      "name": "Computer software",
      "categoryGroupId": "1234",
      "parentId": null,
      "childCount": 0,
      "subCategories": null
    },
    {
      "id": "1234",
      "name": "Graphics and design",
      "categoryGroupId": "1234",
      "parentId": "1234",
      "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"
    }
  ]
}

To search for services

This API returns only published services. Search criteria can be serviceversionIds, categoryId, or free text for a single service name or tag.

POST /services/search

However, multiple search criteria cannot be used in a same call. Only one search criterion must be used in the request body. Wildcards are also not supported.

{
	"title": "Apple"
}

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.
serviceversionIdsRequiredID 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.

Response

Response

Value

Notes

HTTP code

200

Successful response receives an array of service objects.

type

application/json

Not applicable.


{
  "services": [
    {
      "serviceType": "Cloud Software 1",
      "templateType": "SERVICE",
      "id": "1234",
      "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": "1234",
          "name": "Collaboration tools",
          "categoryGroupId": "1234",
          "parentId": "1234",
          "childCount": 0,
          "subCategories": null
        },
        {
          "id": "1234",
          "name": "Productivity",
          "categoryGroupId": "1234",
          "parentId": "1234",
          "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": "1234",
      "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": "1234",
          "name": "Computer software",
          "categoryGroupId": "1234",
          "parentId": null,
          "childCount": 0,
          "subCategories": null
        },
        {
          "id": "1234",
          "name": "Collaboration tools",
          "categoryGroupId": "1234",
          "parentId": "1234",
          "childCount": 0,
          "subCategories": null
        },
        {
          "id": "1234",
          "name": "Business",
          "categoryGroupId": "1234",
          "parentId": "1234",
          "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
}


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.


true
false


Requests and questions

To initiate a request for a service by ID

POST /requests

Parameters

Name

Required/Optional

Description

Type

Example

Notes

serviceversionIdRequiredID of the service.String 456Locate this parameter in the request body.
excludedServiceversionIdsRequiredA 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: We recommend limiting 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
{ 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.

{
  "serviceversionId" : "2417"
}


{
  "serviceversionId" : "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.

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

type

application/json

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


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.

Response

Response

Value

HTTP code

200

type

application/json

{
    "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
    }
}


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. Each required question must be answered before the request can be submitted.

POST /services/{serviceversionId}/questionnaire/answers

Parameters

Name

Required

Description

Type

Notes

serviceversionIdRequiredThe 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.
{
  "questionnaireId": "1234",
  "questionId": "0",
  "answers": ["My First Name"],
  "serviceRequestId": "1234" 
}

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.

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

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.
{
  "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.


{
    "id": "2916",
    "requestErrors": [],
    "requestDetails": [],
    "expectedDate": null
}

To create and submit a service request in a single API call

POST /orders/requests

Parameters

Name

Required/Optional

Description

Type

Where

titleOptional

The order title of the new service request.

In BMC Helix Digital Workplace, this is displayed as the Order Description.

StringLocate this parameter in the request body.
collaboratorsEnabledOptional

If this parameter is true, the new service request is automatically shared with the user's default group of collaborators.

If this parameter is false, the new service request is not automatically shared.

The default is false.

BooleanLocate this parameter in the request body.
serviceRequestsRequired

A list of service requests, using the properties described in the following table.

ListLocate this parameter in the request body.

serviceRequests properties

Name

Required/Optional

Description

Type
serviceversionIdOptional

The ID of the service to be requested.

String
requestForUserIdsOptional

A list of user IDs that require the service.

List
excludedServiceversionIdsOptional

If the request is for a bundle, a list of service IDs in the bundle that should be excluded.

List
dependenciesOptional

A list of IDs of dependent (child) services that are associated with this service.

List
quantityOptional

The order quantity for the request.

If this property is not included, the default is 1.

Integer
referenceRequestIdOptional

The ID of a previously created request that is linked to this request.

String
myStuffItemIdOptional

The ID of the service request on the user's My Stuff page.

String
onBehalfOfUserIdOptional

The user ID that the service request is made on behalf of, if any.

String
requestedByUserIdOptional

The user ID that requests the service.

String
summaryOptional

A summary of the request.

In BMC Helix Digital Workplace, this is displayed as the description at the top of the order page.

String
externalActivitiesRequired

A list of external activities from sources such as BMC Helix ITSM, using the properties described in the following table.

List

externalActivities properties

Name

Required/Optional

Description

TypeNotes
externalActivityIdRequired

The unique ID of the external activity. For example, the Instance ID of a BMC Helix ITSM ticket.

StringNA
externalActivityDisplayIdOptional

The display ID, such as a work order ID, of the external activity.

StringNA
externalActivityTypeOptional

The type of the external activity.

StringNA
externalSubCatalogId

Optional

(but see the Notes column)

The ID of the subcatalog that the external activity uses.

StringAt least one of externalSubCatalogId,  connectionName, or connectionId must be provided.
connectionName

Optional

(but see the Notes column)

The connection name for the BMC Helix ITSM connector.

String
connectionId

Optional

(but see the Notes column)

The connection ID for the BMC Helix ITSM connector.

String
{
    "title": "simple order request",
    "collaboratorsEnabled" : false,
    "serviceRequests": [
        {
            "serviceversionId": "2",
            "quantity": 1,
            "myStuffItemId": "",
            "externalActivities": [
                {
                    "externalActivityId": "IDGADG1AAT7X5AR7LUAUR7LUAUDC30",
                    "externalActivityDisplayId": "INC000000001101",
                    "externalActivityType": "HPD:Help Desk",
                    "connectionName": "Remedy"
                },
                {
                    "externalActivityId": "IDGADG1AAT7X5AR7LU41R7LU41DF2G",
                    "externalActivityDisplayId": "CRQ000000001103",
                    "externalActivityType": "CHG:Infrastructure Change",
                    "connectionName": "Remedy"
                }
            ]
        }
    ]
}

Response

Response

Value

Notes

HTTP code

200

NA

type

object

Returned object is of type SubmitServiceOrderResponseDto


{
    "id": "204",
    "requestErrors": [],
    "requestDetails": [
        {
            "id": "208",
            "expectedDate": null,
            "generatesSrmRequest": false,
            "requestErrors": null,
            "collaborators": null
        }
    ],
    "expectedDate": null
}

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

GET /services/{serviceversionId}/myrequests

Parameters

Name

Required/Optional

Description

Type

Notes

Example

serviceversionIdRequiredID 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

Response

Response

Value

HTTP code

200

type

application/json

{
    "totalSize": 2,
    "data": [
        {
            "id": "1234",
            "serviceversionId": "1234",
            "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": "1234",
            "serviceversionId": "1234",
            "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"
        }
    ]
}


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

Response

Response

Value

Notes

HTTP code

200

Successful response returns a requests object array.

type

application/json

Not applicable.
[
  {
    "id": "4402",
    "requestingUserId": "Allen",
    "requestForUserId": "Allen",
    "name": "New environment test",
    "description": "<p>test</p>",
    "excerpt": "test",
    "price": {
      "paymentType": "Free",
      "currency": "USD"
    },
    "status": {
      "id": "4402",
      "serviceversionId": "1234",
      "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",
      "serviceversionId": "1234",
      "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",
      "serviceversionId": "1234",
      "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
  }
]

To find requests by IDs

POST /services/requests/search

Parameters:

Name

Required/Optional

Description

Type

Example

Notes

serviceRequestIds RequiredService request ID numbers represented as a list of string values.String
["4402", "4302", "4301"]
Locate this parameter in the request body.
requestedFor OptionalFilters service request IDs by requestedFor. String
"Mary"
This is a query parameter.
requestedByOptionalFilters service request IDs by requestedBy.String"Francie"This is a query parameter.
["4402", "4302", "4301"]

Response

Response

Value

Notes

HTTP code

200

Successful response returns the array of service request objects.

type

application/json

Not applicable.
[
  {
    "id": "4402",
    "requestingUserId": "Allen",
    "requestForUserId": "Allen",
    "name": "New environment test",
    "description": "<p>test</p>",
    "excerpt": "test",
    "price": {
      "paymentType": "Free",
      "currency": "USD"
    },
    "status": {
      "id": "4402",
      "serviceversionId": "1234",
      "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",
      "serviceversionId": "1234",
      "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",
      "serviceversionId": "1234",
      "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
  }
]


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.

 Response

Response

Value

Notes

HTTP code

200

Successful response returns a service request object.

type

application/json

Not applicable.
  {
    "id": "4402",
    "requestingUserId": "Allen",
    "requestForUserId": "Allen",
    "name": "New environment test",
    "description": "<p>test</p>",
    "excerpt": "test",
    "price": {
      "paymentType": "Free",
      "currency": "USD"
    },
    "status": {
      "id": "4402",
      "serviceversionId": "1234",
      "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
  }

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.

Response

Response

Value

Notes

HTTP code

200

Successful response returns a question object with completed answers.

type

application/json

Not applicable.
[
  {
    "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"
    ]
  }
]

To retrieve all comments posted to the given request

GET /services/requests/{requestId}/activities

Parameters

Name

Required/Optional

Description

Type

Notes

requestIdRequiredID of the request.StringLocate this parameter in the request URL.

Response

Response

Value

Notes

HTTP code

200

Successful response returns an object with each comment.

type

application/json

Not applicable.
[
    {
        "id": "10002",
        "serviceRequestId": "10012",
        "message": "Test",
        "activityLogType": null,
        "authorLoginId": "hannah_admin",
        "authorFullName": "Hannah",
        "createDate": "2022-08-24T22:29:41.000+0000",
        "modifiedDate": "2022-08-24T22:29:41.000+0000",
        "visibility": "PUBLIC",
        "attachments": []
    },
    {
        "id": "10001",
        "serviceRequestId": "10012",
        "message": "Doug",
        "activityLogType": null,
        "authorLoginId": "hannah_admin",
        "authorFullName": "Hannah",
        "createDate": "2022-08-24T22:14:43.000+0000",
        "modifiedDate": "2022-08-24T22:14:43.000+0000",
        "visibility": "PUBLIC",
        "attachments": []
    }
]

To add a comment to the given request

POST /services/requests/{requestId}/activities

Parameters

Name

Required/

Optional

Description

Type

Notes

requestIdRequiredID of the request.StringLocate this parameter in the request URL.
textRequiredText of the comment.StringThis is a query parameter.
visibilityRequiredPUBLIC for  the comment to be visible to users, or INTERNAL for the comment to be visible only to the creator.StringThis is a query parameter.
broadcastRequiredWhether to notify users subscribed to this request that a comment has been made. BooleanThis is a query parameter.
authorLoginID OptionalThe login ID of the user making the comment.StringThis is a query parameter.  The default is the currently logged-in user.
{
        "text":"This is a comment",
        "visibility":"PUBLIC",
        "broadcast":true
}

Response

Response

Value

Notes

HTTP code

200

Successful response returns an object with each comment.

type

application/json

Not applicable.
{
    "id": "10003",
    "serviceRequestId": "10012",
    "message": "This is a comment",
    "activityLogType": null,
    "authorLoginId": "hannah_admin",
    "authorFullName": null,
    "createDate": "2022-08-25T21:34:59.000+0000",
    "modifiedDate": "2022-08-25T21:34:59.000+0000",
    "visibility": "PUBLIC",
    "attachments": []
}

To add an attachment to the given request

POST /services/requests/{requestId}/attachments

Parameters

Name

Required/

Optional

Description

Type

Notes

requestIdRequiredID of the request.StringLocate this parameter in the request URL.
activityLogRequiredText of a comment associated with the attachment.StringThis is a query parameter.
visibilityRequiredPUBLIC for  the attachment to be visible to users, or INTERNAL for the comment to be visible only to the creator.StringThis is a query parameter.
broadcastRequiredWhether to notify users subscribed to this request that an attachment has been made. BooleanThis is a query parameter.
authorLoginID OptionalThe login ID of the user making the attachment.StringThis is a query parameter.  The default is the currently logged-in user.
fileRequiredThe file to be attached.BinaryThis is a query parameter.
attachmentNamesRequiredThe name of the file to be attached.StringThis is a query parameter.

Response

Response

Value

Notes

HTTP code

200

Successful response returns an object with each comment.

type

application/json

Not applicable.

Reviews

To retrieve all reviews

GET /reviews

Parameters

Name

Required/Optional

Description

Type

Example

Notes

serviceversionId

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.


Response

Response

Value

Notes

HTTP code

200

Successful response returns the array of reviews objects.

type

application/json

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

To create a review for a given service

POST /reviews 

Parameters

Name

Required/Optional

Description

Type

Example

Notes

serviceversionIdRequiredID 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.
{
  "serviceversionId": "123",
  "title": "review title1",
  "content": "review content1"
}

Response

Response

Value

Notes

HTTP code

201

Successful response returns no content.


{
  "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.

Response

Response

Value

Notes

HTTP code

200

Successful response returns a review object.

type

application/json

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


{
  "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.
{    
  "title": "new title",
  "content": "new content"
}

Response

Response

Value

Notes

HTTP code

200

Successful response returns no content.


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.


Ratings

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

To retrieve all ratings

GET /ratings

Parameters

Name

Required/Optional

Description

Type

Example

Notes

serviceversionId

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.

Response

Response

Value

Notes

HTTP code

200

Successful response returns an array of ratings objects.

type

application/json

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


To create a rating for a service

POST /ratings

Parameters

Name

Required/Optional

Description

Type

Example

Where

serviceversionIdRequiredID 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.
{
  "serviceversionId": "123",
  "rating": 0.8
}

Response

Response

Value

Notes

HTTP code

201

Successful response returns no content.


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.
{
  "id": "1",
  "serviceversionId": "123",
  "userId": "2345",
  "rating": 0.8
}


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.
{
  "rating": 0.6
}

Response

Response

Value

Notes

HTTP code

200

Successful response returns no content.


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.
[
  "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.


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
HTTP codeAn object with the requested ID is not found.404
Was this page helpful? Yes No Submitting... Thank you

Comments

  1. Matthias Werninghaus

    Can you verify the part "To search for services" The search by title does not work for me.

    I want to search for a special service with a given name?

    And you write:

    However, multiple search criteria cannot be used in a same call. Wildcards are also not supported.

    And in the example you use wildcards? { "serviceIds": ["%123%","%456","789%"], "title": "apple" }

    Aug 04, 2023 12:55
  2. Matthias Werninghaus

    And can you please add Swagger UI functionality for this interface.

    Aug 04, 2023 02:30
    1. Mariia Matskiv

      Hello Matthias Werninghaus ,

      Thank you for your query. Please allow us to address this issue on our end and get back to you. 

      Best regards,

      Mariia

      Aug 15, 2023 09:14
      1. Mariia Matskiv

        Hello Matthias Werninghaus,

        We hope this message finds you well! We've revised the description of the To search for services API and updated our documentation to include an accurate example of an API call.

        Please take note that searching by title works only if the title parameter is the sole criterion for the search. Other search criteria can't be included in the request body. Also, this API returns only the published services.

        Thank you for your suggestion to include Swagger examples! We plan to introduce this update in the nearest future. 

        If you have any questions or require additional assistance, please let us know. 

        Best regards,
        Mariia


        Aug 17, 2023 07:23
  3. Deepak Nair

    Hello Team,

    POST /services/requests/{requestId}/attachments does not work and throw error below error. Could you please look into this.

    Error: { "messageType": "ERROR", "messageNumber": 8790, "messageText": "Unknown system error", "appendedText": "HTTP 404 Not Found" }

    Aug 23, 2023 12:26
    1. Aaditi Lakade

      Hello, Deepak Nair

      Thank you for sharing the exact error. Allow us to check this API at our end and I shall get back to you. 

      Thanks, 

      Aaditi

      Aug 24, 2023 04:23
      1. Aaditi Lakade

        Hello, Deepak Nair

        This API worked at our end. It is possible that the logged in user does not have access to the service request. Could you please check again with the correct permissions and access? 

        I am closing this thread for now. However, feel free to get back to us with other queries or comments. 

        Thanks, 

        Aaditi

        Aug 28, 2023 12:46
        1. Patrik Stanz

          Hi! I got the same error. Resolved it with an additional header, like shown here: https://www.youtube.com/watch?v=McXhjTYzolM

          X-Requested-By = XMLHttpRequest

          So please update the docu accordingly

          Feb 05, 2024 10:08
          1. Aaditi Lakade

            Hello, Deepak Nair and Patrik Stanz

            Thank you for your inputs. I update the docs to include the additional header so that the APIs work. 

            Thanks, 

            Aaditi

            Mar 01, 2024 07:30