Free cookie consent management tool by TermsFeed

Set Up Case API Library Module

On This Page

Before you begin

After installing the Case API Library module, you need to set it up before external systems can call the API endpoints. To set up the Case API Library module, complete the following steps:

After completing setup, see the endpoint reference for detailed request and response information for each API endpoint.

Step 1: Create a service account

The Case API Library requires a service account to process API requests. The service account acts as the identity for all operations performed through the API, including case creation, updates, and data retrieval.

To create a service account:

  1. Sign in to the target environment.
  2. Navigate to the Admin Console.
  3. Select Users and click CREATE.
  4. In the Username field, enter a username for the service account (for example, caseApiServiceAccount).
  5. In the Groups field, add the service account to the following groups:
    • CMGT Service Accounts
    • CMGT Case Workers
  6. Click CREATE.

Note:  The service account username is recorded as the createdBy value for cases created through the API. Use a descriptive username that makes it clear the case originated from an external system.

Step 2: Configure authentication

The Case API Library ships without a preconfigured authentication method. You must configure authentication before external systems can call the API endpoints. Choose one of the following options based on your security requirements.

Option A: API Key authentication

API Key authentication is straightforward to set up and suitable for trusted system-to-system communication.

To configure API Key authentication:

  1. Sign in to the target environment.
  2. Navigate to the Admin Console and select Web API Authentication.
  3. From the API Key tab, click CREATE.
  4. In the Description field, enter a unique description for the API key (for example, Case API Library - External System).
  5. In the Service Account field, select the service account created in step 1.
  6. Click CREATE.
  7. Copy the generated API key and store it securely. You will provide this key to the external system that calls the API endpoints.

External systems pass the API key in the Appian-API-Key request header with each API call.

For more information about API Key authentication, see Web API Authentication.

Option B: OAuth 2.0 Client Credentials Grant

OAuth 2.0 Client Credentials Grant is the industry-standard protocol for machine-to-machine communication. It is more secure than API keys because it supports token expiration and refresh.

To configure OAuth 2.0:

  1. Sign in to the target environment.
  2. Navigate to the Admin Console and select Web API Authentication.
  3. From the OAuth 2.0 tab, click CREATE.
  4. In the Description field, enter a unique description (for example, Case API Library - OAuth Client).
  5. In the Service Account field, select the service account created in step 1.
  6. Configure the Token Expiration and Refresh Token settings based on your security requirements.
  7. Click CREATE.
  8. Copy the generated Client ID and Client Secret and store them securely. The external system uses these credentials to obtain an access token.

External systems first request an access token using the Client ID and Client Secret, then pass the token in the Authorization: Bearer <token> request header with each API call.

For more information about OAuth 2.0 configuration, see Web API Authentication.

Step 3: Clone and customize templates

The Case API Library ships Web API templates that are designed to be cloned and customized. Cloning preserves the original templates so you can receive future upgrades and merge in new templates as they are released.

To clone and customize a template:

  1. In Appian Designer, navigate to the CMGT Add-On - Case API Library application.
  2. Search for the Web API object you want to customize (for example, CMGT_API_CreateCase).
  3. Right-click the object and select Duplicate.
  4. Rename the duplicated object to reflect your integration (for example, MyOrg_API_CreateCase).
  5. Move the duplicated object to your own application.
  6. Customize the duplicated object to match your integration requirements, such as:
    • Adding or removing fields from the request or response body.
    • Adding custom validation logic.
    • Filtering response data to return only the fields your external system needs.

Tip:  Keep the original templates in the CMGT Add-On - Case API Library application intact. When future versions of the module are released, you can import the update and compare the new templates against your customized versions to adopt improvements.

Endpoint reference

This section provides detailed request and response information for each API endpoint in the Case API Library.

Create a case

Creates a new case record and initiates the configured workflow for the specified case type.

  • Method: POST
  • Endpoint: /cmgt-cases

Request body:

Parameter Type Required Description
caseTypeUuid Text Yes The UUID of the case type to create.
title Text Yes The title of the case.
description Text No A description of the case.
customFields Nested Json No A nested json of custom field values configured for the case type in the Control Panel. Use the Retrieve case fields endpoint to determine field names and types.

Custom fields structure

