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.

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

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
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 and target parameter define a unique customer information context. Data type: String Table: Customer Information Context [sn_customercentral_cust_info_config]

Table 2. Query parameters

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

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
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 6. Status 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 "data_configurations": { "aggregate_field": "String", "aggregate_function": "String", "chart_settings": "String" "decimal_precision": Number, "filter_query": "String", "group_by": "String", "number_of_groups": "String", "show_other": Boolean, "source_id": "String", "source_type": "String", "stack_by_field": "String", "sys_id": "String", "trend_field": "String", "trend_interval": "String", "type": "String" }
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: all: Show all groups. 0: Uses the value in the glide.ui.chart.generate_other system property. 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. Greater than 0: Number of groups to display. The groups that appear are the ones with the highest values for whatever is being tracked. 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: true: Include the "Other" group. false: Don't include the "Other" group. 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: source: Sys_id of the source table. table: Table name of the source table. 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 "fields": [ { "label": "String", "value": "String" } ]
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 "reportGroupConfigurations": [ { "data_configurations": {Object}, "style_configurations": {Object}, "title": "String", "type": "String" } ]
cards_info.reportGroupConfigurations.data_configurations	Configuration information. Data type: Object "data_configurations": { "aggregate_field": "String", "aggregate_function": "String", "chart_settings": "String" "decimal_precision": Number, "filter_query": "String", "group_by": "String", "number_of_groups": "String", "show_other": Boolean, "source_id": "String", "source_type": "String", "stack_by_field": "String", "sys_id": "String", "trend_field": "String", "trend_interval": "String", "type": "String" }
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: all: Show all groups. 0: Uses the value in the glide.ui.chart.generate_other system property. 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. Greater than 0: Number of groups to display. The groups that appear are the ones with the highest values for whatever is being tracked. 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: true: Include the "Other" group. false: Don't include the "Other" group. 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: source: Sys_id of the source table. table: Table name of the source table. 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 "style_configurations": { "colorPalette": "String", "scoreColor": "String", "show_zero": Boolean }
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 "style_configurations": { "colorPalette": "String", "dataLabelConfig": {Object}, "height": "String", "hideRegister": Boolean, "registerConfig": {Object}, "registerPosition": "String", "scoreColor": "String", "showDataLabels": Boolean, "showTooltip": Boolean, "show_zero": Boolean, "width": "String" }
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 "dataLabelConfig": [ { "showTotal": Boolean } ]
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 "registerConfig": { "hideBorder": Boolean, "showPercentages": Boolean }
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 "subheader_fields": { "avatar": "String", "subheader_tags": [Array], "sys_id": "String", "title": "String" }
cards_info.subheader_fields.avatar	File name of the avatar associated with the specified context_instance, such as the contact's avatar. Data type: String
cards_info.subheader_fields.subheader_tags	List of tags associated with the record sub-header, such as escalation tags. Data type: Array (content varies)
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. Data type: String
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": "[e-mail]"
          },
          {
            "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"
  }
}