WSD Reservation Invitees API

  • Release version: Xanadu
  • Updated August 1, 2024
  • 9 minutes to read

    • The Workplace Service Delivery (WSD) Reservation Invitees API provides endpoints to add invitees to reservations, fetch invitees of a reservation, and reassign invitees of a reservation.

    To access this API, the caller must have the sn_wsd_core.workplace_user role and the Workplace Reservation Management (sn_wsd_rsv) plugin must be activated.

    This API runs in the sn_wsd_rsv namespace.

    For additional information on Workplace Reservation Management, see Workplace Reservation Management.

    WSD Reservation Invitees - GET /api/sn_wsd_rsv/wsd_reservation_invitees/reservation/{sys_id}

    Retrieves details about the invitees associated with a specified reservation.

    URL format

    Versioned URL: /api/sn_wsd_rsv/{api_version}/wsd_reservation_invitees/reservation/{sys_id}

    Default URL: /api/sn_wsd_rsv/reservation/{sys_id}

    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
    sys_id Sys_id of the reservation for which to return the invitee details.

    Data type: String
    Table 2. Query parameters
    Name Description
    None
    Table 3. Request body parameters
    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 4. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 5. Response headers
    Header Description
    None

    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.
    401 Unauthorized. The user credentials are incorrect or have not been passed.
    404 Not found. The requested item wasn't found.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters

    Name Description
    result Return results for the invitees associated with the specified reservation.

    Data type: Object

    {
  "result": {
    "invitees": [Array],
    "reservationId": "String",
    "reservationSubType": "String",
    "success": Boolean
  }
}
    result.invitees Details about the invitees associated with the reservation.

    Data type: Array of Objects

    "invitees": [
  {
    "email": "String",
    "firstName": "String",
    "inviteeId": "String",
    "inviteState": {Object},
    "inviteeType": "String",
    "isVIP": Boolean,
    "isWifiRequired": Boolean,
    "isParkingRequired": Boolean,
    "lastName": "String",
    "licensePlate": "String",
    "location": {Object},
    "name": "String",
    "org": "String",
    "parkingType": "String",
    "phoneNumber": "String",
    "privateNotes": "String",
    "reservationId": "String",
    "reservationInviteeId": "String",
    "title": "String",
    "visitorType": "String"
  }
]
    result.invitees.email
    Email address of the invitee.

    Data type: String
    result.invitees.firstName First name of the invitee.

    Data type: String
    result.invitees.inviteeId
    Sys_id of the employee's user record. Located in the User [sys_user] table.

    Data type: String
    result.invitees.inviteState Details about the current state of the invitee for the reservation.

    Data type: Object

    "inviteState": {
  "displayValue": "String",
  "value": "String"
}
    result.invitees.inviteState.displayValue Display value for the invitee state, such as New or Removed.

    Data type: String
    result.invitees.inviteState.value Internal value for the invitee state.

    Data type: String
    result.invitees.inviteeType
    Type of invitee.
    Valid values: (case-sensitive)
    • employee
    • visitor

    Data type: String
    result.invitees.isVIP Flag that indicates whether the invitee is classified as a VIP.
    Valid values:
    • true: Invitee is a VIP.
    • false: Invitee isn't a VIP.

    Data type: Boolean
    result.invitees.isWifiRequired Flag that indicates whether the WIFI password should be provided to the visitor upon entry.
    Valid values:
    • true: Provide WIFI password.
    • false: Don't provide WIFI password.

    Data type: Boolean
    result.invitees.isParkingRequired Flag that indicates whether the invitee requires parking.
    Valid values:
    • true: Parking needed.
    • false: Parking is not needed.

    Data type: Boolean
    result.invitees.lastName Last name of the invitee.

    Data type: String
    result.invitees.licensePlate License plate of the invitee.

    Data type: String
    result.invitees.location Details about the workplace location of the invitee.

    Data type: Object

     "location": {
  "displayName": "String",
  "sysId": "String"
}
    result.invitees.location.displayName Display name of the invitee's workplace location, such as Dublin.

    Data type: String
    result.invitees.location.sysId Sys_id of the invitee workplace location. Located in the Workplace Location [sn_wsd_core_worplace_location] table.

    Data type: String
    result.invitees.name Name of the invitee.

    Data type: String
    result.invitees.org Organization of the invitee.

    Data type: String
    result.invitees.parkingType Type of parking required for invitee.
    Valid values: (case-sensitive)
    • ev_parking
    • none
    • normal_parking
    • van_accessible_parking

    Data type: String
    result.invitees.phoneNumber Phone number of the invitee.

    Data type: String
    result.invitees.privateNotes Any additional notes provided by the invitee.

    Data type: String
    result.invitees.reservationId Sys_id of the reservation to which the invitee is associated. Located in the Workplace Reservation [sn_wsd_rsv_reservation] table.

    Data type: String
    result.invitees.reservationInviteeId

    Sys_id of the reservation invitee for visitor. Located in the Reservation Invitee [sn_wsd_rsv_m2m_reservation_invitee] table.

    Data type: String
    result.invitees.title Title of the invitee.

    Data type: String
    result.invitees.visitorType Type of invitee.
    Valid values: (case-sensitive)
    • client
    • contractor
    • friend_family
    • others

    Data type: String
    result.reservationId Sys_id of the reservation to which the invitee is associated. Located in the Workplace Reservation [sn_wsd_rsv_reservation] table.

    Data type: String
    result.reservationSubType Sub-type of the reservation record, such as single or multi-child.

    Data type: String
    result.success Flag that indicates whether the call was successful.
    Possible values:
    • true: Endpoint call was successful.
    • false: Endpoint call failed.

    Data type: Boolean

    cURL request

    The following code example shows how to retrieve the invitees for a reservation.

    curl 
