Dot-walking in REST API requests

You can use dot-walking when specifying the sysparm_query or sysparm_fields parameters in requests to REST APIs that support those parameters.

Note: The Import Set API does not support dot-walking.

Dot-walking in sysparm_query

You can filter queries using related record values by dot-walking in the sysparm_query parameter. For example, you can retrieve all incident records where the incident Company has a specific Stock symbol value.

https://<instance>.service-now.com/api/now/table/incident?sysparm_query=company.stock_symbol=NYX

Dot-walking in sysparm_fields

You can view field values from multiple tables by dot-walking in the sysparm_fields parameter. For example, you can retrieve theName, Sys_id, and Department of each user that has certain roles, as well as the role Name.

The request runs on the User Roles [sys_user_has_role] table which defines a many-to-many relationship between users and roles. The response includes field values from the User [sys_user] and Roles [sys_user_role] tables.

https://<instance>.service-now.com/api/now/table/sys_user_has_role?sysparm_fields=role%2Crole.name%2Cuser%2Cuser.name%2Cuser.sys_id%2Cuser.department&sysparm_query=role%3D3d43716d0f6002003a2d47bce1050e0d%5EORrole%3Dac73b52d0f6002003a2d47bce1050eec&sysparm_display_value=true

{
    "result": [
        {
            "user.name": "Fred Johnson",
            "user.sys_id": "f5a3716d0f6002003a2d47bce1050ed4",
            "role.name": "support",
            "user.department": {
                "display_value": "Accounting",
                "link": "https://<instance>.service-now.com/api/now/table/cmn_department/5b3b13530f58c2003a2d47bce1050e96"
            },
            "role": {
                "display_value": "support",
                "link": "https://<instance>.service-now.com/api/now/table/sys_user_role/3d43716d0f6002003a2d47bce1050e0d"
            },
            "user": {
                "display_value": "Fred Johnson",
                "link": "https://<instance>.service-now.com/api/now/table/sys_user/f5a3716d0f6002003a2d47bce1050ed4"
            }
        },
        {
            "user.name": "Fred Johnson",
            "user.sys_id": "f5a3716d0f6002003a2d47bce1050ed4",
            "role.name": "asset_mgmt",
            "user.department": {
                "display_value": "Accounting",
                "link": "https://<instance>.service-now.com/api/now/table/cmn_department/5b3b13530f58c2003a2d47bce1050e96"
            },
            "role": {
                "display_value": "asset_mgmt",
                "link": "https://<instance>.service-now.com/api/now/table/sys_user_role/ac73b52d0f6002003a2d47bce1050eec"
            },
            "user": {
                "display_value": "Fred Johnson",
                "link": "https://<instance>.service-now.com/api/now/table/sys_user/f5a3716d0f6002003a2d47bce1050ed4"
            }
        }
    ]
}