Custom fields are organized into three levels:

  • Global (all cases) fields: Pass them directly at the root level of the request body alongside title, description, and other core fields.
  • Category-level fields: Use the category's dataKeyName (for example, "benefitsEnrollment": { ... }).
  • Case type-level fields: Use the case type's dataKeyName (for example, "employeeOnboarding": { ... }).

Response body:

Field Type Description
caseId Integer The system-generated case ID.
caseFriendlyId Text The formatted case identifier (for example, CASE-EQ-2026-001).

Example request:

The following request creates a new case with global, category-level, and case type-level custom fields:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

  "description": "New hire onboarding case for the engineering department starting June 2026.",

  /* Global (All Cases) level fields - passed directly at root level */
  "urgencyLevel": 1,

  /* Case Category level fields - use category dataKeyName as the nested object key */
  "benefitsEnrollment": {
    "detailedNotes": "Employee opted for premium health plan with dental and vision coverage.",
    "quantity": 3
  },

  /* Case Type level fields - use case type dataKeyName as the nested object key */
  "employeeOnboarding": {
    "shortDescription": "Onboarding for senior developer role",
    "detailedNotes": "Requires laptop provisioning, badge access, and team orientation scheduling.",
    "isActive": "True",
    "dueDate": "2026-06-15",
    "createdAt": "2026-05-12T10:00:00Z",
    "itemCount": 5,
    "amount": 1500.00,
    "priority": 1
  }
}

Example response:

1
2
3
4

{
  "caseId": 1953,
  "caseFriendlyId": "STW-87V2JTEBA6"
}

Update a case

Updates a specific case record with the supplied data.

  • Method: PUT
  • Endpoint: /cmgt-cases

Request parameters:

Parameter Type Required Description
caseId Integer Yes The ID of the case to retrieve.

Request body:

Parameter Type Required Description
title Text Conditional If included, cannot be null.
Other case fields Use CMGT_API_GET_CaseFields API for types No If not included, the field is unchanged. If included, the field is updated even if the value is null.
customFields Nested Json No A nested json of custom field values configured for the case type in the Control Panel. Use the Retrieve case fields endpoint to determine field names and types.

Other case fields can also be included in the request body. If a field is not included, it remains unchanged. If included, the field is updated even if the value is null. Use the Retrieve case fields API to determine field names and types.

Response body:

Field Type Description
caseId Integer The ID of the updated case.

Example 1: Update case fields and global custom field:

Updates only a global (all cases) level custom field.

PUT /cases?caseId=1

1
2
3
4
5

{
  "title": "Employee Onboarding - New Hire Request Updated",
  "description": "New hire onboarding case for the engineering department starting June 2026 Updated.",
  "urgencyLevel": 3
}

Example 2: Update category fields only:

Updates only the category-level custom fields without modifying core case fields or case type fields.

PUT /cases?caseId=1

1
2
3
4
5
6

{
  "benefitsEnrollment": {
    "detailedNotes": "Updated coverage to include dependent spouse under family plan.",
    "quantity": 5
  }
}

Example 3: Update case type fields only:

Updates only the case type-level custom fields without modifying core case fields or category fields.

PUT /cases?caseId=1

1
2
3
4
5
6
7
8
9
10
11
12

{
  /* Case Type level fields - use case type dataKeyName as the nested object key */
  "employeeOnboarding": {
    "shortDescription": "Onboarding updated for lateral transfer",
    "detailedNotes": "Badge access revised — no new laptop needed, reuse existing equipment.",
    "isActive": "False",
    "dueDate": "2026-07-01",
    "itemCount": 3,
    "amount": 800.00,
    "priority": 2
  }
}

Example 4: Update all levels:

Updates fields across all three levels (global, category, and case type) in a single request.

PUT /cases?caseId=1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
  /* Global (All Cases) level field - passed directly at root level */
  "urgencyLevel": 2,

  /* Case Category level fields - use category dataKeyName as the nested object key */
  "benefitsEnrollment": {
    "detailedNotes": "Updated coverage to include dependent spouse under family plan.",
    "quantity": 5
  },

  /* Case Type level fields - use case type dataKeyName as the nested object key */
  "employeeOnboarding": {
    "shortDescription": "Onboarding updated for lateral transfer",
    "detailedNotes": "Badge access revised — no new laptop needed, reuse existing equipment.",
    "isActive": "False",
    "dueDate": "2026-07-01",
    "itemCount": 3,
    "amount": 800.00,
    "priority": 2
  }
}

