Introduction

The Case Management APIs provides a RESTful public interface to interact with support cases. By using this API, you can create cases, get case statuses, add comments to a case, add and remove users from a case watchlist, download and add attachments, and more.

Authentication and authorization

Authentication and authorization to the Case Management REST API are enforced by using an IAM access token. The token is used to determine the access roles that the identity has access to when using the user management account management service. For information about how to obtain an IAM token for an authenticated user or service ID, see the IAM Identity Service API documentation.

Use of the IAM Policy Management REST API is done by adding a valid IAM token to the HTTP Authorization request header. Example: -H 'Authorization: Bearer $TOKEN'

To retrieve your access token:

curl -X POST \
'https://iam.cloud.ibm.com/identity/token' \
-H 'Authorization: TOKEN' \
-H 'Content-Type: application/x-www-form-urlencoded'
-d 'grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=MY_APIKEY'

Case Scope

All cases are in the scope of the account specified in the IAM token. Make sure that you have the IAM token that has account information. If you generate the IAM token through some API, you might forget adding the account information.

Error Handling

The Case Management APIs return standard HTTP status codes to indicate the success or failure of a request. The format of the response is represented in JSON.

If an operation can't be fulfilled, an appropriate 400 or 500 series HTTP response is returned from the server. The operations defined in the Reference section describe example errors that can be returned from a failed request. All responses from the IAM Policy Management API are in the JSON format.

Here are potential error codes that the API can return.

HTTP Error Code Description Recovery
200 Success The request was successful.
201 Created The resource was successfully created.
204 No Content The request was successful. No response body is provided.
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request. The token is either invalid, missing or expired. Get a new valid token and try again.
403 Forbidden The token is valid, but the subject of the token is not authorized to perform the operation. If this error persists, contact the account owner to check your permissions.
404 Not Found The requested resource could not be found.
409 Conflict The entity is already in the requested state.
415 Unsupported Media Type Request body sent was formatted using an unsupported media type.
429 Too Many Requests Too many requests have been made within a given time window. Wait before calling the API again.
500 Service Unavailable IAM Policy Management Point is currently unavailable. Your request could not be processed. Wait a few minutes and try again.
{
    "trace": "cd4f7573121a4cf99f0079f8482b3d6b",
    "errors": [
        {
            "code": "invalid_token",
            "message": "The provided IAM token is invalid."
        }
    ],
    "status_code": 401
}

Methods

Get cases in account

Get cases in the account which is specified by the content of the IAM token.

GET /case-management/v1/cases
Request

Custom Headers

  • The OAuth token obtained from the IBM Cloud Identity and Access Management (IAM) through a grant of type 'passcode', or 'apikey', or 'authorization_code'. For access to certain IBM Cloud resources, the OAuth token obtained using a IAM 'authorization_code' needs to be account-scoped, i.e. include the BSS/IMS account id, when obtaining the token through the call to the 'console-platform-express-session' module (as described in the module documentation)

Query Parameters

  • Number of cases should be skipped

    Default: 0

  • Number of cases should be returned

    Default: 10

  • String that a case might contain

  • Sort field and direction. If omitted, default to descending of updated date. Prefix "~" signifies sort in descending.

    Allowable values: [number,short_description,severity,updated_at,created_at,~number,~short_description,~severity,~updated_at,~created_at]

  • Case status filter

    Allowable values: [new,in_progress,waiting_on_client,resolution_provided,resolved,closed]

    Constraints: collection format: csv

  • Seleted fields of interest instead of the entire case information

    Allowable values: [number,short_description,description,created_at,created_by,updated_at,updated_by,contact,contact_type,status,severity,support_tier,resolution,close_notes,invoice_number,eu,watchlist,attachments,resources,comments,offering]

    Constraints: number of items ≥ 1, contains only unique items, collection format: csv

Response

Status Code

  • Success

  • Unauthorized - unable to determine a valid authorization header. The Authorization header was not populated, the value is not a well-formed JWT token, or it is expired, etc.

  • Forbidden - insufficient permission. The client has been authenticated successfully, but the permissions set for the operation forbid this operation to the specified user.

Example responses

Create a case

Create a case in the account.

POST /case-management/v1/cases
Request

Custom Headers

  • The OAuth token obtained from the IBM Cloud Identity and Access Management (IAM) through a grant of type 'passcode', or 'apikey', or 'authorization_code'. For access to certain IBM Cloud resources, the OAuth token obtained using a IAM 'authorization_code' needs to be account-scoped, i.e. include the BSS/IMS account id, when obtaining the token through the call to the 'console-platform-express-session' module (as described in the module documentation)

