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

Copy 
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

Copy 
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

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