Example response:

1
2
3

{
  "caseId": [1]
}

Retrieve a specific case

Retrieves all details and related data for a single case.

  • Method: GET
  • Endpoint: /cmgt-case

Request parameters:

Parameter Type Required Description
caseId Integer Yes The ID of the case to retrieve.
includeComments Boolean No Include case comments in the response. Default: false.
includeMilestones Boolean No Include case milestones in the response. Default: false.
includeRoles Boolean No Include case roles in the response. Default: false.
includeTags Boolean No Include case tags in the response. Default: false.
includeRelatedEntities Boolean No Include related entities in the response. Default: false.
includeRelatedCases Boolean No Include related cases in the response. Default: false.

Response body:

The response includes the case record fields (due date, status, priority, title, description, created by, created on, modified by, modified on) and any requested related data.

Example request:

GET /cmgt-case?caseId=1&includeMilestones=true&includeRelatedCases=true&includeTags=true&includeRoles=true&includeRelatedEntities=true

Example response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

{
  "message": null,
  "data": [{
    "caseId": 1,
    "caseTypeUuid": "d5168ee5-28d1-42e7-b90f-c8877abc91f1",
    "friendlyId": "ECT-J50CIS1AFBD",
    "title": "testing task meta data for triggers",
    "description": "",
    "dueOn": null,
    "statusLabel": "Open",
    "priorityName": "None",
    "caseTypeName": "Case Type",
    "createdBy": "Jone Evan",
    "createdOn": "2025-11-05T17:01:45Z",
    "modifiedBy": "Jone Evan",
    "modifiedOn": "2025-11-05T17:04:43Z",
    "milestones": [],
    "roles": [{
      "roleTypeLabel": "Submitter",
      "groupAssignee": null,
      "userAssignee": "Jone Evan"
    }],
    "tags": [],
    "relatedCases": [],
    "relatedEntities": [],
    "datetime": null,
    "customerName": "",
    "policyEffectiveDate": null,
    "policyExpirationDate": null,
    "rushStatus": null,
    "primaryexcessStatus": null,
    "brokerName": "",
    "brokerOfficeName": "",
    "brokerEmail": "",
    "brokerPhoneNumber": "",
    "customerContactName": "",
    "customerContactEmail": "",
    "totalInsuredValue": null,
    "category": {
      "catShortText": null,
      "catLongText": null
    }
  }],
  "totalCount": 1
}

Retrieve a list of cases

Retrieves a filtered list of cases based on the supplied criteria.

  • Method: GET
  • Endpoint: /cases

Request parameters:

Parameter Type Required Description
startIndex Integer No The starting index for pagination. Default: 1.
batchSize Integer No The number of cases to return. Default: 1000.
sortBy Text No The sort order. Default: "createdOnDescending". Valid values: "createdOnDescending", "createdOnAscending".
caseIds List of Integer No Filter by specific case IDs.
userAssignee Text No Filter by assigned user.
statusId Integer No Filter by status ID.
caseTypeUuid Text No Filter by case type UUID.

Response body:

Retrieves a paginated list of cases based on the provided filter criteria. This API allows consumers to search and narrow down cases by attributes such as case type, status, priority and assigned users.

Example request:

GET /cmgt-cases?startIndex=1&batchSize=10&caseIds=1,229&statusId=1&userAssignee=john.smith&sortBy=createdOnAscending

Example response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

{
  "message" : null,
  "data" : [ {
    "caseId" : 1,
    "caseTypeUuid" : null,
    "friendlyId" : "ECT-X024XY192D5",
    "title" : "testing task flag for an automation loop",
    "description" : "",
    "dueOn" : null,
    "statusLabel" : "Open",
    "priorityName" : "None",
    "caseTypeName" : "Case Type",
    "createdBy" : "John Smith",
    "createdOn" : "2025-10-31T13:02:46Z",
    "modifiedBy" : "John Smith",
    "modifiedOn" : "2025-10-31T16:29:31Z",
    "roles" : [ {
      "roleTypeLabel" : "Assignee",
      "groupAssignee" : null,
      "userAssignee" : "John Smith"
    } ]
  } ],
  "totalCount" : 1
}

