Skip to main content
Index

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

Step 1: Authenticate

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

 

Refer to Generating a Client ID and Client Secret key under Getting Started 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 your IBX location information.

 

Use this API to get all available IBX locations, cages, and cabinets that the user has access to.

 

Refer to Get Workvisit Locations under the API Reference section for instructions on how to retrieve available IBX locations. You may skip this step if you already know the location information.

Step 3: Schedule Work Visit

POST /orders/workvisit

 Method  POST
 URL or End Point  /v1/orders/workvisit
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body

 ibxLocation {ibx, cages [{cage, accountNumber, cabinets [...], cage, accountNumber}]}, serviceDetails {additionalDetails, visitors [{userName}, {firstName, lastName, company, email, mobilePhoneCountryCode, mobilePhone}], schedule {startDateTime, endDateTime}, openCabinet, supervisionRequired}, attachments [{id, name}], customerReferenceNumber, purchaseOrder {purchaseOrderType, number, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}]

 

This method creates a work visit request to grant IBX visitors access for up to two weeks. This can only be done under a user with Work Visit 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, please set up security access for them 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 Started section.

 

The following screenshots show a sample curl request and JSON response for this method.

 

The requests show two scenarios: An order made for a work visit from 23 to 30 August 2019 at IBX location, AT2, in two cages (one with a specified cabinet) for two visitors (one is a registered user with Equinix, and one is not); and the same work visit order with an added Smart Hands order, additional information and attachment, additional customer reference information, and additional contact included.

 

The response indicates that the order was received, and returned the IBX location information of the work visit and the work visit order number for customer reference. 

 

Work visit order without added Smart Hands request, additional information, attachment, or contact information

 

curl -X

POST "https://api.equinix.com/v1/orders/workvisit"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AT2",
    "cages": [
      {
        "cage": "AT2:02:V050005-6-591",
        "accountNumber": "109880",
        "cabinets": [
          "AT2:02:V050005-6-591:V0106"
        ]
      },
      {
        "cage": "AT2:0G:00EQ11",
        "accountNumber": "109880"
      }
    ]
  },
  "serviceDetails": {
    "visitors": [
      {
        "userName": "JohnDoe123"
      },
      {
        "firstName": "MaryJane",
        "lastName": "Watson",
        "company": "Jingleheimer Schmidt Co."
      }
    ],
    "schedule": {
      "startDateTime": "2019-08-23T06:54:45.225Z",
      "endDateTime": "2019-08-30T06:55:01.063Z"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "andrew1"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "andrew1"
    }
  ]
}'

 

Work visit order with added Smart Hands request, additional information and attachment, additional customer reference information, and additional contacts included

 

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

 

curl -X

POST "https://api.equinix.com/v1/orders/workvisit"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AT2",
    "cages": [
      {
        "cage": "AT2:02:V050005-6-591",
        "accountNumber": "109880",
        "cabinets": [
          "AT2:02:V050005-6-591:V0106"
        ]
      },
      {
        "cage": "AT2:0G:00EQ11",
        "accountNumber": "109880"
      }
    ]
  },
  "serviceDetails": {
    "additionalDetails": "Visitors may visit individually or together for either or both cages.",
    "visitors": [
      {
        "userName": "JohnDoe123"
      },
      {
        "firstName": "MaryJane",
        "lastName": "Watson",
        "company": "Jingleheimer Schmidt Co.",
        "email": "jwatson@jhs-co.com",
        "mobilePhoneCountryCode": "+1",
        "mobilePhone": "555-555-1234"
      }
    ],
    "schedule": {
      "startDateTime": "2019-08-23T06:54:45.225Z",
      "endDateTime": "2019-08-30T06:55:01.063Z"
    },
    "openCabinet": true,
    "supervisionRequired": true
  },
  "attachments": [
    {
      "id": "68a81166-decf-4d7b-8e23-b192b0ac6d85",
      "name": "AdditionalWorkVisitDetails.docx"
    }
  ],
  "customerReferenceNumber": "WV082019-101",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "andrew1"
    },
    {
      "contactType": "TECHNICAL",
      "name": "John Smith",
      "email": "johnsmith@corporation.com",
      "workPhoneCountryCode": "+44",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Europe/London",
      "mobilePhoneCountryCode": "+44",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "andrew1"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "JohnDoe123"
    }
  ]
}'

 

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
ibxLocation Yes object     IBX location information consists of cages information and IBX. 
ibx Yes string AT2  

