The Case API provides endpoints that enable you to retrieve and update Customer Service Management (CSM) case records.

In addition, you can generate new social media profile records when creating a case.

The Case API requires the Customer Service plugin (com.sn_customerservice) and is provided within the sn_customerservice namespace.

Users must have the csm_ws_integration role for full API access. External users with the sn_customerservice.customer or sn_customerservice.consumer roles can also access the endpoints.

Case - GET /sn_customerservice/case/{id}/activities

Retrieves the activity stream for a specified Customer Service Management (CSM) case.

Use this endpoint to retrieve all entries from the activity stream for a specified record from the Case [sn_customerservice_case] table.

To use this endpoint, users must have the csm_ws_integration, sn_customerservice.customer, or sn_customerservice.consumer role.

Note: You can reference all sysparm query parameters using either their full name or their shortened name (without the sysparm_ prefix). For example, for sysparm_limit you can also use limit.

URL format

Versioned URL: /api/sn_customerservice/{api_version}/case/{id}/activities

Default URL: /api/sn_customerservice/case/{id}/activities

Supported request parameters

Table 1. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
id Sys_id or case number of the case to retrieve. Located in the Case [sn_customerservice_case] table. Results will be unpredictable if a specified case number is shared by two or more cases.

Data type: String
Table 2. Query parameters
Name Description
sysparm_activity_type Filters the type of activities to return from the activity stream. The entries.element parameter contains the activity type for each activity.
For example:
  • sysparm_activity_type=attachment
  • sysparm_activity_type=work_notes
  • sysparm_activity_type=attachment,work_notes
  • sysparm_ activity_type=attachment,work_notes,comments

Data type: String

Default: Returns all types of activity.
sysparm_limit Maximum number of records to return. Unusually large sysparm_limit values can impact system performance. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval.

Data type: Number
sysparm_offset Starting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks.

For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use sysparm_offset=sysparm_offset+sysparm_limit, until you reach the end of all records.

Do not pass a negative number in the sysparm_offset parameter.

Data type: Number

Default: 0
Table 3. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 4. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 5. Response headers
Header Description
Link REST response data can be split into multiple result sets. Where applicable, the response header contains different links for the first set, previous set, next set, and the last set of records.

For example:

https://<instance name>.service-now.com/api/now/table/cmdb_ci?sysparm_offset=40&sysparm_limit=1000>;rel="next",

https://<instance name>.service-now.com/api/now/table/cmdb_ci?sysparm_offset=40&sysparm_limit=1000>;rel="prev",

https://<instance name>.service-now.com/api/now/table/cmdb_ci?sysparm_offset=0&sysparm_limit=1000>;rel="first",

https://<instance name>.service-now.com/api/now/table/cmdb_ci?sysparm_offset=2780&sysparm_limit=1000>;rel="last"
X-Total-Count Response header showing the total number of records matching the request when the sysparm_limit or sysparm_offset query parameters are specified.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Example: cURL request

Retrieve the complete activity stream for a CSM case by sys_id.

curl --request GET 'https://instance.servicenow.com/api/sn_customerservice/case/f352dc9387632300d6b0a7da0acb0b60/activities'  \
--request GET \
--header 'Accept: application/json' \
--user 'username':'password'

The response shows a single activity stream entry for the specified case, an Additional comments journal entry submitted by the agent.

{
  "result": {
    "display_value": "CS0001401",
    "sys_id": "f352dc9387632300d6b0a7da0acb0b60",
    "short_description": "Laptop is not working properly",
    "number": "CS0001401",
    "entries": [
      {
        "sys_created_on_adjusted": "2020-05-04 14:15:44",
        "sys_id": "600b6e4adb241010d045232d1396196a",
        "login_name": "John Jason",
        "user_sys_id": "da419c1fc312310015519f2974d3ae15",
        "initials": "JJ",
        "sys_created_on": "2020-05-04 21:15:44",
        "contains_code": "false",
        "field_label": "Additional comments",
        "name": "John Jason",
        "value": "Hi, Alex. Can you please send me a photo of the label on your laptop so we can send you the correct replacement?",
        "element": "comments"
      }
    ],
    "user_sys_id": "b1e0989f87232300d6b0a7da0acb0beb",
    "user_full_name": "Mark Johnson",
    "user_login": "admin",
    "label": "Case",
    "table": "sn_customerservice_case",
    "journal_fields": [
      {
        "can_read": true,
        "color": "transparent",
        "can_write": true,
        "name": "comments",
        "label": "Additional comments"
      },
      {
        "can_read": true,
        "color": "gold",
        "can_write": true,
        "name": "work_notes",
        "label": "Work notes"
      }
    ],
    "sys_created_on": "2019-02-15 21:57:04",
    "sys_created_on_adjusted": "2019-02-15 13:57:04"
  }
}

Case - GET /sn_customerservice/case/field_values/{field_name}

Retrieves the list of possible field values for a choice or reference field in the Case [sn_customerservice_case] table.

To use this endpoint, users must have the csm_ws_integration, sn_customerservice.customer, or sn_customerservice.consumer role.

Use this endpoint to populate field value lists in case creation forms.