Retrieve case comments

Retrieves the comment history for a specific case, including case comments and task comments.

  • Method: GET
  • Endpoint: /cmgt-casecomments

Request parameters:

Parameter Type Required Description
caseId Integer Yes The ID of the case.
startIndex Integer No The starting index for pagination. Default: 1.
batchSize Integer No The number of comments to return. Default: 100. Maximum: 1000.

Response body:

A list of comments in descending order, with child comments nested appropriately. Each comment includes associated tags and document references (document IDs and names, not the files themselves).

Example request:

GET /cmgt-casecomments?caseId=1&startIndex=1&batchSize=100

Example response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "commentId": 1,
  "childComments": [],
  "caseId": 1,
  "taskId": null,
  "parentCommentId": null,
  "commentText": "Test comments",
  "isBookmarked": false,
  "isPrivate": true,
  "hasBeenEdited": false,
  "isActive": true,
  "createdBy": "James Evan",
  "createdOn": "2026-06-05T10:40:42Z",
  "modifiedBy": "James Evan",
  "modifiedOn": "2026-06-05T10:40:42Z"
}

Retrieve case tasks

Retrieves all tasks attributed to a specific case.

  • Method: GET
  • Endpoint: /cmgt-casetasks

Request parameters:

Parameter Type Required Description
caseId Integer Yes The ID of the case.
startIndex Integer No The starting index for pagination. Default: 1.
batchSize Integer No The number of tasks to return. Default: 100. Maximum: 1000.
milestoneId List of Integer No Filter by milestone IDs.
taskStatusIds List of Integer No Filter by task status IDs.

Response body:

A list of case tasks. Task dependency relationships are not included in the response.

Example request:

GET /cmgt-casetasks?caseId=1&taskStatusIds=5,6,7&milestoneIds=1

Example response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

[
  {
    "taskId" :1,
    "roles" : [ ],
    "milestone" : null,
    "status" : {
      "statusId" : 7,
      "statusLabel" : "Queued"
    },
    "caseId" : 1,
    "taskUuid" : "93c43da2-9b0f-443f-804a-9a45aa101ee2",
    "milestoneId" : null,
    "taskBehaviorTypeId" : null,
    "taskBehaviorTypeLabel" : null,
    "title" : "Task 1",
    "questionLabel" : "",
    "description" : "",
    "statusId" : 7,
    "availableOn" : null,
    "dueOn" : null,
    "startsByDefault" : null,
    "slaDays" : null,
    "selectedTaskResponseOption" : null,
    "completedBy" : "",
    "completedOn" : null,
    "createdBy" : "John Smith",
    "createdOn" : "2026-06-04T08:49:48Z",
    "modifiedBy" : "John Smith",
    "modifiedOn" : "2026-06-05T02:02:33Z",
    "isActive" : true,
    "isAdhoc" : false,
    "isCompleted" : false,
    "dueOnSortOrder" : 4
  }, {
    "taskId" :2,
    "roles" : [ ],
    "milestone" : null,
    "status" : {
      "statusId" : 7,
      "statusLabel" : "Queued"
    },
    "caseId" :1,
    "taskUuid" : "eb1a31e3-1d03-4818-89ea-786c01e00e26",
    "milestoneId" : null,
    "taskBehaviorTypeId" : null,
    "taskBehaviorTypeLabel" : null,
    "title" : "Task 2",
    "questionLabel" : "",
    "description" : "",
    "statusId" : 7,
    "availableOn" : null,
    "dueOn" : null,
    "startsByDefault" : null,
    "slaDays" : null,
    "selectedTaskResponseOption" : null,
    "completedBy" : "",
    "completedOn" : null,
    "createdBy" : "John Smith",
    "createdOn" : "2026-06-04T08:49:32Z",
    "modifiedBy" : "John Smith",
    "modifiedOn" : "2026-06-04T08:49:32Z",
    "isActive" : true,
    "isAdhoc" : false,
    "isCompleted" : false,
    "dueOnSortOrder" : 4
  }
]

Retrieve all case types