The IBX location code.

cages Yes

array

[objects]

   

Cages information consists of ID of cages, ID of cabinets, and cage account number.

cage Yes string AT2:02:V050005-6-591  

ID of the cage.

 

If you want to provide access to all your cabinets in the cage, only the cage ID will suffice.

 

If you want to limit access to specific cabinets, provide the cabinet ID numbers.

accountNumber Yes string 109880  

The customer account number that is linked to the cage.

cabinets No

array

[strings]

AT2:02:V050005-6-591:V0106  

ID(s) of the cabinet(s).

 

Specifying individual cabinet IDs will limit visitor access to only these cabinets. 

If cabinets IDs are not included in the request, it is the default expectation that visitors will visit all your cabinets in this cage. 

 

If assistance to open cabinets is required for this work visit order, it is recommended to include all the IDs of the cabinets that need to be opened to avoid any issues in processing this work visit order. Refer to the description of the body parameter 'openCabinet' for more information. 

 

With effect from Dec 2020, it will be mandatory to include all the IDs of the cabinets that need to be opened when requesting assistance to open cabinet. 

serviceDetails Yes object    

Service details consist of visitors information and additional work visit details.

additionalDetails No string Visitors may visit individually or together for either or both cages.  

Any additional details about the work visit that customer would like to include. This is free text input.

 

This field can only be up to 4000 characters long. 

visitors Yes

array

[objects]

   

Visitors information that includes the Equinix- registered username of visitors (if they are active users under your organization) or the visitor first name, visitor last name, and visitor company name.

 

The maximum number of visitors allowed in one work visit is 50.

 

For visitors without the required Equinix-registered username, providing their contact details such as the email address will allow them to receive a unique QR code that will improve the security and speed of their IBX visit. Alternatively, the ordering contact will also receive the QR code(s) for each visitor on the ticket, and may distribute the QR code(s) to the individuals before their visit. 

 

All visitors must bring a government-issued photo ID to enter an IBX.

userName Yes string JohnDoe123  

Equinix-registered username of contact person, who is active and approved, or locked.

 

If the visitor does not have the required Equinix-registered username, the visitor's first name, last name, and their company name should be provided.

firstName Conditional string MaryJane  

The visitor's first name. This is free text input.

 

This is field is mandatory for visitors without the required Equinix-registered username.  (This is a different visitor from the above, and the following information about the un-listed visitor must be provided: first name, last name, and their company name. Their mobile phone country code and their mobile phone number, and/or their email address may also be provided).

 

This field can only be up to 30 characters long. 

 

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. Example: John Smith

lastName Conditional string Watson  

The visitor's last name. This is free text input.

 

This is field is mandatory for visitors without the required Equinix-registered username. 

 

This field can only be up to 30 characters long. 

 

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. Example: John Smith

company Conditional string Jingleheimer Schmidt Co.  

The visitor's company name. This is free text input.

 

This is field is mandatory for visitors without the required Equinix-registered username. 

 

This field can only be up to 80 characters long. 

email No string jwatson@jhs-co.com  

Email address of contact person. This is free text input.

 

This is an optional field but is only applicable for visitors who do not have the required Equinix-registered username.

 

Visitors without the required Equinix-registered username may provide their email and/or mobile phone (country code and phone number) contact details. 

 

It is recommended to include visitor's contact details, so that the visitor may receive a unique QR code that will improve the security and speed of their IBX visit. Alternatively, the ordering user will also receive the QR codes for each visitor on the ticket, and may distribute the QR code(s) to the individuals before their visit.

mobilePhoneCountryCode No string +1  

Mobile phone number country code of contact person. This is free text input.

 

This is an optional field but is only applicable for visitors who do not have the required Equinix-registered username.

 

Visitors without the required Equinix-registered username may provide their email and/or mobile phone (country code and phone number) contact details. 

 

