Skip to main content
Index

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 How to Guide. 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 Started 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 How to Guide. 

 

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.