Retrieves all active case types configured in the Control Panel.

  • Method: GET
  • Endpoint: /cmgt-caseType

Response body:

Fetches all case types marked as active from the Control Panel settings.

Field Type Description
caseTypeUuid Text The case type UUID.
caseTypeName Text The case type display name.
categoryUuid Text The case category UUID.
categoryName Text The case category display name.

Example request:

GET /cmgt-caseType

Example response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

[ {
    "caseTypeUuid" : "0611794b-381f-41e8-bd41-e13bd0dd7f01",
    "caseTypeName" : "Generic Commercial Property",
    "categoryUuid" : "c2e6b978-4794-4939-881d-3ce69b62b8bc",
    "categoryName" : "Commercial Property"
  },

   {
    "caseTypeUuid" : "26c8036b-f6bf-4831-8d2f-3f5337476b95",
    "caseTypeName" : "Case type with many create case task",
    "categoryUuid" : "ecbdb633-0f32-4613-a35b-31e3fa5cf00a",
    "categoryName" : "Category"
  }
]

Retrieve all statuses

Retrieves all active case statuses or task statuses in ID order.

  • Method: GET
  • Endpoint: /cmgt-status

Request parameters:

Parameter Type Required Description
type Text No The status type to retrieve. Accepted values: "CASE", "TASK".

Response body:

Field Type Description
statusId Integer The status ID.
type Text The status type (CASE or TASK).
statusLabel Text The status display name.

Example request:

GET /cmgt-status?type=CASE

Example response:

1
2
3
4
5

[
  {"statusId": 1, "type": "CASE", "statusLabel": "Open"},
  {"statusId": 2, "type": "CASE", "statusLabel": "In Progress"},
  {"statusId": 3, "type": "CASE", "statusLabel": "Closed"}
]

Retrieve all case priorities

Retrieves all active case priorities in ID order.

  • Method: GET
  • Endpoint: /cmgt-casePriority

Response body:

Field Type Description
priorityId Integer The priority ID.
priorityName Text The priority display name.

Example request:

GET /cmgt-casePriority

Example response:

1
2
3
4
5
6
7

[
  {"priorityId": 1, "priorityName": "Critical"},
  {"priorityId": 2, "priorityName": "High"},
  {"priorityId": 3, "priorityName": "Medium"},
  {"priorityId": 4, "priorityName": "Low"},
  {"priorityId": 5, "priorityName": "None"}
]

Retrieve case fields by case type

Retrieves the custom fields configured for a specific case type in the Control Panel.

  • Method: GET
  • Endpoint: /cmgt-caseFields

Request parameters:

Parameter Type Required Description
caseTypeUuid Text Yes 1. Pass null to return only the global case fields.
2. Pass a category UUID to return the global and category-level fields.
3. Pass a case type UUID to return the global, category-level, and case type-level fields.

Response body:

A hierarchical list of custom field definitions. Each entry contains a hierarchyKey (the dataKeyName used in API requests), a hierarchyName (the display name), and a fields array. Each field includes fieldKey, fieldName, fieldType, and choiceList (if applicable).

Example 1: Passing a case type UUID:

Returns global fields, category-level fields, and case type-level fields for the specified case type.

GET /cmgt-caseFields?caseTypeUuid=0611794b-381f-41e8-bd41-e13bd0dd7f01

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

[
  {
    "hierarchyKey": "genericCommercialProperty",
    "hierarchyName": "Generic Commercial Property",
    "fields": [
      {
        "fieldKey": "securitySystem",
        "fieldName": "Security System",
        "fieldType": "Short Text",
        "choiceList": null
      },
      {
        "fieldKey": "garage",
        "fieldName": "Garage",
        "fieldType": "Short Text",
        "choiceList": null
      }
    ]
  },
  {
    "hierarchyKey": "commercialProperty",
    "hierarchyName": "Commercial Property",
    "fields": [
      {
        "fieldKey": "categoryLevelTestField",
        "fieldName": "Category Level Test Field",
        "fieldType": "Number (Integer)",
        "choiceList": null
      },
      {
        "fieldKey": "priorCoverageId",
        "fieldName": "Prior Coverage",
        "fieldType": "Choice List",
        "choiceList": [
          {"choiceId": 1, "choiceName": "Yes"},
          {"choiceId": 2, "choiceName": "No"}
        ]
      }
    ]
  },
  {
    "hierarchyKey": "case",
    "hierarchyName": "Case",
    "fields": [
      {
        "fieldKey": "title",
        "fieldName": "Title",
        "fieldType": "Short Text",
        "choiceList": null
      },
      {
        "fieldKey": "rushStatus",
        "fieldName": "Rush Status",
        "fieldType": "Boolean",
        "choiceList": null
      }
    ]
  }
]