Example: +123

 

It is recommended to include visitor's contact details, so that the visitor may receive a unique QR code that will improve the security and speed of their IBX visit. Alternatively, the ordering user will also receive the QR codes for each visitor on the ticket, and may distribute the QR code(s) to the individuals before their visit.

mobilePhone No string 555-555-1234  

Mobile phone number of contact person. This is free text input.

 

This is an optional field but is only applicable for visitors who do not have the required Equinix-registered username. 

 

Visitors without the required Equinix-registered username may provide their email and/ormobile phone (country code and phone number) contact details. 

 

It is recommended to include visitor's contact details, so that the visitor may receive a unique QR code that will improve the security and speed of their IBX visit. Alternatively, the ordering user will also receive the QR codes for each visitor on the ticket, and may distribute the QR code(s) to the individuals before their visit.

schedule Yes object    

Schedule information that includes schedule type, date and time for equipment to be installed, and the time zone of the IBX.

startDateTime Yes string 2019-08-23T06:54:45.225Z

 

Requested start date and time of the work visit.

 

Provide a date and time (UTC timezone) in one of the following ISO 8601 formats:

 

yyyy-MM-dd'T'HH:mm:ssZ,

yyyy-MM-dd'T'HH:mm:ss.SSSZ.

endDateTime Yes string 2019-08-30T06:55:01.063Z  

Requested end date and time of the work visit.

 

Provide a date and time (UTC timezone) in one of the following ISO 8601 formats:

 

yyyy-MM-dd'T'HH:mm:ssZ,

yyyy-MM-dd'T'HH:mm:ss.SSSZ.

 

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.

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', the cabinet will remain closed during the work visit. 

 

Default value: false

 

It is recommended to list all the cabinets to be opened in the IBX Location information to avoid any issues in processing this work visit order.

 

If assistance to open cabinet is required but cabinet information is not included in this request, it is the default expectation that all your cabinets in the 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. 

supervisionRequired No boolean true

true,

false

This is an additional request for Equinix staff to provide supervision, technical assistance, or antenna access, during the work visit.

 

If 'true', Equinix staff will provide the supervision, technical assistance, or antenna access during the work visit. 

 

If 'false', the Equinix staff will not provide any additional supervision, assistance, or access. 

 

Default value: false

 

If you require supervision and your account is PO bearing, it is mandatory to include your purchase order information in this request. Refer to the description of the body parameter 'purchaseOrder' for more information. 

 

Additional Smart Hands fees will apply. There is no need to create a separate Smart Hands order.

attachments No

array

[objects]

   

An array containing the attachment details.

 

Up to 5 additional 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.

 

In this case, it is for any supporting photos or documentation that may help the request.

 

Refer to POST Attachments File in the API Reference section for more information. 

id Conditional string

68a81166-decf-4d7b-

8e23-b192b0ac6d85

 

ID of the attachment. You will obtain this value after attaching your file using the attachment API.

 

This is mandatory when an attachment is included.

name Conditional string AdditionalWorkVisitDetails.docx  

Name of the attachment. You will obtain this value after attaching your file using the attachment API, but you may change the name for your own reference when including this attachment in any order request. This is free text input. 

 

This is mandatory when an attachment is included.

customerReferenceNumber No string

WV082019-101

 

Customer reference information for this order. This is free text input.

 

This can be an internal code. This information can be searched for in Order History and will appear within Reports.

 

This field can only be up to 50 characters long. 

purchaseOrder Conditional object    

Purchase order (PO) information details. 

 

This is mandatory for PO bearing accounts that have requested Equinix supervision during the work visit. 

 

If you do not know your account's PO bearing status, refer to GET Workvisit Locations in the API Reference section for more information. 

purchaseOrderType Conditional string EXEMPTED

EXEMPTED,

EXISTING

Purchase order can be defined as new, existing, or exempted.

 

However, only existing and exempted purchase order types are currently supported.

 

If 'EXISTING', the blanket purchase order is already known to Equinix and the purchase order number must be sent. Only numbers for blanket purchase orders will be accepted. If you do not have a valid blanket purchase order number, see 'EXEMPTED'.

 

