JSON Data Retrieval API

  • Release version: Yokohama
  • Updated January 30, 2025
  • 3 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of JSON Data Retrieval API

    The JSON Data Retrieval API in ServiceNow Yokohama allows customers to query data from their instance using HTTPS GET requests. Depending on the presence of parameters, the API supports retrieving individual records or multiple records, with responses encapsulated in a JSON structure under arecordshash.

    Show full answer Show less

    Key Features

    • Data Retrieval Modes:
      • get: Retrieves a single record by specifying sysparmsysid.
      • getRecords: Retrieves multiple records matching an encoded query in sysparmquery.
      • getKeys: Retrieves sysids of multiple records based on a query.
    • Return Display Value for Reference Fields: By default, reference fields return sysid values. To get their display values instead, you can:
      • Set the system property glide.json.returndisplayValue to true for all JSON requests.
      • Add displayvalue=true to the request URL to return display values instead of sysids for reference fields.
      • Add displayvalue=all to get both sysid and display values, with display values prefixed by dv.
    • Retrieve Service Catalog Variables: Use displayvariables=true in the URL to include Service Catalog variables in the JSON response, supporting both single-row and multi-row variable sets with metadata and values.
    • Control Record Ordering: Use ORDERBY or ORDERBYDESC clauses in the encoded query to specify ascending or descending order of returned records.

    Practical Usage Tips

    • To fetch a specific record by sysid, use the get action or simply include sysparmsysid in the request.
    • To fetch multiple records filtered by conditions (e.g., active incidents in the hardware category), use getRecords with a properly encoded query in sysparmquery.
    • To include human-readable display values for reference fields, append displayvalue=true or configure the system property for all requests.
    • When working with Service Catalog items, include displayvariables=true to retrieve associated variables and their detailed structure.
    • Use encoded query ordering clauses to organize data output to suit reporting or integration needs.

    Expected Outcomes

    By leveraging this API, ServiceNow customers can programmatically access detailed records and their related reference data in JSON format, including Service Catalog variables if needed. This facilitates integrations, automation, and reporting by providing structured, customizable data retrieval directly via RESTful GET requests.

    Query for data by issuing an HTTPS GET request to the instance.

    By default, a GET request is interpreted as a get function if a sysparm_sys_id parameter is present. Otherwise, it is interpreted as a getRecords function. You can also specify a URL parameter sysparm_action=get. Query responses are always encapsulated by a records hash of records, where each individual record's values are themselves hashed by field name.

    Return Display Value for Reference Variables

    When you are getting a record from a get or getRecords function, all the fields associated with that record are returned. The fields are often reference fields that contain a sys_id for another table. The base system behavior is to return the sys_id value for those fields. To have the display value for the field returned, use one of these options:
    • Add the property glide.json.return_displayValue to the system properties, and every JSON request will return a display value for a reference field.
    • Add the parameter displayvalue=true to the JSON request URL and JSON requests with that parameter will return a display value instead of the sys_id for a reference field. The JSON URL would look like this:
      https://<instance name>.service-now.com/incident.do?JSON&sysparm_action=getRecords&sysparm_query=active=true^category=hardware&displayvalue=true
    • Add the parameter displayvalue=all to the JSON request URL and JSON requests with that parameter return a display value and the sys_id for a reference field. The response element name for the display value field will be prefixed with dv_, for example dv_caller_id.

    Get variables

    Use the displayvariables query parameter to return an array of variables associated with a Service Catalog item record. To get variables, add the parameter displayvariables=true to the JSON request URL. For example, here is a URL to retrieve a record in JSON format that includes Service Catalog variables:

    https://<your-instance>.servicenow.com/sc_req_item.do?JSONv2&sysparm_action=getRecords&sysparm_query=sys_id=5018da81742bd410f8771974894916fe&displayvariables=true
    Here is the example response that displays a multi-row variable set from the record:
    {
   "records":[
      {
         …
         "variables":[
            {
               "display_value":[
                  {
                     "quantity":"1",
                     "color":"Black",
                     "device_type":"Apple iPhone 8",
                     "storage":"64GB"
                  },
                  {
                     "quantity":"1",
                     "color":"Black",
                     "device_type":"Apple iPhone 8",
                     "storage":"64GB"
                  }
               ],
               "columns_meta":[
                  {
                     "name":"device_type",
                     "label":"Device Type",
                     "id":"da7d3f3241411300964ff05369414eca",
                     "type":5,
                     "order":"0"
                  },
                  {
                     "name":"storage",
                     "label":"Storage",
                     "id":"691e337241411300964ff05369414e31",
                     "type":5,
                     "order":"1"
                  },
                  {
                     "name":"color",
                     "label":"Color",
                     "id":"e89fb77241411300964ff05369414e74",
                     "type":5,
                     "order":"2"
                  },
                  {
                     "name":"quantity",
                     "label":"Quantity",
                     "id":"2d5f737241411300964ff05369414eaf",
                     "type":5,
                     "order":"3"
                  }
               ],
               "max_rows":50,
               "name":"mobile_devices_set",
               "id":"e84d3f3241411300964ff05369414e3e",
               "type":"one_to_many",
               "value":[
                  {
                     "quantity":"1",
                     "color":"black",
                     "device_type":"iphone8",
                     "storage":"64GB"
                  },
                  {
                     "quantity":"1",
                     "color":"black",
                     "device_type":"iphone8",
                     "storage":"64GB"
                  }
               ],
               "row_count":2
            },
            {
               "question_text":"Department",
               "name":"department",
               "type":8,
               "value":"Development",
               "order":100
            },
            {
               "question_text":"Who is this request for?",
               "name":"requested_for",
               "type":8,
               "value":"System Administrator",
               "order":100
            },
            {
               "question_text":"When do you need this?",
               "name":"needed_by",
               "type":5,
               "value":"Today",
               "order":200
            },
            {
               "question_text":"Business Justification",
               "name":"business_justification",
               "type":2,
               "value":"Example justification",
               "order":200
            }
         ],
       …
      }
   ]
}

    The keys in the response are defined as follows:

    Key Description
    display_value Multi-row variable set question display value. Only returned with multi-row variable sets.
    columns_meta Array of multi-row variable set metadata, such as the sys_id and name of the field. Only returned when the variable contains multiple fields.
    max_rows Maximum rows allowed in the multi-row variable set. Only returned with multi-row variable sets.
    name Question name.
    id Sys_id of the multi-row variable set. Only returned with multi-row variable sets.
    type Type of question.
    value Question value.
    row_count Current number of rows in the multi-row variable set. Only returned with multi-row variable sets.
    question_text Question label. Only returned with single-row variable sets.
    order Order of the question.

    Control the order of records

    You can control the order that records appear in the JSON response. To set an order, use the ORDERBY or ORDERBYDESC clauses in the URL encoded query. For example,

    sysparm_query=active=true^ORDERBYnumber^ORDERBYDESCcategory

    filters all active records and orders the results in ascending order by number first, and then in descending order by category. For more information, see Encoded query strings.

    getKeys

    Get the sys_id of multiple records by specifying an encoded query string in the sysparm_query parameter.
    https://<instance name>.service-now.com/incident.do?JSONv2&sysparm_action=getKeys&sysparm_query=active=true^category=hardware

    get

    Get a record directly by specifying the sys_id in a sysparm_sys_id parameter.
    https://<instance name>.service-now.com/incident.do?JSONv2&sysparm_sys_id=9d385017c611228701d22104cc95c371
    Optionally, you may also specify the sysparm_action parameter:
    https://<instance name>.service-now.com/incident.do?JSONv2&sysparm_action=get&sysparm_sys_id=9d385017c611228701d22104cc95c371

    getRecords

    Get all records by specifying an encoded query string in the sysparm_query parameter.
    https://<instance name>.service-now.com/incident.do?JSONv2&sysparm_action=getRecords&sysparm_query=active=true^category=hardware