Customer Central API
The Customer Central API provides endpoints to access customer information and configuration details.
Use this API to obtain information records (cards) that were previously generated through the Customer Central interface.
You must have the admin or sn_esm_agent role to access this API. In addition, before this API is available in your instance you must activate the com.sn_csm_customer_central plugin.
For additional information, see Customer Central.
Parent Topic:REST API reference
Customer Central - GET /cust_central/custinfo/{context}/{context_instance}/{target}
Returns customer information and configuration details for a specific customer context.
Customer context is determined by the customer content table that you specify, either the Consumer [csm_consumer] or Contact [customer_contact] table, and its associated target table. This information is located in the Customer Information Context [sn_customercentral_cust_info_config] table.
This endpoint returns all active records (cards) within the following Customer Central configuration tables for the specified customer context:
- List Configuration [sn_customercentral_list_config]
- Record Configuration [sn_customercentral_record_config]
- Report Configuration [sn_customercentral_report_config]
- Report Group Configuration [sn_customercentral_report_group_config]
You must define any additional configuration records that you need through the Customer Central interface. For details, see Configure customer central.
URL format
Versioned URL: /api/sn_customercentral/{api_version}/cust_central/custinfo/{context}/{context_instance}/{target}
Default URL: /api/sn_customercentral/cust_central/custinfo/{context}/{context_instance}/{target}
Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.
Supported request 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 |
| context | Name of the customer context table to use.Valid values: - csm\_consumer - customer\_contact Data type: String |
| context\_instance | Sys_id of the record in the table specified in the context parameter to return. Data type: String |
| target | Target table associated with the customer context table specified in the context parameter. The combination of the context parameter andtarget parameter define a unique customer information context. Data type: String Table: Customer Information Context [sn_customercentral_cust_info_config] |
| Name | Description |
|---|---|
| before | Return all configuration records created before the specified date and time.Date type: String Format: YYYY-MM-DD or the format defined in the glide.sys.date_format system property Default: Return all configuration records created before current session time. |
| end | Last record to return. Use this value to paginate record retrieval or use with the start parameter to select a specific set of records to return.Data type: Number Default: Last record in file |
| start | 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. Don't pass a negative number. Data type: Number Default: 0 |
| 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.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json |
| 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.
| Status code | Description |
|---|---|
| 200 | Successful. The request was successfully processed. |
| 400 | Bad Request. A bad request type or malformed request was detected. Ensure that the path parameters contain valid values. |
| 401 | Unauthorized. The user credentials are incorrect or have not been passed. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
Response body parameters (JSON or XML)
| Name | Description |
|---|---|
| cards\_info | List of contact cards associated with the specified customer.Data type: Array \(content depends on selected customer\) |
| cards\_info.data\_configurations | Configuration information.Data type: Object |
| cards\_info.data\_configurations.aggregate\_field | Column name to aggregate. Data type: String |
| cards\_info.data\_configurations.aggregate\_function | Function to use to aggregate the specified table column.Possible values: - AVG - COUNT - COUNT\(DISTINCT\) - SUM Data type: String |
| cards\_info.data\_configurations.decimal\_precision | Number of digits to the right of the decimal point to return.Data type: Number |
| cards\_info.data\_configurations.filter\_query | Query string to use to refine the data used in the report.Data type: String |
| cards\_info.data\_configurations.group\_by | Name of the column to use to group the report data.Data type: String |
| cards\_info.data\_configurations.number\_of\_groups | Maximum number of groups to display in the report.Possible values:
Note: It is not recommended to change the value of the glide.ui.chart.generate_other system property, as it applies to all reports in the instance.
Data type: String |
| cards\_info.data\_configurations.show\_other | Flag that indicates whether the group "Other" appears within the report. If not all groups are to display, as defined by the number_of_groups parameter, the values of the non-display groups are combined and displayed under a single heading of "Other".Possible values:
Data type: Boolean |
| cards\_info.data\_configurations.source\_id | Table name or sys_id of the report source information. This correlates to the information in the cards_info.reportGroupConfigurations.data_configurations.source_type parameter.Data type: String |
| cards\_info.data\_configurations.source\_type | Type of information in the cards_info.reportGroupConfigurations.data_configurations.source_id parameter used to identify the source table.Possible values:
Data type: String |
| cards\_info.data\_configurations.stack\_by\_field | Name of the table column to use when implementing "stack by" in the report.Data type: String |
| cards\_info.data\_configurations.sys\_id | Sys\_id of the report used in the report configuration.Data type: String |
| cards\_info.data\_configurations.trend\_field | Name of table column to use in trend analysis.Data type: String |
| cards\_info.data\_configurations.trend\_interval | Time interval for the trend information. For example, week, month, year, etc.Data type: String |
| cards\_info.data\_configurations.type | Type of report, such as single score, donut, vertical, line, stacked bar, etc.Data type: String |
| cards\_info.encodedQuery | Encoded query string to use to refine the data that appears in the report.Data type: String |
| cards\_info.fields | List of name-value pairs that define the fields within the associated record.Data type: Array of Objects |
| cards\_info.fields.label | Field label.Data type: String |
| cards\_info.fields.value | Field value.Data type: String |
| cards\_info.listLimit | Pagination limit. Number of records to show on a list card.Data type: String |
| cards\_info.reportGroupConfigurations | List of objects that define the report groups.Data type: Array of Objects |
| cards\_info.reportGroupConfigurations.data\_configurations | Configuration information.Data type: Object |
| cards\_info.reportGroupConfigurations.data\_configurations.aggregate\_field | Column name to aggregate. Data type: String |
| cards\_info.reportGroupConfigurations.data\_configurations.aggregate\_function | Function to use to aggregate the specified table column.Possible values: - AVG - COUNT - COUNT\(DISTINCT\) - SUM Data type: String |
| cards\_info.reportGroupConfigurations.data\_configurations.decimal\_precision | Number of digits to the right of the decimal point to return.Data type: Number |
| cards\_info.reportGroupConfigurations.data\_configurations.filter\_query | Query string to use to refine the data used in the report.Data type: String |
| cards\_info.reportGroupConfigurations.data\_configurations.group\_by | Name of the column to use to group the report data.Data type: String |
| cards\_info.reportGroupConfigurations.data\_configurations.number\_of\_groups | Maximum number of groups to display in the report.Possible values:
Note: It is not recommended to change the value of the glide.ui.chart.generate_other system property, as it applies to all reports in the instance.
Data type: String |
| cards\_info.reportGroupConfigurations.data\_configurations.show\_other | Flag that indicates whether the group "Other" appears within the report. If not all groups are to display, as defined by the number_of_groups parameter, the values of the non-display groups are combined and displayed under a single heading of "Other".Possible values:
Data type: Boolean |
| cards\_info.reportGroupConfigurations.data\_configurations.source\_id | Table name or sys_id of the report source information. This correlates to the information in the cards_info.reportGroupConfigurations.data_configurations.source_type parameter.Data type: String |
| cards\_info.reportGroupConfigurations.data\_configurations.source\_type | Type of information in the cards_info.reportGroupConfigurations.data_configurations.source_id parameter used to identify the source table.Possible values:
Data type: String |
| cards\_info.reportGroupConfigurations.data\_configurations.stack\_by\_field | Name of the table column to use when implementing "stack by" in the report.Data type: String |
| cards\_info.reportGroupConfigurations.data\_configurations.sys\_id | Sys\_id of the report used in the report configuration.Data type: String |
| cards\_info.reportGroupConfigurations.data\_configurations.trend\_field | Name of table column to use in trend analysis.Data type: String |
| cards\_info.reportGroupConfigurations.data\_configurations.trend\_interval | Time interval for the trend information. For example, week, month, year, etc.Data type: String |
| cards\_info.reportGroupConfigurations.data\_configurations.type | Type of report associated with the report group, such as donut or single\_core.Data type: String |
| cards\_info.reportGroupConfigurations.style\_configurations | Styles to use within the associated report group.Data type: Object |
| cards\_info.reportGroupConfigurations.style\_configurations.colorPalette | Colors used in the report.Data type: String |
| cards\_info.reportGroupConfigurations.style\_configurations.scoreColor | Color of the score value within the report.Data type: String |
| cards\_info.reportGroupConfigurations.style\_configurations.show\_zero | Flag that indicates whether data points equal to zero are shown in the report.Possible values: - true: Zero values are shown. - false: Zero values aren't shown. Data type: Boolean |
| cards\_info.reportGroupConfigurations.title | Title of the report group.Data type: String |
| cards\_info.reportGroupConfigurations.type | File type for which the information is being returned.Always sn\_customercentral\_report\_config. Data type: String |
| cards\_info.sourceTableName | Name of the table used for the associated list card.Data type: String |
| cards\_info.style\_configurations | Styles to use within the associated report.Data type: Object |
| cards\_info.style\_configurations.colorPalette | Colors used in the report.Data type: String |
| cards\_info.style\_configurations.dataLabelConfig | Configuration parameters that control how data labels appear in the report.Data type: Object |
| cards\_info.style\_configurations.dataLabelConfig.showTotal | Flag that indicates whether to display the total in the report.Possible values: - true: Show totals. - false: Don't show totals. Data type: Boolean |
| cards\_info.style\_configurations.height | Height of the associated report.Data type: String Unit: Pixels or "auto" |
| cards\_info.style\_configurations.hideRegister | Flag that indicates whether to display the register in the card.Possible values: - true: Show the register. - false: Don't show the register. Data type: Boolean |
| cards\_info.style\_configurations.registerConfig | Configuration values that control how the register appears in the report.Data type: Object |
| cards\_info.style\_configurations.registerConfig.hideBorder | Flag that indicates whether to hide the border around the register.Possible values: - true: Hide the register border. - false: Show the register border. Data type: Boolean |
| cards\_info.style\_configurations.registerConfig.showPercentages | Flag that indicates whether to show register percentages.Possible values: - true: Show register percentages. - false: Hide register percentages. Data type: Boolean |
| cards\_info.style\_configurations.registerPosition | Position of the register within a card.Data type: String |
| cards\_info.style\_configurations.scoreColor | Color of the score value within the report.Data type: String |
| cards\_info.style\_configurations.showDataLabels | Flag that indicates whether to show the data labels within the report.Possible values: - true: Show the data labels. - false: Hide the data labels. Data type: Boolean |
| cards\_info.style\_configurations.showTooltip | Flag that indicates whether to show tool tips within the report.Possible values: - true: Show tool tips. - false: Hide tool tips. Data type: Boolean |
| cards\_info.style\_configurations.show\_zero | Flag that indicates whether data points equal to zero are shown in the report.Possible values: - true: Zero values are shown. - false: Zero values aren't shown. Data type: Boolean |
| cards\_info.style\_configurations.width | Width of the associated report.Data type: String Unit: Pixels or "auto" |
| cards\_info.subheader\_fields | Details to show on the sub-header of the associated card.Data type: Object |
| cards\_info.subheader\_fields.avatar | File name of the avatar associated with the specifiedcontext_instance, such as the contact's avatar. Image omitted: cust-central_avatar.png Avatar placement</p> Data type: String |
| cards\_info.subheader\_fields.subheader\_tags | List of tags associated with the record sub-header, such as escalation tags. Image omitted: cust-central\_sub-header\_tags.png Data type: Array \(content varies\)Sub-header tag placement |
| cards\_info.subheader\_fields.sys\_id | Sys\_id of the associated customer.Data type: String Table: Users \[sys\_user\] |
| cards\_info.subheader\_fields.title | Title to display on the sub-header. Image omitted: cust-central\_sub-header-title.png Data type: StringSub-header title placement |
| cards\_info.title | Title on the card \(record\).Data type: String |
| cards\_info.type | File type for which the information is being returned.Possible values: - sn\_customercentral\_list\_config: List Configuration - sn\_customercentral\_record\_config: Record Configuration - sn\_customercentral\_report\_config: Report Configuration - sn\_customercentral\_report\_group\_config: Report Group Configuration Data type: String |
| cards\_info.viewName | Name of the view configured for the table specified in cards_info.sourceTableName.Data type: String |
| has\_more\_records | Flag that indicates whether there are more records to retrieve.Possible values: - true: More records to retrieve. - false: No more records. Data type: Boolean |
| layout | Number of columns per row. Each comma separated value defines the width of a column on the report display. For example "6,6" denotes two columns, each being six units wide, for a total of 12 units per row \(maximum\). A value of "3,6,3" denotes a row with three columns.Data type: String |
| status | HTTP status of the request.Data type: String |
cURL request
curl "https://instance.servicenow/api/sn_customercentral/cust_central/custinfo/csm_consumer/a0488cfbdb1b1200b6075200cf9619db/interaction" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"
{
"result": {
"layout": "6,6",
"cards_info": [
{
"title": "Consumer",
"type": "sn_customercentral_record_config",
"subheader_fields": {
"title": "Sam Collins",
"subheader_tags": [],
"avatar": "",
"sys_id": "64488cfbdb1b1200b6075200cf9619db"
},
"fields": [
{
"label": "Mobile phone",
"value": ""
},
{
"label": "Business phone",
"value": ""
},
{
"label": "Email",
"value": "sam.collins@mailinator.com"
},
{
"label": "Street",
"value": "144 2nd St"
},
{
"label": "City",
"value": "San Francisco"
},
{
"label": "State / Province",
"value": "CA"
}
]
},
{
"title": "High priority cases",
"type": "sn_customercentral_report_group_config",
"reportGroupConfigurations": [
{
"title": "Escalated",
"type": "sn_customercentral_report_config",
"data_configurations": {
"type": "single_score",
"source_type": "table",
"source_id": "sn_customerservice_case",
"group_by": "",
"trend_interval": "year",
"trend_field": "",
"stack_by_field": "",
"aggregate_function": "COUNT",
"aggregate_field": "",
"filter_query": "active=true^active_escalationISNOTEMPTY^EQ^consumer=a0488cfbdb1b1200b6075200cf9619db^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"decimal_precision": 2,
"number_of_groups": 0,
"show_other": true,
"sys_id": "c169a0f50f3b0010e6d4fd820b767e2e"
},
"style_configurations": {
"scoreColor": "#000000",
"show_zero": true
}
},
{
"title": "P1",
"type": "sn_customercentral_report_config",
"data_configurations": {
"type": "single_score",
"source_type": "table",
"source_id": "sn_customerservice_case",
"group_by": "",
"trend_interval": "year",
"trend_field": "",
"stack_by_field": "",
"aggregate_function": "COUNT",
"aggregate_field": "",
"filter_query": "active=true^priority=1^EQ^consumer=a0488cfbdb1b1200b6075200cf9619db^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"decimal_precision": 2,
"number_of_groups": 0,
"show_other": true,
"sys_id": "cce86cb50f3b0010e6d4fd820b767eba"
},
"style_configurations": {
"scoreColor": "#000000",
"show_zero": true
}
},
{
"title": "SLA breached",
"type": "sn_customercentral_report_config",
"data_configurations": {
"type": "single_score",
"source_type": "table",
"source_id": "task_sla",
"group_by": "",
"trend_interval": "year",
"trend_field": "",
"stack_by_field": "",
"aggregate_function": "COUNT",
"aggregate_field": "",
"filter_query": "task.active=true^task.sys_class_name=sn_customerservice_case^stage!=cancelled^task.closed_atISEMPTY^sla.type=SLA^has_breached=true^EQ^taskIN59b65dc4db952200d75270f5bf96193eccc8cf82db912200d75270f5bf9619de^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"decimal_precision": 2,
"number_of_groups": 0,
"show_other": true,
"sys_id": "e739a0f50f3b0010e6d4fd820b767e22"
},
"style_configurations": {
"scoreColor": "#000000",
"show_zero": true
}
}
]
},
{
"title": "Case overview",
"type": "sn_customercentral_report_config",
"data_configurations": {
"type": "donut",
"source_type": "table",
"source_id": "sn_customerservice_case",
"group_by": "state",
"trend_interval": "year",
"trend_field": "",
"stack_by_field": "",
"aggregate_function": "COUNT",
"aggregate_field": "",
"filter_query": "^consumer=a0488cfbdb1b1200b6075200cf9619db^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"decimal_precision": 2,
"number_of_groups": 0,
"show_other": true,
"sys_id": "d169216c0f770010e6d4fd820b767ea8"
},
"style_configurations": {
"width": "auto",
"height": "auto",
"colorPalette": [
"#278ecf",
"#4bd762",
"#ffca1f",
"#ff9416",
"#d42ae8"
],
"hideRegister": false,
"registerConfig": {
"hideBorder": true,
"showPercentages": false
},
"registerPosition": "right",
"showDataLabels": false,
"dataLabelConfig": {
"showTotal": false
},
"showTooltip": true
}
},
{
"title": "Recent cases",
"type": "sn_customercentral_list_config",
"listLimit": "3",
"viewName": "customer_central",
"encodedQuery": "active=true^consumer=a0488cfbdb1b1200b6075200cf9619db^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"sourceTableName": "sn_customerservice_case"
},
{
"title": "Recent chat interactions",
"type": "sn_customercentral_list_config",
"listLimit": "3",
"viewName": "customer_central",
"encodedQuery": "active=false^type=chat^consumer=a0488cfbdb1b1200b6075200cf9619db^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"sourceTableName": "interaction"
},
{
"title": "Recent phone calls",
"type": "sn_customercentral_list_config",
"listLimit": "3",
"viewName": "customer_central",
"encodedQuery": "active=false^type=phone^consumer=a0488cfbdb1b1200b6075200cf9619db^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"sourceTableName": "interaction"
},
{
"title": "Recent viewed articles",
"type": "sn_customercentral_list_config",
"listLimit": "3",
"viewName": "customer_central",
"encodedQuery": "user=64488cfbdb1b1200b6075200cf9619db^viewed=true^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"sourceTableName": "kb_use"
},
{
"title": "Contracts",
"type": "sn_customercentral_list_config",
"listLimit": "3",
"viewName": "customer_central",
"encodedQuery": "active=true^state=Active^consumer=a0488cfbdb1b1200b6075200cf9619db^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"sourceTableName": "ast_contract"
},
{
"title": "Entitlements",
"type": "sn_customercentral_list_config",
"listLimit": "3",
"viewName": "customer_central",
"encodedQuery": "active=true^end_date=NULL^ORend_date>=2020-05-07 07:00:00^consumer=a0488cfbdb1b1200b6075200cf9619db^ORDERBYDESCsys_created_on^sys_created_on>=2020-04-07 13:40:48",
"sourceTableName": "service_entitlement"
}
],
"has_more_records": false,
"status": "200"
}
}