If 'EXEMPTED', there are 2 scenarios where this option applies:-

 

1. A purchase order exemption form has already been submitted and approved. No additional information or attachments are required.

 

2. A purchase order exemption request is made together with this order. A Purchase Order Exemption form should be attached to facilitate the exemption request.  

 

This is mandatory for PO bearing accounts. 

number Conditional string    

Blanket purchase order number. This is free text input.

 

This field can only be up to 20 characters long.

 

If the blanket purchase order number submitted throws an error, select 'EXEMPTED' for purchase order type instead.

 

This is mandatory if purchase order type is 'EXISTING'.

attachment No object    

An object containing the attachment details of 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.

 

This should be included when purchase order type is 'EXEMPTED' and you are submitting a Purchase Order Exemption form.

 

Refer to POST Attachments File under the API Reference section for more information. 

id Conditional string abc1fd2e-345f-67g4-hi89-01jk234l5m6n  

ID of the attachment. You will obtain this value after attaching your file using the attachment API. 

 

This is mandatory when an attachment is included.

name Conditional string PurchaseOrderExemptionForm123.docx  

Name of the attachment. You will obtain this value after attaching your file using the attachment API, but you may change the name for your own reference when including this attachment in any order request. This is free text input.    

 

This is mandatory when an attachment is included. 

contacts Yes

array

[objects]

 

 

Contact information consists of the Ordering contact details, Technical contact details, and Notification contact details. 

contactType Yes string

ORDERING

ORDERING, 

TECHNICAL, 
NOTIFICATION

There are three types of contact persons: Ordering, Technical, and Notification. 

 

Mandatory contacts

- Ordering contact person: Person who created the order. Only one Ordering contact can be passed.

- Notification contact person: Person who will be notified of status updates. At least one notification contact must be provided. If notification contact is not available to pass, use ordering contact as notification contact.

 

Only contactType and userName are valid for ordering and notification contacts. Any other attributes will be ignored. 

 

Additional contacts

- Technical contact person: Person who Equinix can reach out to for technical clarifications. Only one Technical contact can be passed

- Notification contact person(s)

userName Yes string andrew1  

Equinix-registered username of contact person whose user profile is active or locked. 

 

For Ordering contact, Equinix-registered username of contact person must be active.

 

For Notification and Technical contacts, Equinix-registered username of contact person can be active or locked. 

 

If the Technical contact does not have the required Equinix-registered username, their full name, email address, work phone, and work phone timezone calling preference must be provided. It is recommended to also include the work phone country code. Additional information such as mobile phone country code, mobile phone number, and their availability to take calls on their mobile phone may also be provided.

 

With the exception of the mandatory contact information required for the Technical contact, any other additional contact information passed together with a 'userName' for Ordering, Technical, and Notification contacts will be ignored.

 

For example, when 'email' and 'workPhone' are passed with 'userName' for Notification contact, these contact details will be ignored.

Name Conditional string John Smith  

Full name of contact person. This is free text input.

 

This is mandatory when the Technical contact does not have the required Equinix-registered username.

email Conditional string johnsmith@corporation.com  

Email information of contact person. This is free text input.

 

This is mandatory when the Technical contact does not have the required Equinix-registered username.

workPhoneCountryCode No string +44
      
 

Work phone country code of contact person. This is free text input.

 

Example: +571

 

It is recommended to include the work phone country code. 

workPhone Conditional string 0148211111  

Work phone number of contact person. This is free text input.

 

This is mandatory when the Technical contact does not have the required Equinix-registered username.

workPhonePrefToCall Conditional string MY_BUSINESS_HOURS

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls. This is mandatory for the Technical contact.

 

Call Preference - Description
NEVER - Does not take calls.

ANYTIME - Takes calls anytime. 

MY_BUSINESS_HOURS - Takes calls only during their business days from 9am to 5pm in their specified time zone. The body parameter 'workPhoneTimeZone' is mandatory to pass when this option is selected.

IBX_BUSINESS_HOURS - Takes calls only during the business hours of the IBX. 

 


Deprecated values

BUSINESS_HOURS - This value will be removed in the near future.