When you request values for a reference field, any reference qualifiers defined for the requested field in the Dictionary Entry [sys_dictionary] table are applied. For more information on reference qualifiers, see Reference qualifiers.

You can use the sysparm_ref_qual_input query parameter to specify field values to use when evaluating JavaScript reference qualifiers. For an example, see the query parameter listing below.

When you request values for a choice field that is dependent on another field, you can use the sysparm_dependent_value query parameter to specify a value for the dependency parent field and restrict the returned field values accordingly. For more details on dependent fields, see Make a field dependent.

Note: You can reference all sysparm query parameters using either their full name or their shortened name (without the sysparm_ prefix). For example, for sysparm_limit you can also use limit.

URL format

Versioned URL: /api/sn_customerservice/{api_version}/case/field_values/{field_name}

Default URL: /api/sn_customerservice/case/field_values/{field_name}

Supported request parameters

Table 7. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
field_name Name of a choice or reference field in the Case [sn_customerservice_case] table.

Data type: String
Table 9. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 10. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 11. Response headers
Header Description
Link REST response data can be split into multiple result sets. Where applicable, the response header contains different links for the first set, previous set, next set, and the last set of records.

For example:

https://<instance name>.service-now.com/api/now/table/cmdb_ci?sysparm_offset=40&sysparm_limit=1000>;rel="next",

https://<instance name>.service-now.com/api/now/table/cmdb_ci?sysparm_offset=40&sysparm_limit=1000>;rel="prev",

https://<instance name>.service-now.com/api/now/table/cmdb_ci?sysparm_offset=0&sysparm_limit=1000>;rel="first",

https://<instance name>.service-now.com/api/now/table/cmdb_ci?sysparm_offset=2780&sysparm_limit=1000>;rel="last"

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Name Description
result Array of objects in which each object describes a single value for the requested field.

Data type: Array

"result": [
  {
    "label": "String",
    "value": "String"
  }
]
result.label Display value for the field value.

Data type: String
result.value Field value.

Data type: String

Example: cURL request

Retrieve values for the contact reference field from all cases:

curl 'https://instance.servicenow.com/api/sn_customerservice/case/field_values/contact' \
--request GET \
--header 'Accept: application/json' \
--user 'username':'password'

The response displays labels and values for matching contacts:

{
  "result": [
    {
      "label": "Amy Pascal",
      "value": "268e22b0d7300200e5982cf65e6103d3"
    },
    {
      "label": "Marta Hoch",
      "value": "8c974d254fb81200025ba3618110c707"
    },
    {
      "label": "Charlie Brown",
      "value": "078d399dd7600200e5982cf65e6103a2"
    },
    {
      "label": "Alex Linde",
      "value": "60beb5e7d7600200e5982cf65e6103ad"
    },
    {
      "label": "Crissy Stark",
      "value": "00189b324f1e0200c0adfe618110c76d"
    },
    {
      "label": "Denis Koch",
      "value": "07e6fa386f0331003b3c498f5d3ee4a1"
    }
  ]
}

Case - GET /sn_customerservice/case/{id}/field_values/{field_name}

Retrieves the list of possible field values for a choice or reference field for a specified record in the Case [sn_customerservice_case] table.

To use this endpoint, users must have the csm_ws_integration, sn_customerservice.customer, or sn_customerservice.consumer role.

Use this endpoint to populate field value lists in case update forms.

When you request values for a reference field, any reference qualifiers defined for the requested field in the Dictionary Entry [sys_dictionary] table are applied, using values from the specified case record. For more information on reference qualifiers, see Reference qualifiers.

You can use the sysparm_ref_qual_input query parameter to override values from the specified case when evaluating JavaScript reference qualifiers. For an example, see the query parameter listing below.

When you request values for a choice field that is dependent on another field, this endpoint limits returned field values based on the dependency parent field value selected in the specified case record. For more details on dependent fields, see Make a field dependent.

You can use the sysparm_dependent_value query parameter to override the selection from the dependency parent field. For an example, see the query parameter listing below.

Note: You can reference all sysparm query parameters using either their full name or their shortened name (without the sysparm_ prefix). For example, for sysparm_limit you can also use limit.

URL format

Versioned URL: /api/sn_customerservice/{api_version}/case/{id}/field_values/{field_name}

Default URL: /api/sn_customerservice/case/{id}/field_values/{field_name}

Supported request parameters

Table 13. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
field_name Name of a choice or reference field. Located in the Case [sn_customerservice_case] table.

Data type: String
id Sys_id of a record. Located in the Case [sn_customerservice_case] table to use when evaluating reference qualifiers.

Data type: String
Table 15. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 16. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 17. Response headers
Header Description
Link REST response data can be split into multiple result sets. Where applicable, the response header contains different links for the first set, previous set, next set, and the last set of records.

For example:

https://<instance name>.service-now.com/api/now/table/cmdb_ci?sysparm_offset=40&sysparm_limit=1000>;rel="next",

https://<instance name>.service-now.com/api/now/table/cmdb_ci?sysparm_offset=40&sysparm_limit=1000>;rel="prev",

https://<instance name>.service-now.com/api/now/table/cmdb_ci?sysparm_offset=0&sysparm_limit=1000>;rel="first",