The case to create

Response

Status Code

  • Success

  • Unauthorized - unable to determine a valid authorization header. The Authorization header was not populated, the value is not a well-formed JWT token, or it is expired, etc.

  • Forbidden - insufficient permission. The client has been authenticated successfully, but the permissions set for the operation forbid this operation to the specified user.

Example responses

Get a case in account

Get a case in the account that is specified by the case number.

GET /case-management/v1/cases/{case_number}
Request

Custom Headers

  • The OAuth token obtained from the IBM Cloud Identity and Access Management (IAM) through a grant of type 'passcode', or 'apikey', or 'authorization_code'. For access to certain IBM Cloud resources, the OAuth token obtained using a IAM 'authorization_code' needs to be account-scoped, i.e. include the BSS/IMS account id, when obtaining the token through the call to the 'console-platform-express-session' module (as described in the module documentation)

Path Parameters

  • Unique identifier of a case

Query Parameters

  • Selected fields of interest instead of the entire case information

    Constraints: collection format: csv

Response

Status Code

  • Success

  • Unauthorized - unable to determine a valid authorization header. The Authorization header was not populated, the value is not a well-formed JWT token, or it is expired, etc.

  • Forbidden - insufficient permission. The client has been authenticated successfully, but the permissions set for the operation forbid this operation to the specified user.

  • Not Found - The requested resource does not exist.

Example responses

Update case status

Mark the case as resolved or unresolved, or accept the provided resolution.

PUT /case-management/v1/cases/{case_number}/status
Request

Custom Headers

  • The OAuth token obtained from the IBM Cloud Identity and Access Management (IAM) through a grant of type 'passcode', or 'apikey', or 'authorization_code'. For access to certain IBM Cloud resources, the OAuth token obtained using a IAM 'authorization_code' needs to be account-scoped, i.e. include the BSS/IMS account id, when obtaining the token through the call to the 'console-platform-express-session' module (as described in the module documentation)

Path Parameters

  • Unique identifier of a case

the update payload

Response

Status Code

  • Success

  • Unauthorized - unable to determine a valid authorization header. The Authorization header was not populated, the value is not a well-formed JWT token, or it is expired, etc.

  • Forbidden - insufficient permission. The client has been authenticated successfully, but the permissions set for the operation forbid this operation to the specified user.

  • Not Found - The requested resource does not exist.

  • Conflict - The requested resource is being modified in a different request

Example responses

Add comment to case

Add a comment to a case.

PUT /case-management/v1/cases/{case_number}/comments
Request

Custom Headers

  • The OAuth token obtained from the IBM Cloud Identity and Access Management (IAM) through a grant of type 'passcode', or 'apikey', or 'authorization_code'. For access to certain IBM Cloud resources, the OAuth token obtained using a IAM 'authorization_code' needs to be account-scoped, i.e. include the BSS/IMS account id, when obtaining the token through the call to the 'console-platform-express-session' module (as described in the module documentation)

Path Parameters

  • Unique identifier of a case

Response

Status Code

  • Success

  • Unauthorized - unable to determine a valid authorization header. The Authorization header was not populated, the value is not a well-formed JWT token, or it is expired, etc.

  • Forbidden - insufficient permission. The client has been authenticated successfully, but the permissions set for the operation forbid this operation to the specified user.

  • Not Found - The requested resource does not exist.

Example responses

Add users to watchlist of case

Add users to the watchlist of case. By adding a user to the watchlist of the case, you are granting them read and write permissions, so the user can view the case, receive updates, and make updates to the case. Note that the user must be in the account to be added to the watchlist.

PUT /case-management/v1/cases/{case_number}/watchlist
Request

Custom Headers

  • The OAuth token obtained from the IBM Cloud Identity and Access Management (IAM) through a grant of type 'passcode', or 'apikey', or 'authorization_code'. For access to certain IBM Cloud resources, the OAuth token obtained using a IAM 'authorization_code' needs to be account-scoped, i.e. include the BSS/IMS account id, when obtaining the token through the call to the 'console-platform-express-session' module (as described in the module documentation)

Path Parameters

  • Unique identifier of a case

Response

