WSD Unified Search API

concept brazil Updated Sep 10, 2026 7 min read wsd_unified-search-api.md
Raw file servicenow.com

The WSD Unified Search API provides an endpoint to search across workplace users and locations.

The WSD Unified Search API runs in the sn_wsd_core namespace and powers the search/type ahead experience in the Workplace Service Delivery (WSD) portal, returning matching users, spaces, floors, buildings, campuses, and neighborhoods in a single response.

Requirements

The WSD Unified Search API requires:

  • The calling user have the sn_wsd_core.workplace_user role.
  • The Workplace Service Delivery Core (com.sn_wsd_core) plugin be active.
  • At least one building and floor be configured in the workplace location hierarchy.

Parent Topic:REST API reference

WSD Unified Search - POST /api/sn_wsd_core/wsd_unified_search/users_and_locations

Searches for users and workplace locations matching the provided search term. Returns a combined list of matching results with pagination support.

URL format

Versioned URL: /api/sn_wsd_core/{api_version}/wsd_unified_search/users_and_locations

Default URL: /api/sn_wsd_core/wsd_unified_search/users_and_locations

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
|Name|Description| |----|-----------| |None| |

Name

Description

search_term

Search query used to find matching users and workplace locations. Accepts a comma-separated list of values to search for multiple terms simultaneously. For example, "Conference, Desk" returns results matching either term. Empty segments are ignored.Data type: String

Default value: Empty string (returns all results)

show_location

Flag that indicates whether to include the user's current location in the result label.Possible values:

  • true: Display the user's current location in the result label.
  • false: Don't display the user's current location in the result label.

Data type: Boolean

Default: true

show_loggedin_user

Flag that indicates whether to display the authenticated user as the first result when no search term is provided. Only applies to desktop clients at offset 0. Possible values:

  • true: Show the authenticated user as the first result.
  • false: Don't show the authenticated user as the first result.

Data type: Boolean

Default: true

include_user_email

Flag that indicates whether to include user email addresses in result labels and allow searching by email address. Possible values:

  • true: Include email in result labels and enable email search.
  • false: Don't include email in result labels or enable email search

Data type: Boolean

Default: false

filterConfig

Object containing one or more table names as keys to restrict results to specific entity types. When empty, both users and locations are returned.Valid fields (table names):

  • sys_user
  • sn_wsd_core_workplace_location
  • sn_wsd_core_region
  • sn_wsd_core_site
  • sn_wsd_core_campus
  • sn_wsd_core_building
  • sn_wsd_core_floor
  • sn_wsd_core_area
  • sn_wsd_core_space
  • sn_wsd_core_room
  • sn_wsd_core_neighborhood

Data type: Object

JavaScript
"filterConfig": {  "<table_name>": Boolean}

Default: {} (no filter applied)

filterConfig.<table_name>

Flag that indicates whether to include results from the specified table. Set to true to include results from that entity type.Valid values:

  • true: Include results from that entity type.
  • false: Don't include results from that entity type.

Data type: Boolean

options

Object containing additional configuration for search behavior. Data type: Object

JavaScript
"options": {   "search_in_parent": Boolean,  "cache": Boolean,  "rsvModule": {Object}}

options.search_in_parent

Flag that indicates whether to include results from parent location records when filtering by a child entity.Possible values:

  • true: Include parent location results.
  • false: Don't include parent location results.

Data type: Boolean

options.cache

Flag that indicates whether to use cached search results.Possible values:

  • true: Use cached results where available.
  • false: Always fetch fresh results

Data type: Boolean

options.rsvModule

Object containing reservation module configuration for filtering results by reservable module context.Data type: Object

Text
"rsvModule": {   "value": "String"}

options.rsvModule.value

Sys_id of the reservable module to use for filtering available spaces. Table: Reservable Module [sn_wsd_rsv_reservable_module]

Data type: String

options.rsvModule.enable_restricted_neighborhood_rules

Flag that indicates whether to apply restricted neighborhood rules when filtering results by reservation module.Possible values:

  • true: Apply restricted neighborhood rules.
  • false: Don't apply restricted neighborhood rules.

Data type: Boolean

sysparam_offset

Pagination offset. Number of records to skip before returning results. Use with sysparam_limit for pagination. Minimum value: 0

Data type: Number

Default value: 0

sysparam_limit

Maximum number of records to return per request. Use with sysparam_offset for pagination.Minimum value: 1

Data type: Number

Default value: 10
### 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, application/xml, text/xml.
Content-Type Data format of the request body: application/json.
Authorization Authentication credentials. Supports Basic authentication or session-based authentication.
Header Description
Content-Type Data format of the response body: application/json.

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. Invalid request body format.
500 Internal server error. An unexpected error occurred while processing the request.