https://<instance name>.service-now.com/api/now/table/cmdb_ci?sysparm_offset=2780&sysparm_limit=1000>;rel="last"

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Name Description
result Array of objects in which each object describes a single value for the requested field.

Data type: Array

"result": [
  {
    "label": "String",
    "value": "String"
  }
]
result.label Display value for the field value.

Data type: String
result.value Field value.

Data type: String

Example: cURL request

Retrieve the contact reference field value for an existing case:

curl 'https://instance.servicenow.com/api/sn_customerservice/case/f352dc9387632300d6b0a7da0acb0b60/field_values/contact' \
--request GET \
--header 'Accept: application/json' \
--user 'username':'password'

The response displays the label and value for the contact assigned to the specified case:

{
  "result": [
    {
      "label": "Alex Linde",
      "value": "60beb5e7d7600200e5982cf65e6103ad"
    }
  ]
}

Case - GET /sn_customerservice/case/{id}

Retrieves the specified Customer Service Management (CSM) case.

To use this endpoint, users must have the csm_ws_integration, sn_customerservice.customer, or sn_customerservice.consumer role.

Note: You can reference all sysparm query parameters using either their full name or their shortened name (without the sysparm_ prefix). For example, for sysparm_limit you can also use limit.

URL format

Versioned URL: /api/sn_customerservice/{api_version}/case/{id}

Default URL: /api/sn_customerservice/case/{id}

Supported request parameters

Table 19. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
id Sys_id or case number for the case to retrieve. Located in the Case [sn_customerservice_case] table. Results will be unpredictable if a specified case number is shared by two or more cases.

Data type: String
Table 20. Query parameters
Name Description
sysparm_display_value Determines the type of data returned, either the actual values from the database or the display values of the fields. Display values are manipulated based on the actual value in the database and user or system settings and preferences.
If returning display values, the value that is returned is dependent on the field type.
  • Choice fields: The database value may be a number, but the display value will be more descriptive.
  • Date fields: The database value is in UTC format, while the display value is based on the user's time zone.
  • Encrypted text: The database value is encrypted, while the displayed value is unencrypted based on the user's encryption context.
  • Reference fields: The database value is sys_id, but the display value is a display field of the referenced record.

Data type: String

Valid values:

  • true: Returns the display values for all fields.
  • false: Returns the actual values from the database.
  • all: Returns both actual and display values.

Default: false

Note: There is no preferred method for setting this parameter. However, specifying the display value may cause performance issues since it is not reading directly from the database and may include referencing other fields and records. For more information on display values and actual values, see Table API FAQs (KB0534905).
Table 21. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 22. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 23. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 24. Status codes
Status code Description
200 Successful. The request was successfully processed.
404 Indicates that the request is invalid. Could be due to one of the following reasons:
  • Requested case does not exist.
  • User does not have access to the case.

Response body parameters (JSON or XML)

Example: cURL request

curl "https://instance.servicenow.com/api/sn_customerservice/case/ba325dbe64f01300964fae39b050e9a6" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  "result": {
    "parent": "",
    "caused_by": "",
    "watch_list": "",
    "active_escalation": "",
    "upon_reject": "cancel",
    "sys_updated_on": "2018-06-18 00:14:43",
    "support_manager": "",
    "approval_history": "",
    "skills": "",
    "number": "CS0000871",
    "problem": "",
    "state": "10",
    "case": "Acme Analytics performance degradation​CS0000871",
    "sys_created_by": "john.jason",
    "knowledge": "false",
    "order": "",
    "cmdb_ci": "",
    "delivery_plan": "",
    "impact": "3",
    "contract": "",
    "active": "true",
    "work_notes_list": "",
    "auto_created_case": "false",
    "priority": "1",
    "sys_domain_path": "/",
    "rejection_goto": "",
    "first_response_time": "",
    "business_duration": "",
    "group_list": "",
    "child_case_creation_progress": "false",
    "sync_driver": "false",
    "approval_set": "",
    "wf_activity": "",
    "short_description": "Acme Analytics performance degradation",
    "correlation_display": "",
    "delivery_task": "",
    "work_start": "",
    "recipient_list": "",
    "additional_assignee_list": "",
    "notify": "1",
    "sys_class_name": "sn_customerservice_case",
    "closed_by": "",
    "follow_up": "",
    "contact_local_time": "",
    "sn_app_cs_social_social_profile": "",
    "reassignment_count": "0",
    "contact_time_zone": "",
    "notes_to_comments": "false",
    "assigned_to": "da419c1fc312310015519f2974d3ae15",
    "product": "4c84a024c3211200bb779f2974d3aef6",
    "variables": "",
    "variable_pool": "",
    "hierarchical_variables": "variable_pool",
    "sla_due": "",
    "change": "",
    "comments_and_work_notes": "",
    "partner": "",
    "escalation": "0",
    "upon_approval": "proceed",
    "partner_contact": "",
    "correlation_id": "",
    "asset": "",
    "made_sla": "true",
    "resolved_by": "",
    "sys_updated_by": "john.jason",
    "opened_by": "da419c1fc312310015519f2974d3ae15",
    "user_input": "",
    "sys_created_on": "2018-06-18 00:14:39",
    "contact": "",
    "sys_domain": "global",
    "closed_at": "",
    "follow_the_sun": "false",
    "entitlement": "",
    "business_service": "",
    "business_impact": "Acme Anaytics performance is extremely slow. Customers are not able to use it. ",
    "time_worked": "",
    "expected_start": "",
    "opened_at": "2018-06-18 00:14:39",
    "work_end": "",
    "resolved_at": "",
    "case_report": "27329dbe64f01300964fae39b050e93c",
    "subcategory": "0",
    "work_notes": "",
    "assignment_group": "",
    "cause": "",
    "description": "",
    "calendar_duration": "",
    "close_notes": "",
    "sys_id": "ba325dbe64f01300964fae39b050e9a6",
    "contact_type": "web",
    "resolution_code": "",
    "probable_cause": "",
    "urgency": "3",
    "company": "",
    "major_case_state": "accepted",
    "consumer": "",
    "activity_due": "",
    "comments": "",
    "approval": "not requested",
    "due_date": "",
    "sys_mod_count": "2",
    "sys_tags": "",
    "active_account_escalation": "",
    "location": "",
    "category": "1",
    "account": ""
  }
}

