WorkVisits (V2)

WorkVisits (V2) API allows a user with Work Visit permission to do the following: create a work visit request, and update their work visit request.

To create a work visit, see Schedule work visit (V2) under the Getting Started. All other methods can be found below.

PATCH WorkVisits {orderId}

	PATCH /workVisits/{orderId}
Method	PATCH
URL or End Point	/colocations/v2/orders/workVisits/{orderId}
Headers	Authorization, Content-Type
Query Parameters	Not applicable
Body	details {openCabinet, visitStartDateTime, visitEndDateTime}, contacts [{ type, registeredUsers [...]}]

This method partially updates a specific work visit order that is not cancelled or completed. To update this work visit order, the authenticated user must have permission to view all users' requests, or they must be the ordering or technical contact for this order. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

Currently, the user can update the following in a work visit order:

start and end dates of the visit
request to open cabinets
notification contacts

If you would like to add additional information instead, you may add notes to this work visit with POST Orders {orderId} Notes.

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Access Token section.

The following screenshot shows different curl requests to update the work visit order.

Updating only one detail of the work visit

curl -X
PATCH "https://api.equinix.com/colocations/v2/orders/workVisits/1-188243137021"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
   "details": {
    "visitStartDateTime": "2020-11-02T10:45:41.564Z"
  }
}'

Updating only notification contacts

curl -X
PATCH "https://api.equinix.com/colocations/v2/orders/workVisits/1-188243137021"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
   "contacts": [
    {
      "registeredUsers": [
        "siripala@acme.com",
        "somchai9"
      ],
      "type": "NOTIFICATION"
    }
  ]
}'

Updating the notification contacts and all details in the work visit

curl -X
PATCH "https://api.equinix.com/colocations/v2/orders/workVisits/1-188243137021"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
   "details": {
    "openCabinet": true,
    "visitStartDateTime": "2020-11-02T10:45:41.564Z",
    "visitEndDateTime": "2020-11-04T10:45:41.564Z"
  },
   "contacts": [
    {
      "registeredUsers": [
        "siripala@acme.com",
        "somchai9"
      ],
      "type": "NOTIFICATION"
    }
  ]
}'

The description of the URL parameters is as follows:

URL Parameter Name	Mandatory	Type	Example	Description
orderId	Yes	string	1-188243137021	Order identifier (order ID). Order ID was returned in the response header 'Location' after the work visit order was created. For example, 'orders/1-188243137021' would have been returned as the URL of the newly created work visit order. This order ID is also the work visit order number in the Equinix Customer Portal. If you are not sure of your order ID, see How to retrieve order history? under the Getting Started.

The description of the body parameters is as follows:

When 'Conditional' is indicated for a Body Parameter, refer to Description for further details.

Body Parameter Name	Mandatory	Type	Example	Applicable Values	Description
details	No	object			Details of your work visit request. This comprises the following parameters where applicable: cages, openCabinet, visitStartDateTime, visitEndDateTime, visitors.
openCabinet	No	boolean	true	true, false	This is an additional request for Equinix to open your secure cabinet during the work visit. If 'true', Equinix staff will open the cabinet. If 'false', otherwise. Default value: false
visitStartDateTime	No	string	2020-11-02T10:45:41.564Z		Requested start date and time of the work visit. Provide a date and time (UTC time zone) in the following ISO 8601 format: yyyy-MM-dd'T'HH:mm:ssZ
visitEndDateTime	No	string	2020-11-04T10:45:41.564Z		Requested end date and time of the work visit. Work visit end date cannot exceed 2 weeks from the start date. If a visitor needs to be on site for more than two weeks, please set up security access for them instead. Provide a date and time (UTC time zone) in the following ISO 8601 format: yyyy-MM-dd'T'HH:mm:ssZ
contacts	No	array [objects]			Contacts array consists of the notification contact object. The contacts object contains the following parameters: registeredUsers, and type. Limit: 1 object This notification contacts object will serve as the latest list of registered users to receive notifications for this order. All registered users included in this object will completely replace the existing list of users. If you would like to add more users to the existing list, ensure that the existing list of registered usernames are not left out in this object.
type	Conditional	string	NOTIFICATION	NOTIFICATION	Defines the contact type.
registeredUsers	Conditional	array [strings]	janesmith123, jimsnow1		List of Equinix Customer Portal usernames of the registered contacts. Each string in the array represents one contact's username. Equinix Customer Portal user's status must be approved, active, or locked. If the user's status is not any of these, the request will fail. Limit for notification contacts: 1 to 10 strings.

Work visit order update is successful when an HTTP code of 204 or 202 is returned, and the following response header is returned. There is no response body.

HTTP Response Header Name

Description

Location

URL of the order.

Example: /orders/{orderId}

'orderId' is the order identifier (ID). This is important to retrieve, update, cancel, or add notes to the order. The order ID is also known as the order number in the Equinix Customer Portal.

If you get “Insufficient permissions” error, contact your Master Administrator.

PATCH WorkVisits {orderId}​

PATCH WorkVisits {orderId}