---
sourceDocument: Australia Platform security
sourceDocumentLink: https://www.servicenow.com/docs/r/australia/platform-security

 Release :

    - australia

ft:locale :

    - en-US

ft:publication_title :

    - Australia Platform security

ft:clusterId :

    - psec

bundleId :

    - psec

workflow :

    - Platform


---

# JSON APIs

# JSON APIs {#ariaid-title1}

Release version: Australia  
Updated November 5, 2026  
![](https://www.servicenow.com/docs/portal-asset/ico-clock) 3 minutes to read
Summarize  
![AI sparkle icon](https://servicenow.com/docs/portal-asset/ai-sparkle-icon) 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 APIs

JSON APIs in ServiceNow allow you to process JSON payloads securely by iterating over JSON elements and selectively encrypting data fields based on encryption rules.
These APIs are accessed via thegetAsJsonContent()method on the request object or a ParameterValue property, returning iterable JSON objects that facilitate mapping JSON data to ServiceNow table fields with encryption applied as configured.
Show full answer Show less  

## Key Features

* **JSON Iteration:** Use `getIterator()` or `iterator()` on `JsonNode` objects to traverse JSON elements.
* **Conditional Encryption:** Call `valueFor(tableName, fieldName)` on JSON elements to map them to specific table fields, prompting the proxy to check and apply encryption if configured.
* **Dynamic Field Mapping:** Rules can dynamically determine table and field names from request parameters, enabling flexible encryption logic for unknown or variable JSON structures.
* **Encoded Query Support:** The `encodedQueryFor(tableName)` method encrypts values within query nodes to secure query parameters.
* **XPath Support:** Use XPath expressions in `getIterator()` to target specific JSON nodes for processing.

## Practical Examples

* **Known Table-Field Mapping:** Iterate over specific JSON nodes (e.g., descriptions in records) and encrypt values mapped to a known field like `incident.shortdescription`.
* **Unknown Table-Field Mapping:** Iterate over records with fields matching table columns dynamically determined from request parameters, encrypting fields as configured while handling exceptions (e.g., mapping `description` to `shortdescription`).
* **Query Encryption:** When processing JSON that includes query nodes, apply encryption to sensitive query parts using `encodedQueryFor()`.

## Key Outcomes

By leveraging JSON APIs and these encryption rules, ServiceNow customers can securely ingest JSON data by:

* Ensuring sensitive fields are encrypted according to defined configurations when inserting or updating records.
* Handling both static and dynamic JSON schemas flexibly without compromising security.
* Encrypting sensitive query parameters to protect data in transit and storage.

This approach helps maintain data confidentiality and compliance while enabling automated and scalable processing of JSON payloads within ServiceNow workflows.  
JSON APIs can be used after calling getAsJsonContent() on either
the request object or a ParameterValue property.
When using JSON APIs to write your encryption rule, you can follow a general format:

1. Call getAsJsonContent() on the request object. This returns an iterable object of the JsonNode underlying class.
2. Call iterator() or getIterator(String xPath) on the JsonNode object. This returns a JsonNodeIterator object that can be used to iterate over nodes in the JSON object.
3. Call the hasNext() method on the JsonNodeIterator object to determine whether another element is available.
4. Call next() on the JsonNodeIterator object to return the next JSON element. You cannot call next() without first calling hasNext().
5. Call valueFor(String tableName, String fieldName) on the JSON element. This method tells the proxy that the value for this element maps to the specified field in the specified table. The proxy then checks whether the field must be encrypted.  
   Note:  
   To determine if you want to call valueFor(String tableName, String fieldName) on a JSON element, you can use the getName() method to return the name of the element.
{#json-overview__ol_qfz_kmt_dz}

## Mapping to a known table-field on the instance {#json-overview__section_hhq_fsd_yz}

In this example, the JSON payload is processed on the instance to insert records in
the incident table. The description field populates short_description on the
incident.  

    {
        data: {
            records: [
                {
                    "name": "Test Record 1",
                    "description": "Test Record 1 Description",
                    "tag": "security"
                }, 
                {
                    "name": "Test Record 1",
                    "description": "Test Record 1 Description",
                    "tag": "security"
                }],
            "query": "assigned_to=3D4860165813e63a00d00abd322244b092^category=vulnerability"
        },
        "source": "10.11.13.14"
    }

The following rule can apply:  

    function sampleJsonAction1() {
        var jsonContent = request.getAsJsonContent();
        // This loop iterates over all description elements in the records array
        var jsonNodeIterator = jsonContent.getIterator('/data/records/description');    
        while (jsonNodeIterator.hasNext()) {
            var jsonNode = jsonNodeIterator.next();
            jsonNode.valueFor('incident', 'short_decription');
        }
    }

This action iterates through the description nodes and asks
the proxy server to encrypt the values and insert them into
incident.short_description on the instance.  
Note:  
This rule finds all description nodes within the JSON payload. If there is only one occurrence of a node to encrypt, the rule still uses the xPath and iterator structure. However, it iterates only once in the loop.

## Mapping to an unknown table-field on the instance {#json-overview__json-dynamic}

In this example, the rule iterates over records, but is not
sure what nodes to expect. The only known is that for each object within
records, the nodes match the names of the columns
specified in the table URL parameter.

The rule also specifies that, if the table is incident, then the data in the
description node should be encrypted and stored in the
short_description field on the instance.  

    function sampleJsonAction2() {
        var jsonContent = request.getAsJsonContent();
        var tableName = request.urlParam.table;
        // This first iterator will iterate over all record elements
        var jsonNodeIterator = jsonContent.getIterator('data/records');
        while (jsonNodeIterator.hasNext()) {
                encryptFieldsInRecord(jsonNodeIterator.next());
        }
    }
    function encryptFieldsInRecord(jsonNode) {
        //this time we want to iterate over all nodes
        var fieldIterator = jsonNode.iterator();
        while (fieldIterator.hasNext()) {
                var field = fieldIterator.next();
                var fieldname = childElement.getName();
                if (fieldName == 'description') {
                    field.valueFor(tableName, 'short_description');
                } else {
                    field.valueFor(tableName, fieldName);
                }
        }
    }

In the encryptFieldsInRecord() function, the
valueFor() method is called on a table and a field that are
dynamically assigned based on the request. Even though the table and field names can
change, the rule asks the proxy to check whether the field in the table must be
encrypted based on the encryption configurations defined.

If the field is not configured for encryption, or if the node name does not match a
field in the table, the proxy skips that node. If the node name matches a field
marked for encryption, then the proxy encrypts the value.

## Using an encoded query {#json-overview__section_sbq_msd_yz}

    function sampleJsonAction3() {
        var jsonContent = request.getAsJsonContent();
        var tableName = request.urlParam.table;
        // This first iterator will iterate over all record elements
        var jsonNodeIterator = jsonContent.getIterator('data');
        while (jsonNodeIterator.hasNext()) {
            var jsonNode = jsonNodeIterator.next();
            if (jsonNode.getName() == 'records')
                encryptRecors(jsonNodeIterator.next());
            else if (jsonNode.getName() == 'query')
                jsonNode.encodedQueryFor(tableName);
        }
    }
    function encryptRecords(jsonNode) {
        //we iterate over all fields in the node
        var recordIterator = jsonNode.iterator();
        while (recordIterator.hasNext()) {
            encryptFieldsInRecord(recordIterator.next());
        }
    }
    function encryptFieldsInRecord(jsonNode) {
        //this time we want to iterate over all nodes
        var fieldIterator = jsonNode.iterator();
        while (fieldIterator.hasNext()) {
                var field = fieldIterator.next();
                var fieldname = childElement.getName();
                field.valueFor(tableName, fieldName);
        }
    }

In this example, the rule iterates over data. As it finds
records, it performs the same logic as in the second
example, iterating over fields in each node. When it finds the
query node, it calls encodedQueryFor()
to encrypt values that should be encrypted in the query.
* **[JsonNode](https://www.servicenow.com/docs/7L8avaXnbeMJAPyUyHzKAA#c_JsonNodeAPI)**   
  A global object that provides methods to iterate over the JSON content.
* **[JsonNodeIterator](https://www.servicenow.com/docs/UAucsLyI3idmRuRAFPG0jQ#c_JsonNodeIteratorAPI)**   
  You get a JsonNodeIterator object by calling the getIterator() or iterator() methods of the JsonNode class.