Case - GET /sn_customerservice/case

Retrieves a specified set of Customer Service Management (CSM) cases.

To use this endpoint, users must have the csm_ws_integration, sn_customerservice.customer, or sn_customerservice.consumer role.

Note: You can reference all sysparm query parameters using either their full name or their shortened name (without the sysparm_ prefix). For example, for sysparm_limit you can also use limit.

URL format

Versioned URL: /api/sn_customerservice/{api_version}/case

Default URL: /api/sn_customerservice/case

Supported request parameters

Table 25. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
Table 27. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 28. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 29. Response headers
Header Description
Link REST response data can be split into multiple result sets. Where applicable, the response header contains different links for the first set, previous set, next set, and the last set of records.

For example:

https://<instance name>.service-now.com/api/now/table/cmdb_ci?sysparm_offset=40&sysparm_limit=1000>;rel="next",

https://<instance name>.service-now.com/api/now/table/cmdb_ci?sysparm_offset=40&sysparm_limit=1000>;rel="prev",

https://<instance name>.service-now.com/api/now/table/cmdb_ci?sysparm_offset=0&sysparm_limit=1000>;rel="first",

https://<instance name>.service-now.com/api/now/table/cmdb_ci?sysparm_offset=2780&sysparm_limit=1000>;rel="last"
X-Total-Count Response header showing the total number of records matching the request when the sysparm_limit or sysparm_offset query parameters are specified.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 30. Status codes
Status code Description
200 Successful. The request was successfully processed.
401 Unauthorized. The user credentials are incorrect or have not been passed.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Example: cURL request

Retrieve the third and fourth CSM cases listed for a specific account.

curl "https://instance.servicenow.com/api/sn_customerservice/case?sysparm_query=account=86837a386f0331003b3c498f5d3ee4ca&sysparm_limit=2&sysparm_offset=2" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

The response shows the two cases.