Status Code

  • Success

  • Unauthorized - unable to determine a valid authorization header. The Authorization header was not populated, the value is not a well-formed JWT token, or it is expired, etc.

  • Forbidden - insufficient permission. The client has been authenticated successfully, but the permissions set for the operation forbid this operation to the specified user.

  • Not Found - The requested resource does not exist.

Example responses

Remove users from watchlist of case

Remove users from the watchlist of a case.

DELETE /case-management/v1/cases/{case_number}/watchlist
Request

Custom Headers

  • The OAuth token obtained from the IBM Cloud Identity and Access Management (IAM) through a grant of type 'passcode', or 'apikey', or 'authorization_code'. For access to certain IBM Cloud resources, the OAuth token obtained using a IAM 'authorization_code' needs to be account-scoped, i.e. include the BSS/IMS account id, when obtaining the token through the call to the 'console-platform-express-session' module (as described in the module documentation)

Path Parameters

  • Unique identifier of a case

Response

User IDs in the watchlist

Status Code

  • Success

  • Unauthorized - unable to determine a valid authorization header. The Authorization header was not populated, the value is not a well-formed JWT token, or it is expired, etc.

  • Forbidden - insufficient permission. The client has been authenticated successfully, but the permissions set for the operation forbid this operation to the specified user.

  • Not Found - The requested resource does not exist.

Example responses

Add a resource to case

Add a resource to case by specifying the Cloud Resource Name (CRN), or id and type if attaching a class iaaS resource.

PUT /case-management/v1/cases/{case_number}/resources
Request

Custom Headers

  • The OAuth token obtained from the IBM Cloud Identity and Access Management (IAM) through a grant of type 'passcode', or 'apikey', or 'authorization_code'. For access to certain IBM Cloud resources, the OAuth token obtained using a IAM 'authorization_code' needs to be account-scoped, i.e. include the BSS/IMS account id, when obtaining the token through the call to the 'console-platform-express-session' module (as described in the module documentation)

Path Parameters

  • Unique identifier of a case

Response

Status Code

  • Success

  • Unauthorized - unable to determine a valid authorization header. The Authorization header was not populated, the value is not a well-formed JWT token, or it is expired, etc.

  • Forbidden - insufficient permission. The client has been authenticated successfully, but the permissions set for the operation forbid this operation to the specified user.

  • Not Found - The requested resource does not exist.

Example responses

Add attachment(s) to case

You can add attachments to a case to provide more information for the support team about the issue that you're experiencing.

PUT /case-management/v1/cases/{case_number}/attachments
Request

Custom Headers

  • The OAuth token obtained from the IBM Cloud Identity and Access Management (IAM) through a grant of type 'passcode', or 'apikey', or 'authorization_code'. For access to certain IBM Cloud resources, the OAuth token obtained using a IAM 'authorization_code' needs to be account-scoped, i.e. include the BSS/IMS account id, when obtaining the token through the call to the 'console-platform-express-session' module (as described in the module documentation)

  • Allowable values: [multipart/form-data,application/octet-stream]

Path Parameters

  • Unique identifier of a case

Form Parameters

  • file of supported types, 8MB in size limit

Response

Details of an attachment

Status Code

  • Success

  • Unauthorized - unable to determine a valid authorization header. The Authorization header was not populated, the value is not a well-formed JWT token, or it is expired, etc.

  • Forbidden - insufficient permission. The client has been authenticated successfully, but the permissions set for the operation forbid this operation to the specified user.

  • Not Found - The requested resource does not exist.

Example responses

Download an attachment

Download an attachment from a case.

GET /case-management/v1/cases/{case_number}/attachments/{file_id}
Request

Custom Headers

  • The OAuth token obtained from the IBM Cloud Identity and Access Management (IAM) through a grant of type 'passcode', or 'apikey', or 'authorization_code'. For access to certain IBM Cloud resources, the OAuth token obtained using a IAM 'authorization_code' needs to be account-scoped, i.e. include the BSS/IMS account id, when obtaining the token through the call to the 'console-platform-express-session' module (as described in the module documentation)

Path Parameters

  • Unique identifier of a case

  • Unique identifier of a file

Response

Status Code

  • Success

  • Unauthorized - unable to determine a valid authorization header. The Authorization header was not populated, the value is not a well-formed JWT token, or it is expired, etc.

  • Forbidden - insufficient permission. The client has been authenticated successfully, but the permissions set for the operation forbid this operation to the specified user.

  • Not Found - The requested resource does not exist.

Example responses

Remove attachment from case

Remove an attachment from a case.

DELETE /case-management/v1/cases/{case_number}/attachments/{file_id}
Request

