Schedule on-site services

On-site services such as Work Visit, IBX Security Access, and Conference Rooms can be scheduled at the IBX based on customer request. These on-site services can only be scheduled by an Equinix Customer Portal user with the appropriate IBX Access Services Request permissions.

To schedule a work visit, the user must have Work Visit permission.

Schedule work visit (V2)

Step 1: Authenticate

Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication.

 

Refer to Generating Client ID and Client Secret under Getting Access Token section for instructions on how to create client ID and client secret and refer to Requesting Access and Refresh tokens for instructions on how to call Oauth API to validate and authenticate your credentials.

 

If you are unaware of your user credentials for Equinix Customer Portal, contact your local Equinix Service Desk. 

Step 2: Get Work Visit Details

 

To get work visit details, the user must have Work Visit permission. If you are unaware of your user permissions, contact your Master Administrator.

Get Location Information
Retrieve all your permitted location information.

Determine the exact cage ID, account number, and cabinet ID for your work visit.

These values will be passed in the request body in Step 4 for the following parameters: details.cages.id, details.cages.account, details.cages.cabinetId.

 

Refer to GET Locations under the API Reference section for instructions on how to get your permitted location information. You may skip this step if you already know the location information.

Step 3: Get Contact Information

 

If you are the only technical and notification contact for this order, skip this step and proceed to Step 4.

3a) Identify usernames
Identify the usernames you want to include as technical and notification contacts for this visit.

To verify if the username belongs to your intended user, proceed to Step 3b.

When you are certain this is the correct username, proceed to Step 4, where this value will be passed in the request body for the following parameter in the contacts array: registeredUsers.

 

Refer to GET Users under the API Reference section for instructions on how to get all your users. You may skip this step if you know this username.

3b) Verify usernames
Ensure the user profile details match the details of your intended user.

 

Refer to GET Users {username} under the API Reference section for instructions on how to get your user profile. You may skip this step if you are certain this is the intended user.

Step 4: Schedule Work Visit

	POST /workVisits
Method	POST
URL or End Point	/colocations/v2/orders/workVisits
Headers	Authorization, Content-Type
Query Parameters	Not applicable
Body Parameters	details { cages [{ id, accountNumber, cabinetId}], openCabinet, visitStartDateTime, visitEndDateTime, visitors [{ registeredUsers [...]}, {firstName, lastName, companyName, details [{ type, value}]}]}, customerReferenceId, description, attachments [{ id, name}], purchaseOrder { type, number, amount, startDate, endDate, attachmentId}, contacts [{ type, registeredUsers [...]}, { type, firstName, lastName, availability, timezone, details [{ type, value}]}]

This method creates a work visit request for an authenticated user with Work Visit services request permission. 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.

 

If a visitor needs to be on-site for more than two weeks, ensure they have IBX Data Center Access permissions and a completed Security Profile in the Equinix Customer Portal.

 

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 screenshots show sample curl requests based on the different scenarios.

Work Visit request for a single account cage, without any additional information or attachment (minimum required information)

curl -X
POST "https://api.equinix.com/colocations/v2/orders/workVisits"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
   "details": {
    "cages": [
      {
        "id": "AM1:01:000111"
      }
    ],
    "visitStartDateTime": "2020-11-02T10:45:41.564Z",
    "visitEndDateTime": "2020-11-04T10:45:41.564Z",
    "visitors": [
      {
        "registeredUsers": [
          "john_doe1"
        ]
      }
    ]
  }
}'

Work Visit request for a cage with multiple accounts, without any additional information or attachment (minimum required information)

curl -X
POST "https://api.equinix.com/colocations/v2/orders/workVisits"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
   "details": {
    "cages": [
      {
        "id": "AM1:01:000111",
        "accountNumber": "901011"
      }
    ],
    "visitStartDateTime": "2020-11-02T10:45:41.564Z",
    "visitEndDateTime": "2020-11-04T10:45:41.564Z",
    "visitors": [
      {
        "registeredUsers": [
          "john_doe1"
        ]
      }
    ]
  }
}'

Work Visit request for a cage with multiple accounts, including additional information and attachment

 

Before creating an order with attachment, call the POST Attachments File under the API Reference section.