{
  "result": [{
    "parent": "",
    "caused_by": "",
    "watch_list": "",
    "active_escalation": "",
    "upon_reject": "cancel",
    "sys_updated_on": "2017-06-17 16:37:13",
    "support_manager": "",
    "approval_history": "",
    "skills": "a6d64b11d772120058c92cf65e610357,9b178b11d772120058c92cf65e610382,1c76ec15d703120058c92cf65e61034a",
    "number": "CS0000009",
    "problem": "",
    "state": "18",
    "case": "Advanced and large routers making noise​CS0000009",
    "sys_created_by": "alex linde",
    "knowledge": "false",
    "order": "",
    "cmdb_ci": "",
    "delivery_plan": "",
    "impact": "3",
    "contract": "",
    "active": "true",
    "work_notes_list": "",
    "auto_created_case": "false",
    "priority": "3",
    "sys_domain_path": "/",
    "rejection_goto": "",
    "first_response_time": "",
    "business_duration": "",
    "group_list": "",
    "child_case_creation_progress": "false",
    "sync_driver": "false",
    "approval_set": "",
    "wf_activity": "",
    "short_description": "Advanced and large routers making noise",
    "correlation_display": "",
    "delivery_task": "",
    "work_start": "",
    "recipient_list": "",
    "additional_assignee_list": "",
    "notify": "1",
    "sys_class_name": "sn_customerservice_case",
    "closed_by": "",
    "follow_up": "",
    "contact_local_time": "",
    "sn_app_cs_social_social_profile": "",
    "reassignment_count": "1",
    "contact_time_zone": "",
    "notes_to_comments": "false",
    "assigned_to": "85453c616fc331003b3c498f5d3ee4fa",
    "product": "5f5fbcc3c0a8010e00f3b27814f3b96b",
    "variables": "",
    "variable_pool": "",
    "hierarchical_variables": "variable_pool",
    "sla_due": "",
    "change": "",
    "comments_and_work_notes": "",
    "partner": "",
    "escalation": "0",
    "upon_approval": "proceed",
    "partner_contact": "",
    "correlation_id": "",
    "asset": "a8fb6024d7700200e5982cf65e61034d",
    "made_sla": "true",
    "resolved_by": "",
    "sys_updated_by": "admin",
    "opened_by": "60beb5e7d7600200e5982cf65e6103ad",
    "user_input": "",
    "sys_created_on": "2016-09-19 16:49:18",
    "contact": {
      "country": "",
      "calendar_integration": "1",
      "last_position_update": "",
      "last_login_time": "2018-05-10 19:50:26",
      "last_login_device": "0:0:0:0:0:0:0:1%0",
      "source": "",
      "sys_updated_on": "2018-02-16 21:30:03",
      "building": "",
      "web_service_access_only": "false",
      "notification": "1",
      "sys_updated_by": "venki",
      "enable_multifactor_authn": "false",
      "sys_created_on": "2018-02-16 21:29:11",
      "sys_domain": "global",
      "agent_status": "",
      "state": "",
      "vip": "false",
      "sys_created_by": "venki",
      "longitude": "",
      "zip": "",
      "home_phone": "",
      "time_format": "",
      "last_login": "",
      "default_perspective": "",
      "geolocation_tracked": "false",
      "active": "true",
      "time_sheet_policy": "",
      "sys_domain_path": "/",
      "phone": "(626) 722-6969",
      "cost_center": "",
      "name": "Julie Lewis",
      "employee_number": "",
      "gender": "",
      "city": "",
      "user_name": "julie.lewis",
      "failed_attempts": "",
      "edu_status": "faculty",
      "latitude": "",
      "roles": "",
      "title": "Operations Manager",
      "sys_class_name": "customer_contact",
      "sys_id": "4d147a386f0331003b3c498f5d3ee437",
      "internal_integration_user": "false",
      "ldap_server": "",
      "mobile_phone": "",
      "street": "",
      "company": "86837a386f0331003b3c498f5d3ee4ca",
      "department": "",
      "first_name": "Julie",
      "preferred_language": "en",
      "introduction": "",
      "email": "julie.lewis@mailinator.com",
      "manager": "",
      "locked_out": "false",
      "sys_mod_count": "1",
      "last_name": "Lewis",
      "photo": "",
      "sys_tags": "",
      "middle_name": "",
      "time_zone": "",
      "schedule": "",
      "on_schedule": "",
      "date_format": "",
      "location": "",
      "account": "86837a386f0331003b3c498f5d3ee4ca"
    },
    "sys_domain": "global",
    "closed_at": "",
    "follow_the_sun": "false",
    "entitlement": "",
    "business_service": "",
    "business_impact": "",
    "time_worked": "",
    "expected_start": "",
    "opened_at": "2016-09-19 16:49:18",
    "work_end": "",
    "resolved_at": "",
    "case_report": "",
    "subcategory": "0",
    "work_notes": "",
    "assignment_group": "6a42f4616fc331003b3c498f5d3ee46f",
    "cause": "",
    "description": "",
    "calendar_duration": "",
    "close_notes": "",
    "sys_id": "dccc6024d7700200e5982cf65e6103e5",
    "contact_type": "web",
    "resolution_code": "",
    "probable_cause": "",
    "urgency": "3",
    "company": "",
    "major_case_state": "",
    "consumer": "",
    "activity_due": "",
    "comments": "",
    "approval": "not requested",
    "due_date": "",
    "sys_mod_count": "5",
    "sys_tags": "",
    "active_account_escalation": "",
    "location": "",
    "category": "1",
    "account": {
      "banner_image_light": "",
      "country": "USA",
      "parent": "",
      "notes": "",
      "stock_symbol": "",
      "discount": "",
      "active_escalation": "",
      "sys_updated_on": "2019-01-03 19:37:35",
      "apple_icon": "",
      "number": "ACCT0000001",
      "sys_updated_by": "admin",
      "fiscal_year": "",
      "sys_created_on": "2018-02-20 21:29:16",
      "contact": "4d147a386f0331003b3c498f5d3ee437",
      "stock_price": "",
      "state": "",
      "banner_image": "",
      "sys_created_by": "venki",
      "longitude": "-122.4005464",
      "zip": "94103",
      "profits": "0",
      "phone": "(626) 722-6999",
      "fax_phone": "",
      "name": "Boxeo",
      "banner_text": "",
      "account_code": "~~~~1",
      "primary": "false",
      "city": "San Francisco",
      "latitude": "37.7838391",
      "sys_class_name": "customer_account",
      "manufacturer": "false",
      "account_parent": "",
      "sys_id": "86837a386f0331003b3c498f5d3ee4ca",
      "market_cap": "0",
      "num_employees": "",
      "rank_tier": "",
      "street": "747 Howard St",
      "vendor": "false",
      "lat_long_error": "",
      "theme": "",
      "vendor_type": "",
      "website": "www.boxeo.com",
      "revenue_per_year": "0",
      "publicly_traded": "false",
      "sys_mod_count": "9",
      "sys_tags": "",
      "partner": "false",
      "registration_code": "BOXEO",
      "vendor_manager": "",
      "account_path": "~~~~1",
      "primary_contact": "4d147a386f0331003b3c498f5d3ee437",
      "customer": "true"
    }
  }, {
    "parent": "",
    "caused_by": "",
    "watch_list": "",
    "active_escalation": "",
    "upon_reject": "cancel",
    "sys_updated_on": "2019-01-15 23:28:00",
    "support_manager": "",
    "approval_history": "",
    "skills": "a6d64b11d772120058c92cf65e610357,9b178b11d772120058c92cf65e610382,1c76ec15d703120058c92cf65e61034a",
    "number": "CS0000005",
    "problem": "",
    "state": "6",
    "case": "Urgent issue, need help ...​CS0000005",
    "sys_created_by": "admin",
    "knowledge": "false",
    "order": "",
    "cmdb_ci": "",
    "delivery_plan": "",
    "impact": "",
    "contract": "495e16b96f0731003b3c498f5d3ee4af",
    "active": "true",
    "work_notes_list": "",
    "auto_created_case": "false",
    "priority": "1",
    "sys_domain_path": "/",
    "rejection_goto": "",
    "first_response_time": "",
    "business_duration": "",
    "group_list": "",
    "child_case_creation_progress": "false",
    "sync_driver": "false",
    "approval_set": "",
    "wf_activity": "",
    "short_description": "Urgent issue, need help ...",
    "correlation_display": "",
    "delivery_task": "",
    "work_start": "",
    "recipient_list": "",
    "additional_assignee_list": "",
    "notify": "",
    "sys_class_name": "sn_customerservice_case",
    "closed_by": "",
    "follow_up": "",
    "contact_local_time": "",
    "sn_app_cs_social_social_profile": "",
    "reassignment_count": "",
    "contact_time_zone": "",
    "notes_to_comments": "false",
    "assigned_to": "85453c616fc331003b3c498f5d3ee4fa",
    "product": "9068b0a16fc331003b3c498f5d3ee438",
    "variables": "",
    "variable_pool": "",
    "hierarchical_variables": "variable_pool",
    "sla_due": "",
    "change": "",
    "comments_and_work_notes": "",
    "partner": "",
    "escalation": "",
    "upon_approval": "proceed",
    "partner_contact": "",
    "correlation_id": "",
    "asset": "b8defca16fc331003b3c498f5d3ee4e7",
    "made_sla": "false",
    "resolved_by": "",
    "sys_updated_by": "jodi.seals",
    "opened_by": "ddce70866f9331003b3c498f5d3ee417",
    "user_input": "",
    "sys_created_on": "2019-01-02 20:00:00",
    "contact": {
      "country": "",
      "calendar_integration": "1",
      "last_position_update": "",
      "last_login_time": "2018-03-10 21:48:11",
      "last_login_device": "",
      "source": "",
      "sys_updated_on": "2019-01-03 05:49:34",
      "building": "",
      "web_service_access_only": "false",
      "notification": "2",
      "sys_updated_by": "system",
      "enable_multifactor_authn": "false",
      "sys_created_on": "2018-03-04 20:26:32",
      "sys_domain": "global",
      "agent_status": "",
      "state": "",
      "vip": "false",
      "sys_created_by": "admin",
      "longitude": "",
      "zip": "",
      "home_phone": "",
      "time_format": "",
      "last_login": "",
      "default_perspective": "",
      "geolocation_tracked": "false",
      "active": "true",
      "time_sheet_policy": "",
      "sys_domain_path": "/",
      "phone": "+1 858 287 7834",
      "cost_center": "",
      "name": "George Warren",
      "employee_number": "",
      "gender": "",
      "city": "",
      "user_name": "george.warren",
      "failed_attempts": "",
      "edu_status": "",
      "latitude": "",
      "roles": "",
      "title": "Network Administrator",
      "sys_class_name": "customer_contact",
      "sys_id": "ddce70866f9331003b3c498f5d3ee417",
      "internal_integration_user": "false",
      "ldap_server": "",
      "mobile_phone": "+1 858 867 7857",
      "street": "",
      "company": "86837a386f0331003b3c498f5d3ee4ca",
      "department": "",
      "first_name": "George",
      "preferred_language": "",
      "introduction": "",
      "email": "geo.warren@mailinator.com",
      "manager": "",
      "locked_out": "false",
      "sys_mod_count": "3",
      "last_name": "Warren",
      "photo": "",
      "sys_tags": "",
      "middle_name": "",
      "time_zone": "",
      "schedule": "",
      "on_schedule": "",
      "date_format": "",
      "location": "25ab8e460a0a0bb300857304ff811af5",
      "account": "86837a386f0331003b3c498f5d3ee4ca"
    },
    "sys_domain": "global",
    "closed_at": "",
    "follow_the_sun": "false",
    "entitlement": "1eb7893a6f1b31003b3c498f5d3ee4dd",
    "business_service": "",
    "business_impact": "",
    "time_worked": "",
    "expected_start": "",
    "opened_at": "2019-01-02 20:00:00",
    "work_end": "",
    "resolved_at": "",
    "case_report": "",
    "subcategory": "0",
    "work_notes": "",
    "assignment_group": "0df0c400c322310015519f2974d3ae23",
    "cause": "",
    "description": "",
    "calendar_duration": "",
    "close_notes": "",
    "sys_id": "cf866683c3033100b12d9f2974d3ae1f",
    "contact_type": "web",
    "resolution_code": "",
    "probable_cause": "",
    "urgency": "3",
    "company": "",
    "major_case_state": "",
    "consumer": "",
    "activity_due": "",
    "comments": "",
    "approval": "",
    "due_date": "2016-08-04 20:36:23",
    "sys_mod_count": "0",
    "sys_tags": "",
    "active_account_escalation": "",
    "location": "",
    "category": "1",
    "account": {
      "banner_image_light": "",
      "country": "USA",
      "parent": "",
      "notes": "",
      "stock_symbol": "",
      "discount": "",
      "active_escalation": "",
      "sys_updated_on": "2019-01-03 19:37:35",
      "apple_icon": "",
      "number": "ACCT0000001",
      "sys_updated_by": "admin",
      "fiscal_year": "",
      "sys_created_on": "2018-02-20 21:29:16",
      "contact": "4d147a386f0331003b3c498f5d3ee437",
      "stock_price": "",
      "state": "",
      "banner_image": "",
      "sys_created_by": "venki",
      "longitude": "-122.4005464",
      "zip": "94103",
      "profits": "0",
      "phone": "(626) 722-6999",
      "fax_phone": "",
      "name": "Boxeo",
      "banner_text": "",
      "account_code": "~~~~1",
      "primary": "false",
      "city": "San Francisco",
      "latitude": "37.7838391",
      "sys_class_name": "customer_account",
      "manufacturer": "false",
      "account_parent": "",
      "sys_id": "86837a386f0331003b3c498f5d3ee4ca",
      "market_cap": "0",
      "num_employees": "",
      "rank_tier": "",
      "street": "747 Howard St",
      "vendor": "false",
      "lat_long_error": "",
      "theme": "",
      "vendor_type": "",
      "website": "www.boxeo.com",
      "revenue_per_year": "0",
      "publicly_traded": "false",
      "sys_mod_count": "9",
      "sys_tags": "",
      "partner": "false",
      "registration_code": "BOXEO",
      "vendor_manager": "",
      "account_path": "~~~~1",
      "primary_contact": "4d147a386f0331003b3c498f5d3ee437",
      "customer": "true"
    }
  }]
}