Example 2: Passing a category UUID:

Returns global fields and category-level fields without case type-specific fields.

GET /cmgt-caseFields?caseTypeUuid=c2e6b978-4794-4939-881d-3ce69b62b8bc

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

[
  {
    "hierarchyKey": "commercialProperty",
    "hierarchyName": "Commercial Property",
    "fields": [
      {
        "fieldKey": "categoryLevelTestField",
        "fieldName": "Category Level Test Field",
        "fieldType": "Number (Integer)",
        "choiceList": null
      },
      {
        "fieldKey": "priorCoverageId",
        "fieldName": "Prior Coverage",
        "fieldType": "Choice List",
        "choiceList": [
          {"choiceId": 1, "choiceName": "Yes"},
          {"choiceId": 2, "choiceName": "No"}
        ]
      }
    ]
  },
  {
    "hierarchyKey": "case",
    "hierarchyName": "Case",
    "fields": [
      {
        "fieldKey": "title",
        "fieldName": "Title",
        "fieldType": "Short Text",
        "choiceList": null
      },
      {
        "fieldKey": "rushStatus",
        "fieldName": "Rush Status",
        "fieldType": "Boolean",
        "choiceList": null
      }
    ]
  }
]

Example 3: Passing null (global fields only):

Returns only the global fields that apply to all case types.

GET /cmgt-caseFields?caseTypeUuid=

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

[
  {
    "hierarchyKey": "case",
    "hierarchyName": "Case",
    "fields": [
      {
        "fieldKey": "title",
        "fieldName": "Title",
        "fieldType": "Short Text",
        "choiceList": null
      },
      {
        "fieldKey": "rushStatus",
        "fieldName": "Rush Status",
        "fieldType": "Boolean",
        "choiceList": null
      }
    ]
  }
]

Upload a document

Uploads and attaches a document to a specific case record.

  • Method: POST
  • Endpoint: /cmgt-uploadFile

Request parameters:

Parameter Type Required Description
caseId Integer Yes The ID of the case to attach the document to.
isPrivate Boolean No Indicates whether the document is private.

Header parameters:

Parameter Type Required Description
Appian-Document-Name Text Yes The name of the document that is uploaded.

Request body:

The document file, sent as a multipart form upload.

Response body:

Field Type Description
documentId Integer The ID of the uploaded document.

Example request:

POST /uploadFile?caseId=1&isPrivate=true

The request body contains the document file as a multipart form upload.

Example response:

1
2
3

{
  "documentId": 5012
}

Error handling

Each endpoint returns structured error messages when a request contains invalid or missing data. The following table lists the standard error messages returned by the Case API Library:

Error code Error message Cause
400 "Invalid JSON request" The request body is not in a valid JSON format.
400 "Missing required parameter" A required field was not included in the request body.
400 "Invalid data type" A field value does not match the expected data type. This includes unsupported characters (such as emojis) in text fields.
400 "Invalid value" A reference ID (such as status ID, priority ID, or case type ID) does not correspond to a valid record.
400 "Invalid format" A field value does not match the expected format (for example, email address, phone number, postal code). Also returned when submitter emails are not unique across the request.
400 "Value for parameter exceeds character length" A field value exceeds the configured maximum character length.
400 "Invalid batch size" The requested batch size exceeds the maximum allowed value of 1000.
500 "There was an error starting the process" An error occurred while starting the case workflow process.
500 "Failed to move document to the specified folder." An error occurred while moving the document from the temporary folder to the target location.

Next steps

Now that you have set up the Case API Library module, external systems can begin calling the API endpoints to create, update, and retrieve case data in Case Management Studio.

For a high-level overview of the module and its capabilities, see the Case API Library Overview.

Feedback