Response body parameters (JSON or XML)

Name

Description

result

Object containing results of the request.Data type: Object

JavaScript
"result": {  "result": [Array],  "more": Boolean,  "isMobile": Boolean}

result.isMobile

Flag that indicates whether the request was detected as originating from a mobile client.Possible values:

  • true: Request originated from a mobile client.
  • false: Request originated from a desktop client.

Data type: Boolean

result.more

Flag that indicates whether additional results are available beyond the current page.Possible values:

  • true: More results are available. Increment sysparam_offset by sysparam_limit to retrieve the next page.
  • false: No more results are available.

Data type: Boolean

result.result

Array of matching user and location objects. Each object contains common fields shared across all result types, as well as type-specific fields that are only present for user results.Data type: Array of Objects

JavaScript
"result": [  {    "displayValue": "String",    "value": "String",    "table": "String",    "label": "String",    "selectedTreeBranch": "String",    "timezone": {Object},    "wsdSource": "String",    "externalId": "String",    "floorId": "String",    "isReservable": Boolean  }]

result.result.displayValue

Display name of the result. For example, Conference Room A - Floor 1 for a space or Jane Doe for a user.Data type: String

result.result.externalId

Identifier of the result record in an external source system, when applicable.Data type: String

result.result.floorId

Sys_id of the floor on which the result location resides. Present for location results only.Table: Workplace Floor [sn_wsd_core_floor]

Data type: String

result.result.isReservable

Flag that indicates whether the result location can be reserved.Possible values:

  • true: The location is reservable.
  • false: The location isn't reservable.

Data type: Boolean

result.result.label

Secondary display string providing additional context for the result. For example, the location hierarchy for a space, or the department and title for a user.Data type: String

result.result.selectedTreeBranch

Sys_id of the parent location record in the workplace hierarchy associated with this result. Used to pre-select the location tree in the UI.Data type: String

result.result.table

Table name from which the result originates. For example, sn_wsd_core_space or sys_user.Data type: String

result.result.timezone

Time zone associated with the result location. Present for location results.Data type: Object

Text
"timezone": {  "displayValue": "String",  "value": "String"}

result.result.timezone.displayValue

Human-readable time zone name. For example, Eastern Standard Time.Data type: String

result.result.timezone.value

IANA time zone identifier for the result location. For example, America/New_York.Data type: String

result.result.userDetails

Object containing additional details about a user result. Present for user results only (User [sys_user] table).Data type: Object

JSON
"userDetails": {  "userID": "String",  "name": "String",  "department": "String",  "avatar": "String",  "initials": "String"}

result.result.userDetails.avatar

Relative URL path to the user's profile avatar image.Data type: String

result.result.userDetails.department

Name of the department the user belongs to.Data type: String

result.result.userDetails.initials

Initials derived from the user's display name, used as a fallback when no avatar is available. For example, JD for Jane Doe.Data type: String

result.result.userDetails.name

Full display name of the user. For example, Jane Doe.Data type: String

result.result.userDetails.userID

Sys_id of the user record.Table: User [sys_user]

Data type: String.

result.result.value

Sys_id of the result record.Data type: String

result.result.wsdSource

Source system identifier for the result. Used when the location originates from an external integration.Data type: String
### cURL request

The following example searches for spaces matching "Conference" or "Desk" within a specific building, returning up to 10 results.

Shell
curl "https://<instance>.service-now.com/api/sn_wsd_core/wsd_unified_search/users_and_locations" \ --request POST \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --user "username:password" \--data '{  "search_term": "Conference, Desk",  "show_location": true,  "show_loggedin_user": true,  "include_user_email": false,  "filterConfig": {},  "options": {       "search_in_parent": false,       "cache": true              },       "sysparam_offset": 0,       "sysparam_limit": 10   }}'

Response body.

JSON
{  "result": {    "result": [      {        "displayValue": "Conference Room A - Floor 1",        "value": "space_123",        "table": "sn_wsd_core_space",        "label": "Floor 1, Building A, Main Campus",        "selectedTreeBranch": "building_456",        "timezone": {          "value": "America/New_York",          "displayValue": "Eastern Standard Time"        },        "wsdSource": "",        "externalId": "",        "floorId": "floor_789",        "isReservable": true      },      {        "displayValue": "Jane Doe",        "value": "user_789",        "table": "sys_user",        "label": "Senior Engineer, Engineering",        "selectedTreeBranch": "building_456",        "userDetails": {          "userID": "user_789",          "name": "Jane Doe",          "department": "Engineering",          "avatar": "/avatar/user_789",          "initials": "JD"        }      }    ],    "more": true,    "isMobile": false  }}
Keywords Workplace Service Delivery CoreWSD
Search documentation
Search document titles and file paths on the brazil branch