workPhoneTimeZone Conditional string Europe/London Click here for applicable values

This indicates the specific timezone of the Technical contact's business hours that follows the IANA time zone database names format. This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.

mobilePhoneCountryCode No string  +1  

Country code for the mobile phone number of the contact person. This is free text input.

 

Example: +571

mobilePhone No string 0123456789
     
 

Mobile phone number of contact person. This is free text input.

mobilePhonePrefToCall No string ANYTIME

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls on their mobile phone.

 

For description of applicable values, refer to description of body parameter 'workPhonePrefToCall'.

mobilePhoneTimeZone No string   Click here for applicable values

This indicates the specific timezone of the Technical contact's business hours that follows the IANA time zone database names format.

 

This should be included when 'MY_BUSINESS_HOURS' is selected for 'mobilePhonePrefToCall' and the mobile phone timezone differs from the work phone timezone. If 'mobilePhoneTimeZone' is not included, it will be assumed that both the work phone and mobile phone timezones are the same. 

 

{
  "successes": [
    {
      "ibxLocation": {
        "ibxTime": -7,
        "timezone": "America/New_York",
        "ibx": "AT2",
        "region": "AMER",
        "address1": "56 Marietta Street NW, 5th Floor",
        "city": "Atlanta",
        "state": "GA",
        "country": "United States of America",
        "zipCode": "30303",
        "cageDetails": [
          {
            "cage": "AT2:02:V050005-6-591",
            "cageUSID": "104937",
            "systemName": "AT2:02:VBMMR:INTERNAP NETWORK SERVICES CORP",
            "accountNumber": "109880",
            "cabinets": [
              {
                "cabinet": "V0106",
                "cabinetId": "AT2:02:V050005-6-591:V0106",
                "cabinetUSID": "104957",
                "assetNumber": "12955912"
              }
            ],
            "multiCabinet": false
          },
          {
            "cage": "AT2:0G:00EQ11",
            "cageUSID": "202298",
            "systemName": "AT2:0G:VBMMR:INTERNAP NETWORK SERVICES CORP",
            "accountNumber": "109880",
            "cabinets": [
              {
                "cabinet": "0110,0111"
              }
            ],
            "notes": [
              {
                "noteDescription": "Cabinet Numbers:0110,0111",
                "noteType": ""
              }
            ],
            "multiCabinet": true
          }
        ],
        "accessRestricted": false,
        "specialPrivilege": false
      },
      "response": {
        "OrderNumber": "1-190397565698"
      }
    }
  ]
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
successes

array

[objects]

  The cages and cabinets that were successfully registered for the work visit order, as requested.  
ibxLocation object   The IBX location information that consists of the IBX time in UTC, the IBX timezone by region/city, the IBX location code, the region of the IBX, the address of the IBX, the city of the IBX, the state of the IBX, the country of the IBX, the zipcode of the IBX, and the cage details information.
ibxTime integer -7

The IBX time based on Equinix internal system. 

 

You may ignore this.

timezone string America/New_York

The local timezone of the IBX based on Equinix internal system. 

 

This follows the IANA time zone database names format.

 

You may ignore this.

ibx string AT2

The IBX location code.

region string AMER

The region that the IBX is located.

 

Example: AMER- Americas (Brasil, Canada, and the United States)

address1 string 56 Marietta Street NW, 5th Floor

The address of the IBX.

city string Atlanta

The city that the IBX is located.

state string GA

The state that the IBX is located.

country string United States of America

The country that the IBX is located.

zipCode string 30303

The zip code or postal code of the IBX.

cageDetails

array

[objects]

  The cage details information consists of the specific cages and cabinets that the visitors can access.
cage string AT2:02:V050005-6-591

The ID of the cage that the visitors can access.

cageUSID string 104937

The Equinix internal cage ID reference.


You may ignore this. 

systemName string AT2:02:VBMMR:INTERNAP NETWORK SERVICES CORP

The Equinix internal system name for the cage that the visitors can access.

 

You may ignore this.

accountNumber string 109880

The customer account number related to the cage that the visitors can access.

cabinets

array

[objects]

  The cabinets information consists of the specific cabinets that the visitors can access.
cabinet string  V0106

The specific cabinet number of the cabinet that the visitors can access.

 

If value is 'ALL_CABINETS', visitors may visit all your cabinets in this cage. 

cabinetId string

AT2:02:V050005-6-591:V0106

The ID(s) of the cabinet(s) that the visitors can access.

cabinetUSID string 104957

Equinix internal cabinet ID reference.

 

You may ignore this.

assetNumber string 12955912 The asset number related to the cabinet.
notes

array

[objects]

 

Internal Equinix notes information about the cabinets.

 

You may ignore this.

noteDescription string Cabinet Numbers:0110,0111

Note description.

 

You may ignore this.

noteType string  

Note type.

 

You may ignore this.

multiCabinet boolean true

This indicates whether the visitors have permission to visit only the specified cabinet(s) in the cage, or all the cabinets in the cage. This is reflective of the request made that indicated either specific cabinet(s) access, or access to just the cage without specifying cabinets. 

 

If 'true', the visitors may visit all the customer's cabinets in the cage.

 

If 'false', the visitors may only visit the specified cabinet(s) in the cage. All other unspecified cabinets are off-limits.

accessRestricted boolean false

Indicates if this IBX access is restricted.

 

You may ignore this.

specialPrivilege boolean false

Indicates if this IBX requires special privilege.

 

You may ignore this.

response object   The order response information that consists of order reference ID, order number, and service request number. 
OrderNumber string 1-190397565698

The order number created after order is submitted. 

 

You will need to submit this number when requesting Smart Hands Cage Escort.

 

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

Schedule work visit (V2 Beta)

Step 1: Authenticate

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

 

Refer to Generating a Client ID and Client Secret key under Getting Started 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 3 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: 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, please request Security Access for them 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 Started section.

 

The following screenshots show sample curl requests based on the different scenarios.

 

Work Visit request without 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": [
          "janesmith123"
        ]
      }
    ]
  }
}
'

 