Case - POST /sn_customerservice/case

Creates a new Customer Service Management (CSM) case.

To use this endpoint, users must have the csm_ws_integration, sn_customerservice.customer, or sn_customerservice.consumer role.

You can create different types of cases depending on whether you are working in a business-to-business (B2B) or business-to-consumer (B2C) environment, or creating a case for an order or product.

In addition, you can create a social media profile for a contact, consumer, or account using this endpoint. To create a social media profile, you must specify the following parameters in the request body:
  • social_channel
  • social_handle
  • social_handle_type
  • social_handle_url
  • social_post_url

All request body parameters are optional. Some parameters are only valid in one environment or the other (B2B or B2C), and are noted as such in the request body parameter descriptions. If you specify a contact, the account, case report, contract, and entitlement parameters are defaulted to the values defined in the contact/account records. If you specify an account, the case report, contract, and entitlement parameters are defaulted to the values defined in the account record (unless overridden by passed in parameters.) If you do not pass any parameters to the endpoint, the case record is created with only default information (defined in the table below) and instance generated values (sys_*). All other parameters are set with their equivalent of a null value. In addition to the list of parameters defined below, which define the parameters found in a base system, the endpoint also accepts custom case fields and any additional case fields configured in your instance. For additional information on these elements, refer to your specific table definitions [System Definition > Tables].