Custom Headers

  • The OAuth token obtained from the IBM Cloud Identity and Access Management (IAM) through a grant of type 'passcode', or 'apikey', or 'authorization_code'. For access to certain IBM Cloud resources, the OAuth token obtained using a IAM 'authorization_code' needs to be account-scoped, i.e. include the BSS/IMS account id, when obtaining the token through the call to the 'console-platform-express-session' module (as described in the module documentation)

Path Parameters

  • Unique identifier of a case

  • Unique identifier of a file

Response

Status Code

  • Success

  • Unauthorized - unable to determine a valid authorization header. The Authorization header was not populated, the value is not a well-formed JWT token, or it is expired, etc.

  • Forbidden - insufficient permission. The client has been authenticated successfully, but the permissions set for the operation forbid this operation to the specified user.

  • Not Found - The requested resource does not exist.

Example responses

Shows how to mark case as EU supported

Shows how an account can mark a case as EU supported.

GET /case-management/utilities/v1/eu-support
Request

Custom Headers

  • The OAuth token obtained from the IBM Cloud Identity and Access Management (IAM) through a grant of type 'passcode', or 'apikey', or 'authorization_code'. For access to certain IBM Cloud resources, the OAuth token obtained using a IAM 'authorization_code' needs to be account-scoped, i.e. include the BSS/IMS account id, when obtaining the token through the call to the 'console-platform-express-session' module (as described in the module documentation)

Response

Status Code

  • Success

  • Unauthorized - unable to determine a valid authorization header. The Authorization header was not populated, the value is not a well-formed JWT token, or it is expired, etc.

  • Forbidden - insufficient permission. The client has been authenticated successfully, but the permissions set for the operation forbid this operation to the specified user.

No Sample Response

This method does not specify any sample responses.

Get offerings

Get offerings used in technical cases.

GET /case-management/utilities/v1/offerings/technical
Request

Custom Headers

  • The OAuth token obtained from the IBM Cloud Identity and Access Management (IAM) through a grant of type 'passcode', or 'apikey', or 'authorization_code'. For access to certain IBM Cloud resources, the OAuth token obtained using a IAM 'authorization_code' needs to be account-scoped, i.e. include the BSS/IMS account id, when obtaining the token through the call to the 'console-platform-express-session' module (as described in the module documentation)

Response

Status Code

  • Success

  • Unauthorized - unable to determine a valid authorization header. The Authorization header was not populated, the value is not a well-formed JWT token, or it is expired, etc.

  • Forbidden - insufficient permission. The client has been authenticated successfully, but the permissions set for the operation forbid this operation to the specified user.

No Sample Response

This method does not specify any sample responses.

Get resolution code values

Get the resolution code values used in "Update Status API"

GET /case-management/utilities/v1/constants/resolution-codes
Request

Custom Headers

  • The OAuth token obtained from the IBM Cloud Identity and Access Management (IAM) through a grant of type 'passcode', or 'apikey', or 'authorization_code'. For access to certain IBM Cloud resources, the OAuth token obtained using a IAM 'authorization_code' needs to be account-scoped, i.e. include the BSS/IMS account id, when obtaining the token through the call to the 'console-platform-express-session' module (as described in the module documentation)

Response

Status Code

  • Success

  • Unauthorized - unable to determine a valid authorization header. The Authorization header was not populated, the value is not a well-formed JWT token, or it is expired, etc.

  • Forbidden - insufficient permission. The client has been authenticated successfully, but the permissions set for the operation forbid this operation to the specified user.

No Sample Response

This method does not specify any sample responses.

Get status values

Get the status values used in case filtering

GET /case-management/utilities/v1/constants/statuses
Request

Custom Headers

  • The OAuth token obtained from the IBM Cloud Identity and Access Management (IAM) through a grant of type 'passcode', or 'apikey', or 'authorization_code'. For access to certain IBM Cloud resources, the OAuth token obtained using a IAM 'authorization_code' needs to be account-scoped, i.e. include the BSS/IMS account id, when obtaining the token through the call to the 'console-platform-express-session' module (as described in the module documentation)

Response

Status Code

  • Success

  • Unauthorized - unable to determine a valid authorization header. The Authorization header was not populated, the value is not a well-formed JWT token, or it is expired, etc.

  • Forbidden - insufficient permission. The client has been authenticated successfully, but the permissions set for the operation forbid this operation to the specified user.

No Sample Response

This method does not specify any sample responses.