Work Visit request with 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": [
          "janesmith123",
          "jimsnow1"
        ]
      },
      {
        "firstName": "Da",
        "lastName": "Kine",
        "companyName": "Aloha Corp.",
        "details": [
          {
            "type": "EMAIL",
            "value": "dakine@aloha.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": [
        "janesmith123",
        "jimsnow1"
      ]
    },
    {
      "type": "TECHNICAL",
      "firstName": "Carmen",
      "lastName": "Santiago",
      "availability": "WORK_HOURS",
      "timezone": "America/New_York",
      "details": [
        {
          "type": "EMAIL",
          "value": "csantiago@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 if this cage is shared and you know 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 timezone) 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, please set up security access for them instead.

 

Provide a date and time (UTC timezone) 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]

janesmith123,

jimsnow1

 

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. 

firstName Conditional string Da  

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 Kine  

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 Aloha 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 dakine@aloha.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, please 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.

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.

 

Format: yyyy-MM-dd

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.
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 (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 timezone will also be referred from the user profile, unless otherwise included in this request. If they are a non-registered contact, their full name and contact details must be provided. To include more information such as the technical contact's availability or timezone, 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.

 

If providing the contact information for a registered contact object, the following body parameters are mandatory: registeredUsers, type. All other attributes passed in a registered contact object will be ignored.

 

If providing the contact information for a non-registered contact object, the following body parameters are mandatory: name, type, details. 

 

For more information on technical contact's work hours timezone, 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 contact. 

 

Type - Description

TECHNICAL - Technical contact. 

NOTIFICATION - Notification contact. 

registeredUsers Conditional

array

[strings]

janesmith123,

jimsnow1

 

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 Carmen

 

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 Santiago  

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 timezone. For a registered technical contact, their work hours is defaulted to the timezone in their user profile. If they would like to provide a different timezone, 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 timezone 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 timezone provided here will override the timezone in the user profile only for this order request, and does not replace the timezone 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 a phone number and an email address. Only one of each can be provided. Providing a mobile number is optional. 

 

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 csantiago@acme.com  

Value of the contact detail type. 

 

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.

 

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 Beta) 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.