Warning: This endpoint does not perform parameter validation as doing so can create excessive overhead. If a request parameter is misspelled, is not valid for the type of case, or is not supported by the endpoint, it is either ignored without warning or can cause unexpected results. For example, if you create a consumer or contact for the wrong type of case or mismatch a contact with an account.
Warning: By default, external users who have the sn_customerservice.customer or sn_customerservice.consumer role can only set the account, asset, comments, consumer, contact, contact_type, partner, partner_contact, priority, product, short_description, and state fields using this endpoint.
Note: You can reference all sysparm query parameters using either their full name or their shortened name (without the sysparm_ prefix). For example, for sysparm_limit you can also use limit.

URL format

Versioned URL: /api/sn_customerservice/{api_version}/case

Default URL: /api/sn_customerservice/case

Supported request parameters

Table 31. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
Table 32. Query parameters
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 34. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Content-Type Data format of the request body. Only supports application/json.
Table 35. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 36. Status codes
Status code Description
201 New case record was successfully created.
401 Unauthorized. The user credentials are incorrect or have not been passed.
500 Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Element Description
number Associated case number.

Data type: String
sys_id Sys_id of the new case record created in the Case [sn_customerservice_case] table.

Data type: String

Example: cURL request

The following example illustrates how to create a case based on a consumer and also create a new social media account that is associated with the case.