"http://instance.servicenow.com/api/sn_wsd_rsv/wsd_reservation_invitees/reservation/17979dc9536b01103cf7ddeeff7b12b3" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

    Return results:

    {
  "result": {
    "success": true,
    "reservationId": "17979dc9536b01103cf7ddeeff7b12b3",
    "reservationSubType": "single",
    "invitees": [
      {
        "reservationId": "17979dc9536b01103cf7ddeeff7b12b3",
        "location": {
          "sysId": "19efb84edb7650106c731dcd1396193c",
          "displayName": "Dublin"
        },
        "reservationInviteeId": "1f97d58d53e701103cf7ddeeff7b129a",
        "inviteeType": "employee",
        "inviteState": {
          "displayValue": "New",
          "value": "new"
        },
        "inviteeId": "6816f79cc0a8016401c5a33be04be441",
        "name": "System Administrator",
        "email": "admin@example.com"
      },
      {
        "reservationId": "17979dc9536b01103cf7ddeeff7b12b3",
        "location": {
          "sysId": "19efb84edb7650106c731dcd1396193c",
          "displayName": "Dublin"
        },
        "reservationInviteeId": "8ee7ddc9536b01103cf7ddeeff7b1219",
        "inviteeType": "employee",
        "inviteState": {
          "displayValue": "New",
          "value": "new"
        },
        "inviteeId": "62826bf03710200044e0bfc8bcbe5df1",
        "name": "Abel Tuter",
        "email": "abel.tuter@example.com"
      },
      {
        "reservationId": "17979dc9536b01103cf7ddeeff7b12b3",
        "location": {
          "sysId": "19efb84edb7650106c731dcd1396193c",
          "displayName": "Dublin"
        },
        "reservationInviteeId": "4ae7d10d536b01103cf7ddeeff7b126b",
        "inviteeType": "visitor",
        "inviteState": {
          "displayValue": "New",
          "value": "new"
        },
        "inviteeId": "86e7d10d536b01103cf7ddeeff7b1267",
        "firstName": "Visitor",
        "lastName": "User",
        "name": "Visitor User",
        "email": "visitoruser@example.com",
        "phoneNumber": "+919876543210",
        "isVIP": true,
        "parkingType": "normal_parking",
        "licensePlate": "1234",
        "isParkingRequired": true,
        "org": "Senow",
        "visitorType": "contractor",
        "title": "President",
        "isWifiRequired": true,
        "privateNotes": "Visiting"
      }
    ]
  }
}

    WSD Reservation Invitees - POST /api/sn_wsd_rsv/wsd_reservation_invitees/reassign

    Reassigns the specified invitees from one reservation to another.

    URL format

    Versioned URL: /api/sn_wsd_rsv/{api_version}/wsd_reservation_invitees/reassign

    Default URL: /api/sn_wsd_rsv/wsd_reservation_invitees/reassign

    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
    None
    Table 9. Request body parameters
    Name Description
    reservationId Required. Sys_id of the reservation for which to reassign the invitees. Located in the Workplace Reservation [sn_wsd_rsv_reservation] table.

    Data type: String
    reservationInvitees List of invitees to reassign to the reservation identified in the reservationId parameter. Located in the Reservation Invitee [sn_wsd_rsv_m2m_reservation_invitee] table.

    This removes the specified invitees from an earlier reservation in which they were present as per the reservation invitee table and moves them to this reservation.

    Data type: Array of Strings

    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 request body. Supported types: application/json, application/xml or, text/xml.

    Default: application/json
    Content-Type Data format of the request body. Only supports application/json.
    Table 11. Response headers
    Header Description
    None

    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.
    401 Unauthorized. The user credentials are incorrect or have not been passed.
    404 Not found. The requested item wasn't found.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters

    Name Description
    result Details about the invitee reassignment.

    Data type: Object

    "result": {
   "reservationInviteeIds": Array,
   "success": Boolean
}
    result.reservationInviteeIds List of sys_ids of the reservation invitees that were re-assigned to the specified reservation.

    Data type: Array of Strings
    result.success Flag that indicates whether the invitees were reassigned to the reservation.
    Possible values:
    • true: Invitees were successfully reassigned.
    • false: Invitees were not reassigned.

    Data type: Boolean

    cURL request

    The following code example shows how to reassign invitees to a reservation.

    curl "http://instance.servicenow.com/api/sn_wsd_rsv/wsd_reservation_invitees/reassign" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