curl -X
POST "https://api.equinix.com/colocations/v2/orders/workVisits"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
   "details": {
    "cages": [
      {
        "id": "AM1:01:000111",
        "accountNumber": "901011",
        "cabinetId": "AM1:01:000111:0101"
      },
      {
        "id": "AM1:01:000111",
        "accountNumber": "901011",
        "cabinetId": "AM1:01:000111:0109"
      }
    ],
    "openCabinet": true,
    "visitStartDateTime": "2020-11-02T10:45:41.564Z",
    "visitEndDateTime": "2020-11-04T10:45:41.564Z",
    "visitors": [
      {
        "registeredUsers": [
          "john_doe1",
          "jane_smith1"
        ]
      },
      {
        "firstName": "John",
        "lastName": "Doe",
        "companyName": "Acme Corp.",
        "details": [
          {
            "type": "EMAIL",
            "value": "johndoe@acme.com"
          },
          {
            "type": "MOBILE",
            "value": "+1-912345678"
          }
        ]
      }
    ]
  },
  "customerReferenceId": "EQX_CC_20201010",
  "description": "Please refer to attachment for full details for this work visit.",
  "attachments": [
    {
      "id": "85d9660a-f877-405a-b38e-8e61a4f77f44",
      "name": "OrderInstructions.docx"
    }
  ],
  "purchaseOrder": {
    "type": "NEW",
    "number": "EQXPO_Ref9654284",
    "amount": 10000,
    "startDate": "2020-10-01",
    "endDate": "2021-09-30",
    "attachmentId": "56d10de6-f2c0-4edd-ba29-b70736aa2093"
  },
  "contacts": [
    {
      "type": "NOTIFICATION",
      "registeredUsers": [
        "john_doe1",
        "jane_smith1"
      ]
    },
    {
      "type": "TECHNICAL",
      "firstName": "John",
      "lastName": "Doe",
      "availability": "WORK_HOURS",
      "timezone": "America/New_York",
      "details": [
        {
          "type": "EMAIL",
          "value": "johndoe@acme.com"
        },
        {
          "type": "PHONE",
          "value": "+1-987654321"
        },
        {
          "type": "MOBILE",
          "value": "+1-912345678"
        }
      ]
    }
  ]
}'

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	Yes	object			Details of your work visit request. This comprises the following parameters where applicable: cages, openCabinet, visitStartDateTime, visitEndDateTime, visitors.
cages	Yes	array [objects]			Cages that will be visited. Each cage object comprises the following parameters where applicable: id, accountNumber, cabinetId. Limit: At least 1 object.
id	Yes	string	AM1:01:000111		ID of the cage that will be visited. When you provide a cage ID without cabinet IDs, it will be assumed that all your organizations cabinets in this cage will be visited.
accountNumber	No	string	901011		Account number to be associated with this cage and the cabinet that will be visited. You should provide an account number when there are multiple accounts and cabinets associated with this cage. When you have multiple accounts in this cage and you do not provide an account number or a cabinet ID, the account number from the first cabinet in this cage will be associated with this cage. Subsequently, only the cabinets associated with this first account number can be visited. When you have multiple accounts in this cage and you do not provide an account number, but you provide a cabinet ID, the account number associated with this cabinet will be associated with this cage.
cabinetId	Conditional	string	AM1:01:000111:0101		ID of the cabinet that will be visited. You should specify the ID of the cabinet to be visited if you do not want to visit all your organization's cabinets in your cage. When you need your cabinets to be opened, you should specify the ID of these cabinets to avoid any issues in processing this work visit order.
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 When assistance to open cabinet is required but cabinet IDs are not included in this request, it is the default expectation that all your organization's cabinets in your cage require assistance to be opened.   With effect from Dec 2020, it will be mandatory to list all the cabinets to be opened in the IBX location information when requesting assistance to open cabinet.
visitStartDateTime	Yes	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	Yes	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, 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
visitors	Yes	array [objects]			List of visitors who will visit your cages and cabinets. Each visitor object comprises the following parameters where applicable: registeredUsers, firstName, lastName, companyName, details. If the visitor is an Equinix Customer Portal user with an approved, active, or locked status, you should provide their Equinix-registered username in the following parameter: registeredUsers. An object with registeredUsers can contain up to 10 Equinix-registered visitors. If the visitor is not an Equinix-registered user, they do not have the required username and you must pass provide their full name and company name in the following parameters: firstName, lastName, companyName. You should also provide their contact details in the following parameter: details. The object with the non-registered Equinix user represents one visitor. Providing a non-registered visitor's contact details, such as their email address or mobile number, will allow them to receive a unique QR code that will improve the security and speed of their IBX visit. Alternatively, the ordering contact (the user who created this request) will also receive the QR code(s) for each visitor, and may distribute the QR code(s) to the individuals before their visit. Limit: 50 visitors.   All visitors must bring a government-issued photo ID to enter an IBX. The number of visitors allowed may vary when access to the IBX is restricted. When the number of visitors allowed is different from the limit stated here, contact your Global Service Desk for more information.
registeredUsers	Conditional	array [strings]	john_doe1, jane_smith1		Equinix-registered usernames of visitors. This is recommended if the visitor is a registered user of the Equinix Customer Portal.   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. Refer to GET Users for more information.
firstName	Conditional	string	John		The visitor's first name. This field is mandatory for visitors without the required Equinix-registered username (this visitor is different from the 'registeredUsers' visitors). This is free text input. Limit: 30 characters. Our local kiosks are case sensitive. Visitors without QR codes will need to enter their name manually in the exact format entered here. We suggest you follow the preferred format, 'John Smith'. For example, when visitor's first name entered is 'John' and last name entered is 'Smith', their full name will appear as and is expected to be entered at the IBX as 'John Smith'.
lastName	Conditional	string	Doe		The visitor's last name. This field is mandatory for visitors without the required Equinix-registered username (this visitor is different from the 'registeredUsers' visitors). This is free text input. Limit: 30 characters. For recommendation on last name input, see description for the following parameter: firstName.
companyName	Conditional	string	Acme Corp.		The visitor's company name. This field is mandatory for visitors without the required Equinix-registered username (this visitor is different from the 'registeredUsers' visitors). This is free text input. Limit: 80 characters.
details	No	array [objects]			List of contact details for the visitor. This is only applicable for a visitor who is a non-registered user (this visitor is different from the 'registeredUsers' visitors). When you pass 'details' with 'regsiteredUser', the contact details will be ignored. Each contact details object contains the following parameters: type, value. Limit: 2 objects.
type	Conditional	string	EMAIL	EMAIL, MOBILE	Defines the contact detail type. This is mandatory when passing the parameter 'details'. It is recommended to provide email and/or mobile number. Type - Description EMAIL - Email address. This is recommended. MOBILE - Mobile phone number. This is recommended.
value	Conditional	string	johndoe@acme.com		Value of the contact detail type. This is mandatory for a non-registered user. Phone numbers must be prefixed by '+' country code. For example, +1-987-654-3210 or +1 987 654 3210. Email addresses must follow a valid email format.
customerReferenceId	No	string			Customer reference ID for this order. This information can be searched for in Order History and will appear within Reports. This is free text input. Limit: 1 to 40 characters.
description	No	string	Please refer to attachment for full details for this work visit.		Additional descriptions about the work visit that you would like to include. If you have a shipment associated with this work visit, include it here. This is free text input. Limit: 4000 characters.
attachments	No	array [objects]			Attachments array comprising object(s) with attachment details. Each attachment object must contain the following parameters: id, name. If this is critical infrastructure related work, you may attach or bring a government document to help prioritize your request. Up to 5 attachments, each not exceeding 5MB, can be provided in the following formats: bmp, jpg, jpeg, gif, png, tif, tiff, txt, doc, docx, xls, xlsx, ppt, pps, ppsx, pdf, and vsd.   See POST Attachments File under the API Reference section for more information.
id	Conditional	string	85d9660a-f877-405a-b38e-8e61a4f77f44		Attachment id. This is mandatory when an attachment is included. You will obtain this value after attaching your file using the POST Attachments File API. Limit: 36 characters.
name	Conditional	string	OrderInstructions.docx		Name of the attachment. This is mandatory when an attachment is included. You will obtain this value after using the POST Attachments File API, but you can change the name for your own reference when including this attachment in any order request. This is free text input. Limit: 5 to 100 characters.
purchaseOrder	Conditional	string			Purchase order (PO) information you would like to associate with this order. This is mandatory for PO bearing accounts that have requested open cabinet assistance during the work visit. This comprises the following parameters where applicable: type, number, amount, startDate, endDate, attachmentId.
type	Conditional	string	NEW	EXEMPTED, EXISTING, NEW	Type of purchase order. This is mandatory when including parameter 'purchaseOrder'. Type - Description EXEMPTED - You are exempted from: a) including a purchase order in your request, or b) you are applying for exemption to include a purchase order in your request. If b), see body parameter 'attachmentId'. EXISTING - You would like to use an existing blanket purchase order for this order. Body parameter 'number' is mandatory with this. NEW - You would like to use a new blanket purchase order which has not yet been applied for any order. Body parameter 'number' is mandatory with this. You should also include the following parameters: amount, startDate, endDate, attachmentId.
number	Conditional	string	EQXPO_Ref9654284		Purchase order number to associate with this order. This is applicable when purchase order type is existing or new. For 'EXISTING' purchase orders, it the blanket purchase order number submitted throws an error, select 'EXEMPTED' for purchase order type instead.   See GET PurchaseOrders under the API Reference section to retrieve your applicable blanket purchase order number.
amount	No	number	10000		Total value amount of the new purchase order. This is only applicable when purchase order type is new, and is recommended to include.
startDate	No	string	2020-10-01		Starting date of the new purchase order. This is only applicable when purchase order type is new, and is recommended to include. Format: yyyy-MM-dd
endDate	No	string	2021-09-30		End date of the new purchase order. This is only applicable when purchase order type is new, and is recommended to include. Format: yyyy-MM-dd
attachmentId	No	string	56d10de6-f2c0-4edd-ba29-b70736aa2093		Attachment ID. You can attach a new purchase order document, or the Purchase Order Exemption Form. Use the document below as a template for your Purchase Order Exemption Form. Download Purchase Order Exemption Form Template. The attachment, not exceeding 5MB, can be provided in the following formats: bmp, jpg, jpeg, gif, png, tif, tiff, txt, doc, docx, xls, xlsx, ppt, pps, ppsx, pdf, and vsd. Limit: 36 characters.   This should be included when your purchase order type is 'NEW' and you would like to attach the new blanket purchase order, or your purchase order type is 'EXEMPTED' and you are submitting a Purchase Order Exemption form.   See POST Attachments File under the API Reference section for more information.
contacts	No	array [objects]			Contacts array consists of the technical contact and notification contact(s) information. Equinix will be able to communicate with these contacts based on their information provided. When any of the contacts are not provided, they default to the authenticated user who submitted this order (i.e. ordering contact). Technical contact is the person who Equinix can reach out to for technical clarifications. Only one technical contact can be passed. If they are a registered Equinix Customer Portal user, only their username needs to be passed. All their contact details will be referred from their user profile in the Equinix Customer Portal. Their work hours time zone will also be referred from the user profile, unless otherwise included in this request. If they are a non-registered contact, their full name (first and last names) and contact details must be provided. To include more information such as the technical contact's availability or time zone, see parameter 'details'. Notification contact is the person who will be notified of status updates. At least one notification contact must be provided. They must be a registered Equinix Customer Portal user. Only their username needs to be passed. N/A for a non-registered contact. When providing the contact information for: Registered contact object, the following body parameters are mandatory: registeredUsers, type. All other attributes passed in a registered contact object will be ignored. Non-registered contact object, the following body parameters are mandatory: firstName, lastName, type, details. For more information on technical contact's work hours time zone, see description of body parameter, 'timezone'.
type	Conditional	string	NOTIFICATION	NOTIFICATION, TECHNICAL	Defines the contact type. This is mandatory for the registered and non-registered contacts. Type - Description TECHNICAL - Technical contact (applies to both registered and non-registered contacts). NOTIFICATION - Notification contact (applies to registered contact only).
registeredUsers	Conditional	array [strings]	john_doe1, jane_smith1		Equinix Customer Portal username of the registered user. This is mandatory for a registered contact.   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 technical contact: 1 string. Limit for notification contact(s): 1 to 10 strings.
firstName	Conditional	string	John		First name of the non-registered Technical contact. This is mandatory for a non-registered Technical contact. This is free text input.
lastName	Conditional	string	Doe		Last name of the non-registered Technical contact. This is mandatory for a non-registered Technical contact. This is free text input.
availability	Conditional	string	WORK_HOURS	WORK_HOURS, ANYTIME	Defines the technical contact's availability to be contacted. Availability - Description ANYTIME - Technical contact is available 24/7. WORK_HOURS - Technical contact is only available during work hours in their time zone. For a registered technical contact, their work hours is defaulted to the time zone in their user profile. If they would like to provide a different time zone, they should provide it in the body parameter 'timezone'. For a non-registered technical contact, if they select their work hours, the parameter 'timezone' is mandatory. Default value: ANYTIME
timezone	Conditional	string	America/New_York	Click here for applicable values.	Defines the time zone of the technical contact's work hours. This is mandatory when the non-registered technical contact selects their work hours as their availability. For a registered technical contact, the time zone provided here will override the time zone in the user profile only for this order request, and does not replace the time zone in their user profile. For example, selecting 'America/Detroit' specifies the technical contact's work hours.
details	Conditional	array [objects]			Array of contact details for the non-registered technical contact consisting of the type of contact detail and its value. It is mandatory to provide two types of contacts: always email address and at least one type of number, either phone or mobile. Limit: 2 to 3 objects.
type	Conditional	string	EMAIL	EMAIL, MOBILE, PHONE	Defines the contact detail type. Type - Description EMAIL - Email address. MOBILE - Mobile phone number. This is the secondary contact number. PHONE - Phone number. This is the primary contact number.
value	Conditional	string	johndoe@acme.com		Value of the contact detail type. Phone and mobile numbers must be prefixed by '+' country code. For example, +1-987-654-3210 or +1 987 654 3210. Email addresses must follow a valid email format.

Order is successfully created when an HTTP code of 201 is returned and the following response header is returned. There is no response body.

HTTP Response Header Name	Description
Location	Location of the newly created order. Example: /orders/{orderId}   'orderId' is the order identifier. This is important if you want to update, add notes to, retrieve and reply negotiations for, or cancel the order. It is also known as the order number in the Equinix Customer Portal.

 

If you would like to update this order, see WorkVisits (V2) in the API Reference section for more information.

If you would like to add notes to this order, retrieve and reply negotiations for this order, or cancel this order, see Orders (V2 Beta) in the API Reference Section for more information.

 

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