curl "https://instance.servicenow.com/api/sn_customerservice/case" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{ \
    consumer: \"cd97ef1ddb8bc7006b7a9646db9619ac\", \
    contact_type: \"social\", \
    priority: \"4\", \
    short_description: \"Consumer Test Case\", \
    social_channel: \"TWITTER\", \
    social_handle: \"consumertwo\", \
    social_handle_type: \"Consumer\", \
    social_handle_url: \"https://www.twitter.com/consumertwo\", \
    social_post_url: \"https://twitter.com/MuleSoft/status/829092185022750720\"}" \
--user "username":"password"

{
  "result": {
    "sys_id": "0397c743db436f0057c3fd441d96197f",
    "number": "CS0001005"
  }
}

Example: cURL request

The following example illustrates how to create a case for an account.

curl "https://instance.servicenow.com/api/sn_customerservice/case" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{ \
    account: \"051f62b0d7300200e5982cf65e610333\", \
    contact_type: \"phone\", \
    priority: \"1\", \
    short_description: \"Power Outage\"}" \
--user "username":"password"

{
  "result": {
    "sys_id": "b88366ffdb1b0b00216e9ee6db96190b",
    "number": "CS0001021"
  }
}

Example: cURL request

The following example illustrates how to create a case for a specific contact. Note that if an account is specified within the contact record, that account is automatically assigned to the case.

curl "https://instance.servicenow.com/api/sn_customerservice/case" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{ \
    contact: \"62fe1c97db76c3006b7a9646db961999\", \
    contact_type: \"phone\", \
    priority: \"3\", \
    short_description: \"Power Outage\"}" \
--user "username":"password"

{
  "result": {
    "sys_id": "bf916affdb1b0b00216e9ee6db961937",
    "number": "CS0001013"
  }
}

Case - PUT /sn_customerservice/case/{id}

Updates the specified existing Customer Service Management (CSM) case with the passed-in parameters.

Warning: This endpoint does not perform parameter validation as doing so can create excessive overhead. If a request parameter is misspelled, is not valid for the type of case, or is not supported by the endpoint, it is either ignored without warning or can cause unexpected results. For example, if you create a consumer or contact for the wrong type of case or mismatch a contact with an account.
Warning: By default, external users who have the sn_customerservice.customer or sn_customerservice.consumer role can only set the comments and state fields using this endpoint. Admins can enable external users to set additional fields by specifying the field names in the UPDATE_ALLOWED_FIELDS array defined in the CaseRESTAPIValidatorForExternalUser script include. Exercise caution when adding new fields to this array, as there may not be existing validators for input into those fields. For more information on script includes, see Script includes.
Note: You can reference all sysparm query parameters using either their full name or their shortened name (without the sysparm_ prefix). For example, for sysparm_limit you can also use limit.

URL format

Versioned URL: /api/sn_customerservice/{api_version}/case/{id}

Default URL: /api/sn_customerservice/case/{id}

Supported request parameters

Table 37. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
id Sys_id of the case to update. Located in the Case [sn_customerservice_case] table.
Table 38. Query parameters
Name Description
sysparm_display_value Determines the type of data returned, either the actual values from the database or the display values of the fields. Display values are manipulated based on the actual value in the database and user or system settings and preferences.
If returning display values, the value that is returned is dependent on the field type.
  • Choice fields: The database value may be a number, but the display value will be more descriptive.
  • Date fields: The database value is in UTC format, while the display value is based on the user's time zone.
  • Encrypted text: The database value is encrypted, while the displayed value is unencrypted based on the user's encryption context.
  • Reference fields: The database value is sys_id, but the display value is a display field of the referenced record.

Data type: String

Valid values:

  • true: Returns the display values for all fields.
  • false: Returns the actual values from the database.
  • all: Returns both actual and display values.

Default: false

Note: There is no preferred method for setting this parameter. However, specifying the display value may cause performance issues since it is not reading directly from the database and may include referencing other fields and records. For more information on display values and actual values, see Table API FAQs (KB0534905).
sysparm_fields Comma-separated list of fields to return in the response.

Data type: String
sysparm_get_case_details Flag that indicates whether to return the updated case record.

Valid values:

  • true: Return updated case record.
  • false: Do not return the updated case record.

Data type: Boolean

Default: false

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 40. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Content-Type Data format of the request body. Only supports application/json.
Table 41. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Notes on request body parameters

All request body parameters are optional. Not all parameters apply to all case types (B2B vs B2C and order vs product.) Ensure that the parameters that you set do not conflict, such as a mismatch between the account and contact or consumer. In addition to the list of elements defined below (which define the elements found in a base system), the endpoint also accepts custom case fields and any additional case fields configured in your instance. For additional information on these elements, refer to your specific table definitions [System Definition > Tables].

Example: cURL request

The following example illustrates how to update a consumer-based case.

curl "https://instance.servicenow.com/api/sn_cusomerservice/case/0397c743db436f0057c3fd441d96197f" \
--request PUT \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{ \
  consumer: \"cd97ef1ddb8bc7006b7a9646db9619ac\", \
  contact_type: \"phone\", \
  priority: \"4\", \
  short_description: \"Consumer Test Case\"}" \
--user "username":"password"

{
  "result": {
    "sys_id": "0397c743db436f0057c3fd441d96197f",
    "number": "CS0001005"
  }
}