\"reservationId\":\"3984e6c1532f01103cf7ddeeff7b129b\",
\"reservationInvitees\":{\"aa31427f531701103cf7ddeeff7b1243\",\"e231427f531701103cf7ddeeff7b1243\"}
}" \
--user 'username':'password'

    Return results:

    {
  "result": {
    "success": true,
    "reservationInviteeIds": [
      "aa31427f531701103cf7ddeeff7b1243",
      "e231427f531701103cf7ddeeff7b1243"
    ]
  }
}

    WSD Reservation Invitees - POST /api/sn_wsd_rsv/wsd_reservation_invitees/submit

    Adds the specified invitees to a specified reservation.

    URL format

    Versioned URL: /api/sn_wsd_rsv/{api_version}/wsd_reservation_invitees/submit

    Default URL: /api/sn_wsd_rsv/wsd_reservation_invitees/submit

    Supported request parameters

    Table 13. 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 14. Query parameters
    Name Description
    None
    Table 15. Request body parameters (XML or JSON)
    Name Description
    invitees List of invitees to add to the specified reservation.

    Data type: Object

    "invitees": [
  {
    "email": "String",
    "firstName": "String",
    "inviteeId": "String",
    "inviteeType": "String",
    "isVIP": Boolean,
    "isWifiRequired": Boolean,
    "lastName": "String",
    "licensePlate": "String",
    "org": "String",
    "parkingType": "String",
    "phone": "String",
    "privateNotes": "String",
    "title": "String",
    "visitorType": "String"
  }
]
    invitees.email Required when inviteeType is "visitor".
    Email address of the invitee.

    Data type: String
    invitees.firstName First name of the invitee.

    Data type: String
    invitees.inviteeId Required if inviteType is "employee".
    Sys_id of the employee's user record. Located in the User [sys_user] table.

    Data type: String
    invitees.inviteeType Required.
    Type of invitee.
    Valid values: (case-sensitive)
    • employee
    • visitor

    Data type: String
    invitees.isVIP Flag that indicates whether the invitee is classified as a VIP.
    Valid values:
    • true: Invitee is a VIP.
    • false: Invitee isn't a VIP.

    Data type: Boolean
    invitees.isWifiRequired Flag that indicates whether the WIFI password should be provided to the visitor upon entry.
    Valid values:
    • true: Provide WIFI password.
    • false: Don't provide WIFI password.

    Data type: Boolean
    invitees.lastName Last name of the invitee.

    Data type: String
    invitees.licensePlate License plate of the invitee.

    Data type: String
    invitees.org Organization of the invitee.

    Data type: String
    invitees.parkingType Type of parking required for invitee.
    Valid values: (case-sensitive)
    • ev_parking
    • none
    • normal_parking
    • van_accessible_parking

    Data type: String
    invitees.phone Phone number of the invitee.

    Data type: String
    invitees.privateNotes Any additional notes provided by the invitee.

    Data type: String
    invitees.title Title of the invitee.

    Data type: String
    invitees.visitorType Type of invitee.
    Valid values: (case-sensitive)
    • client
    • contractor
    • friend_family
    • others

    Data type: String
    reservationId Required.
    Sys_id of the reservation for which to add the invitees. Located in the Workplace Reservations [sn_wsd_rsv_reservation] table.

    Data type: String

    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 16. Request headers
    Header Description
    Accept Data format of the request body. Supported types: application/json, application/xml or, text/xml.

    Default: application/json
    Content-Type Data format of the request body. Only supports application/json.
    Table 17. Response headers
    Header Description
    None

    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 18. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    401 Unauthorized. The user credentials are incorrect or have not been passed.
    404 Not found. The requested item wasn't found.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters

    Name Description
    result Result of adding the invitees to the reservation.

    Data type: Object

    "result": {
  "reservationId": "String",
  "success": Boolean
}
    result.reservationId Sys_id of the reservation to which the invitee was added.

    Data type: String
    result.success Flag that indicates whether the invitees were added to the reservation.
    Possible values:
    • true: Invitees were successfully added.
    • false: Invitees were not added.

    Data type: Boolean

    cURL request

    The following code example shows how to add both a visitor and an employee to a reservation.

    curl "http://instance.servicenow.com/api/sn_wsd_rsv/v1/wsd_reservation_invitees/submit" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{[
  \"reservationId\": \"041c4a13532f01103cf7ddeeff7b12c0\",
  \"invitees\": [
  {
    \"inviteeType\": \"employee\",
    \"inviteeId\": \"62826bf03710200044e0bfc8bcbe5df1\"
  },
  {
    \"inviteeType\":  \"visitor\",
    \"email\": \"visitoruser@example.com\",
    \"firstName\": \"Visitor\",
    \"lastName\":\"User\",
    \"isVIP\":true,
    \"visitorType\":\"contractor\",
    \"title\": \"ServiceNow Developer\",
    \"phone\": \"+91 9876543210\",
    \"isWifiRequired\": true,
    \"parkingType\": \"ev_parking\",
    \"licensePlate\": \"TS00TS0000\",
    \"org\": \"ServiceNow\",
    \"privateNotes\": \"Remarks\"
  }
]}" \
--user 'username':'password'

    Return results:

    {
  "result": {
    "success": true,
    "reservationId": "17979dc9536b01103cf7ddeeff7b12b3"
  }
}