WSD Unified Search API

  • Release version: Australia
  • Updated April 28, 2026
  • 11 minutes to read

    • 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.

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

    Searches for users and workplace locations (case-insensitive) 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

    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
    Table 2. Query parameters
    Name Description
    None
    Note:
    All searches are case-insensitive.
    Table 3. Request body parameters (XML or JSON)
    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.

    When a search_term is provided, this flag has no effect. The authenticated user is returned only if they match the search criteria.

    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 Table-specific encoded queries. Keys are table names. Values are encoded query strings.
    Note:
    filterConfig filters by entity type only. It doesn't support filtering results to a specific record or location hierarchy. To narrow results by location, use search_term in combination with options.rsvModule.
    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

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

    Default: {} (no filter applied, searches all tables)
    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

    "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

    "rsvModule": { 
  "value": "String",
  "enable_restricted_neighborhood_rules": Boolean
}
    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.

    Table 4. Request 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.
    Table 5. Response headers
    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.

    Table 6. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    400 Bad Request. Invalid request body format.
    401 Authentication failed.
    403 User lacks required ACL permissions.
    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

    "result": {
  "result": [Array],
  "more": Boolean,
  "isMobile": Boolean
}
    result.isMobile Flag that indicates whether the request was detected as originating from a mobile client. This value can be used to mirror the same client-type logic in your own UI, for example to replicate the show_loggedin_user behavior.
    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

    "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

    "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

    "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.

    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": {
  "sn_wsd_core_building": true
                  },
  "options": {
       "search_in_parent": false,
       "cache": true
              },
       "sysparam_offset": 0,
       "sysparam_limit": 10 
  }
}'

    Response body.

    {
  "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
  }
}

    cURL request

    The following are examples of different search criteria.

    Search all locations and users:

    { 
  "search_term": "engineering", 
  "filterConfig": {}, 
  "sysparm_offset": 0, 
  "sysparm_limit": 20
}

    Search only reservable spaces:

    {
  "search_term": "workspace",
  "filterConfig": {
    "sn_wsd_core_workplace_location": "is_reservable=true^sys_class_name=sn_wsd_core_space"
  },
  "sysparm_offset": 0,
  "sysparm_limit": 10
}

    Search only active users in IT department:

    {
  "search_term": "smith",
  "include_user_email": true,
  "filterConfig": {
    "sys_user": "department.name=IT Department"
  },
  "sysparm_offset": 0,
  "sysparm_limit": 10
}

    Search neighborhoods with restricted access validation:

    {
  "search_term": "team",
  "filterConfig": {
    "sn_wsd_core_neighborhood": ""
  },
  "options": {
    "sn_wsd_core_neighborhood": {
      "validateAccess": true
    },
    "rsvModule": {
      "value": "module_sys_id_here"
    }
  },
  "sysparm_offset": 0,
  "sysparm_limit": 10
}

    WSD Unified Search - GET /api/sn_wsd_core/wsd_unified_search/current_location

    Retrieve the current location of a specific user based on their active reservations, workplace profile, or neighborhood assignment. Returns the most relevant public location first, falling back to private locations if no public location is found.

    URL format

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

    Default URL: /api/sn_wsd_core/wsd_unified_search/current_location

    Supported request parameters

    Table 7. 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
    Table 8. Query parameters
    Name Description
    userSysId Required. Sys_id of the user whose current location to retrieve.

    Table: User [sys_user]

    Data type: String
    useNeighborhoods Flag that indicates whether to include a neighborhood-based location from the user's workplace profile record when no reservation or direct profile location is found.

    Table: Workplace Profile [sn_wsd_core_workplace_profile]

    Valid values:
    • true: Include neighborhood-based location as a fallback.
    • false: Don't include neighborhood-based location.

    Data type: Boolean

    Default: false
    Table 9. 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 10. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Authorization Authentication credentials. Supports Basic authentication or session-based authentication.
    Table 11. Response headers
    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.

    Table 12. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    400Bad Request. The userSysId parameter is missing or invalid.
    500 Internal server error. An unexpected error occurred while processing the request.

    Response body parameters (JSON or XML)

    Returns a single location object when a current location is found, or an empty object {} when no location is found.
    Name Description
    isPrivate Flag that indicates whether the returned location is private. A location is considered private when it's marked as private in the workplace profile or when it's associated with a reservation that has a private or sensitive status.
    Valid values:
    • true: Location is private or the reservation has private/sensitive status.
    • false: Location is public.

    Data type: Boolean
    displayValue Display name of the result location. For example, Building A - Floor 2 - Workspace 201.

    Data type: String
    value Sys_id of the result location record.

    Data type: String.
    table Name of the ServiceNow table from which the location originates For example, sn_wsd_core_space.

    Data type: String
    label Secondary display string providing location hierarchy context. For example, Floor 2, Building A.

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

    Data type: String
    timezone Time zone associated with the result location.

    Data type: Object

    "timezone": {
  "value": "String",
  "displayValue": "String"
}
    timezone.value IANA time zone identifier for the result location. For example, America/New_York.

    Data type: String
    timezone.displayValue Human-readable timezone name. For example, Eastern Standard Time.

    Data type: String
    wsdSource Source system identifier for the location. Used when the location originates from an external integration.

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

    Data type: String
    floorId Sys_id of the floor on which the location resides.

    Table: Workplace Floor [sn_wsd_core_floor] table

    Data type: String
    isReservable Flag that indicates whether the location can be reserved.
    Possible values:
    • true: The location is reservable.
    • false: The location isn't reservable.

    Data type: Boolean

    cURL request

    The following example retrieves the current location of a specific user, including neighborhood-based location as a fallback.

    curl "https://<instance>.service-now.com/api/sn_wsd_core/wsd_unified_search/current_location
  ?userSysId=abc123def456&useNeighborhoods=true" \
  --request GET \
  --header "Accept: application/json" \
  --user "username:password"

    Reponse body when location is found.

    {
  "result": {
    "displayValue": "Building A - Floor 2 - Workspace 201",
    "value": "abc123def456",
    "table": "sn_wsd_core_space",
    "label": "Floor 2, Building A",
    "selectedTreeBranch": "building789xyz",
    "timezone": {
      "value": "America/New_York",
      "displayValue": "Eastern Standard Time"
    },
    "wsdSource": "manual",
    "externalId": "EXT-WS-201",
    "floorId": "floor123",
    "isReservable": true,
    "isPrivate": false
  }
}

    Response body when location isn't found (empty object {}).

    {
  "result": {}
}