https://developer.equinix.com
For Public Viewing
body: 

Legend        Don't like reading - How about a 1-minute video?       Ask us

 

What is Equinix Customer Portal?

Equinix Customer Portal (ECP) is a one-stop solution for customers to manage their users and orders, receive communications, and retrieve their asset and billing information. 

 

ECP offers the following capabilities:

  • User Management (Administration) - Managing different users and their permissions to IBXs and its operations.
  • Order Management - Ordering On- Site services, Shipments, Smart Hands, Trouble Tickets, Cross connects, Network Ports, and additional services, as well as modifying and cancelling these orders.
    • On-Site Services: Users can schedule on-site services such as work visits, security access, conference room reservations and data center tours.
    • Shipments: Users can schedule inbound and outbound shipments.
    • Smart Hands: Users can request cage assistance, custom installation and equipment troubleshooting via specific Smart Hands orders.
    • Trouble Ticket: Users can submit Trouble Tickets to resolve IBX issues.
    • Interconnection Products: Users can order Cross Connect installations and removals, as well as order Network Ports, Patch Cables, and Intra-Facility Cables.
    • Colocation Services: Users can order power and monitoring services for their infrastructure, environment and operations.
  • Communications - Receiving communications from Equinix about pending messages, orders, shipments and user registrations.
  • Asset Inventory Overview - Retrieving asset information.
  • Billing - Retrieving billing summary and downloading invoices.

 

Equinix products and services are offered to customers via digital channels like portal, mobile and REST APIs.

 

 

 

body: 

What are Equinix Customer Portal APIs?

The Equinix Customer Portal APIs are a collection of RESTful APIs that enable User and Order management of products and services offered by Equinix. (Refer API reference section or Catalog for more details.)

 


body: 

How do the Equinix Customer Portal APIs work?

Background

When a customer is on-boarded, they are provided with user credentials. 

 

 

The customer must use these credentials to connect to the Equinix Developer Platform to generate a Consumer key and Consumer secret, also known as client ID and client secret. 

 

 

The Consumer key and Consumer secret are essential for obtaining access and refresh tokens to authenticate API calls as described in the subsequent section

 

Refer to Generating a Client ID and Client Secret key under the Getting Started section for instructions on how to generate Consumer key and Consumer secret.

 

Equinix Customer Portal API Workflow

 

 

Authorization flow:

Step 1  - Request access and refresh token information by calling the Equinix OAuth API (/oauth2/v1/token) with the Consumer key, Consumer secret, and user credentials. 

 

 

Refer to Requesting Access and Refresh tokens under the Getting Started for instructions on how to obtain an Authorization Token.

 

Step 2  - The API gateway makes an OAuth2 call to the identity provider using the submitted credentials.

 

Step 3  - The identity provider returns an OAuth2 access token to the API gateway.

 

Step 4  - The API gateway sends back the authorization token details to the customer.

 

API Request flow:

Step 5  - The customer submits an API request with the obtained authorization token and respective API request payload.

Refer to the How-to Guide section for instructions on how to use Equinix Customer Portal APIs.

 

Step 6  - API gateway validates the request and calls the relevant API.

 

Step 7  - The response is received by the API gateway.

 

Step 8  - The response is sent back to the customer.

 


body: 

How-to Guide for ECP use cases

Learn how to perform a variety of functions using ECP APIs!

 

To use these APIs, the user must have the required permissions for the specific IBX locations. If you are unaware of your user permissions, contact your Master Administrator. 

 

Order Management

​Create a Trouble Ticket order

  • Mandatory permission: Trouble Ticket, under the Administration & Ordering permission catalog
    • Additional permission that may be required: View Install Base, under the Install Base permission catalog (if you want to include an asset ID number and need to retrieve it)

 

Create a Smart Hands order

  • Mandatory permission: Smart Hands & Accessories, under the Administration & Ordering permission catalog
    • Additional permission that may be required: IBX Access Services, under the Administration & Ordering permission catalog (if you need to schedule a Work Visit order for a Cage Access Escort Smart Hands order)
    • Additional permission that may be required: Shipments, under the Administration & Ordering permission catalog (if you need to schedule an Inbound Shipping order for an Unpack Shipments or Locate Packages Smart Hands order)
    • Additional permission that may be required: View Install Base, under the Install Base permission catalog (if you need to retrieve the serial number of a cross connect for a Patch Cable Installation or Patch Cable Removal Smart Hands order)

 

Create a Cross Connect order

  • Mandatory permission: Cross Connect & Intra-Facility Cables, under the Administration & Ordering permission catalog
    • Additional permission that may be required: View Install Base, under the Install Base permission catalog (if you need to retrieve the asset ID number for a cross connect removal)

 

Schedule On-Site Services

  • Mandatory permission: IBX Access Services, under the Administration & Ordering permission catalog

 

Schedule Shipments

  • Mandatory permission: Shipments, under the Administration & Ordering permission catalog

 

Retrieve Order History

  • Mandatory permission: Any ordering permission.

 

Asset Inventory Overview

Retrieve your assets 

  • Mandatory permission: View Install Base, under the Install Base permission catalog

 

Report Management

Install Base Report

  • Mandatory permission: View Install Base, under the Install Base permission catalog

 

Billing

Download billing documents

  • Mandatory permission: Billing & Payments permission

 

 

 

 


body: 

Pre-requisites

  •   You have valid user credentials.
  •   You have been authorized to access the developer platform.
  •   You have been authorized permissions for orders and notifications by your Master Administrator.

body: 

Getting Started

Learn the fundamentals of Equinix APIs.

 


body: 

Generating Client ID and Client Secret key

To obtain your client ID (consumer key) and client secret key (consumer secret), you must register your app in the developer platform according to your preferred environment. 

1. Login to Equinix Developer Platform using your login credentials.

 

If you are unaware of your login credentials for Equinix Developer Platform, contact your local Equinix Service Desk.

 

2. After logging in, click on the My Apps section as shown below.

 

 

3. Click on the Create New App button.

 

 

4. You will need to name your app and then select the app type to be used, you can either create an app for the Sandbox or Production environment. Once you’re ready click on the Create App button.

 

The sandbox environment is only a test environment that mimics the production environment and creates simulated API responses. 

If you are not an existing API customer, send an email to api-support@equinix.com to gain access to Equinix sandbox.

 

 

5. You should now have your app listed in the My Apps section as shown below:

 

 

6. When you select the application, your Client ID ( Consumer Key) and Client Secret (Consumer Secret) will be revealed.

 

 


body: 

Requesting Access and Refresh tokens

Access Token Flow

The access token is used to exchange data with the Equinix APIs and the refresh token is used to request a new access token should the access token expire. You can obtain your access token by either using the password or client credentials grant type as shown in the sample curl commands below:

 

The client_credentials grant type is used by users who do not want to use their Equinix login credentials (user name and user password) in exchange for an access token, whereas the password grant type is for users who are less hesitant. 

 

Refer to https://oauth.net/2/grant-types/ for more information about the different grant types and their usage. 

 

Access token using password grant type

 

curl -X

POST 'https://api.equinix.com/oauth2/v1/token'

-H "content-type: application/json" 

-d '{

"grant_type": "password",

"user_name": "john.doe@example.com",

"user_password": "jd1@#$",

"client_id": "ABCDE12345",

"client_secret": "FGHIJ67890"

}'

 

Access token using client credentials grant type  (Recommended)

 

curl -X

POST 'https://api.equinix.com/oauth2/v1/token'

-H "content-type: application/json"

-d '{

"grant_type": "client_credentials",

"client_id": "ABCDE12345",

"client_secret": "FGHIJ67890"

}'

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example Applicable Values Description
grant_type Yes string password

"password"

"client_credentials"

Different ways to authorize access to resources. It indicates the type of grant to be presented in exchange for an access token.
user_name Yes string john.doe@example.com   The Equinix login username. This field is optional for client credentials grant type.
user_password Yes string jd1@#$   The Equinix login password. This field is optional for client credentials grant type.
client_id Yes string ABCDE12345   A special ID generated by the Equinix Developer Platform.
client_secret Yes string FGHIJ67890   A special key generated by the Equinix Developer Platform.
password_encoding No string md5-b64 "md5-b64"

An optional field for users who wish to encrypt their password when requesting an access token. Currently, only “md5-b64” hashing is supported. This field is only applicable to users who use password grant. 

 

 

Click here to learn how to encrypt your password using md5-b64 hashing.

 

 

Refer to Generating a Client ID and Client Secret key under the Getting Started section for instructions on how to create a client ID and client secret.

 

If you are unaware of your user credentials for the Equinix Developer Platform, contact your local Equinix Service Desk. 

 

Once authenticated, the respective token and timeout details will be sent to you as shown in the sample JSON responses below.

 

Sample response when using password grant type

 

{

    "access_token": "qwErtY8zyW1abcdefGHI",

    "token_timeout": "3600",

    "user_name": "john.doe@example.com",

    "token_type": "Bearer",

    "refresh_token": "zxcvbn1JKLMNOPQRSTU",

    "refresh_token_timeout": "5184000"

}

 

Refresh token details will only be sent to customers that use password grant.

 

Sample response when using client credentials grant type

 

{

    "access_token": "qwErtY8zyW1abcdefGHI",

    "token_timeout": "3600",

    "user_name": "john.doe@example.com",

    "token_type": "Bearer",

}

 

The description of the response payload is as follows:

 

Field Name Type Example Applicable Values Description
access_token string qwErtY8zyW1abcdefGHI   The authorization token to be used in subsequent API calls. 
token_timeout string 3600   The lifetime of an access token in seconds. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated.
user_name string john.doe@example.com   The Equinix login username.
token_type string Bearer

"Bearer"

The type of token. 
refresh_token string zxcvbn1JKLMNOPQRSTU   Access tokens have limited lifetimes. If your application needs access to an API beyond the lifetime of a single access token, you can obtain a refresh token. A refresh token allows your application to obtain new access tokens. This information is only applicable to "password" grant users. 
refresh_token_timeout string 5184000   The lifetime of a refresh token in seconds. For example, the value "5184000" denotes that the refresh token will expire in 60 days from the time the response was generated. This information is only applicable to "password" grant users.

 

To make a request to Equinix APIs, add the Authorization header to the HTTP request with the word "Bearer" prepended to the access token. For example with curl use,  -H "Authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Refresh Token Flow

You can use a valid refresh token to obtain new access tokens to be used in API calls. A refresh token is valid for 60 days. You must submit your Client ID, Client Secret and Refresh Token to obtain refresh access tokens as shown in the sample curl command below.

 

curl -X

POST 'https://api.equinix.com/oauth2/v1/refreshaccesstoken'

-H "content-type: application/json" 

-d '{

"client_id": "ABCDE12345",

"client_secret": "FGHIJ67890",

"refresh_token": "zxcvbn1JKLMNOPQRSTU"

}'

 

The description of the body parameters are as follows:

 

Body Parameter Name Mandatory Type Example Applicable Values Description
client_id Yes string ABCDE12345   A special ID generated by the Equinix Developer Platform.
client_secret Yes string FGHIJ67890   A special key generated by the Equinix Developer Platform.
refresh_token Yes string zxcvbn1JKLMNOPQRSTU   A refresh token allows your application to obtain a new access token and is provided in the response payload of an access token call.

 

Once requested, a new set of access token, refresh token, and timeout details will be sent to you.

 

{

    "access_token": "1abcdefGHIqwErtY8zyW",

    "token_timeout": "3600",

    "user_name": "john.doe@example.com",

    "token_type": "Bearer",

    "refresh_token": "1JKLMNOPQRSTUzxcvbn",

    "refresh_token_timeout": "5184000"

}

 

Refer to Generating a Client ID and Client Secret key under the Getting Started section for instructions on how to create a client ID and client secret.

 


body: 

Order Management


body: 

How to create a Trouble Ticket order


body: 
How to create a trouble ticket?

 

 


body: 
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. 

 


body: 
Step 2: Get Trouble ticket Details

 

To get trouble ticket details, the user must have 'Trouble Ticket' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

2a) Get Trouble ticket Types

 

Retrieve all the trouble ticket categories supported by Equinix.

 

Use this API to identify the specific problem code and service name. Service name information is only mandatory for Managed Services problem codes. 

 

Refer to Get Troubleticket Types under the API Reference section for instructions on how to get all available trouble ticket types. You may skip this step if you already know the trouble ticket type.  

 

2b) Get Location information (with or without a specific asset)

 

2bi) Get Asset ID and Location information (if a known specific asset is affected)

 

To use this method, the user must have 'View Install Base' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

Retrieve the asset ID and location information of the affected asset. Providing the asset ID number can help expedite the processing time of your request.

 

Use this API to get the specific asset ID number of the affected asset, and the corresponding IBX location information where the issue occurred, such as cage ID number, cabinet ID number (optional), cage account number, and IBX location ID.

 

Refer to How to retrieve assets? under the How-to Guide for ECP use cases section for instructions on how to retrieve the asset and locations information. You may skip this step if you already know the asset and location information.

 

OR

 

2bii) Get Location Information (if there is no known specific asset)

 

Retrieve your IBX location information.

 

Use this API to get the specific IBX location information where the issue occurred, such as cage ID number, cabinet ID number (optional), cage account number, and IBX location ID.

 

Refer to Get Troubleticket 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.

 


body: 
Step 3: Create Trouble ticket

Post Trouble ticket

POST /orders/troubleticket

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

 ibxLocation {ibx, cages [{cage, cabinets [...], accountNumber}]}, serviceDetails {incidentDateTime, problemCode, serviceName, assetNumber, callMeFromCage, additionalDetails}, attachments [{id, name}], customerReferenceNumber,  contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall, mobilePhoneTimeZone}, {contactType, userName}, {contactType, userName}]}

 

The Post troubleticket API creates a trouble ticket under a user with 'Trouble Ticket' 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 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 API.

 

The request indicates two scenarios: A trouble ticket for an issue under the 'Managed Services' Problem Category without additional information, attachments, or contacts,  and a trouble ticket for the same issue with additional information, attachments, and contacts.

 

The response indicates the order was successful and returned the order number.

 

Trouble ticket without additional information, attachment, or additional contacts

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

    "ibxLocation": {

    "ibx": "DB1",
    "cages": [
      {
        "cage": "DB1:0G:00EQ11-1",
        "accountNumber": "109921"
      }
    ]
  },

  "serviceDetails": {
    "incidentDateTime": "2019-07-02T03:00:24.311Z",
    "problemCode": "ms01",

    "serviceName": "Firewall Issue"
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "userName": "johndoe",

      "workPhonePrefToCall": "MY_BUSINESS_HOURS",

      "workPhoneTimeZone": "Europe/London"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

 

Trouble ticket with additional information, attachment, and additional contacts

 

Before creating an order with attachment, call the Post Attachment File under the API Reference section.

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

   "ibxLocation": {

    "ibx": "DB1",
    "cages": [
      {
        "cage": "DB1:0G:00EQ11-1",
        "cabinets": [
          "DB1:0G:00EQ11-1:0602"
        ],
        "accountNumber": "109921"
      }
    ]
  },
  "serviceDetails": {
    "incidentDateTime": "2019-07-02T03:00:24.311Z",
    "problemCode": "ms01",

    "serviceName": "Firewall Issue",

    "assetNumber": "12357987",
    "callMeFromCage": true,

    "needSupportFromASubmarineCableStationEngineer": false,

    "additionalDetails": "Refer to attachment."
  },

  "attachments": [

    {

      "id": "372ffa24-c5ae-48d9-886b-88932cd30c9b",

      "name": "AdditionalDetailsAttachment.docx"

    }

  ],

  "customerReferenceNumber": "TT072019-001",

  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@corporation.com",
      "workPhoneCountryCode": "+44",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",

      "workPhoneTimeZone": "Europe/London"
      "mobilePhoneCountryCode": "+1",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "MY_BUSINESS_HOURS",

      "mobilePhoneTimeZone": "Europe/London"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    },   

    {
      "contactType": "NOTIFICATION",
      "userName": "janesmith"
    }
  ]
}'

 

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 the cages information and IBX location code. 

ibx Yes string DB1  

The IBX location code.

 

E.g. AM1 is an IBX data centre in Amsterdam, Netherlands. 

cages Yes array[objects]    

Cages information consists of ID of cage, ID of cabinet, and cage account number.

 

Only 1 cage per order is currently being supported. Provide information for only 1 cage.

cage Yes string DB1:0G:00EQ11-1  

ID of the cage.

cabinets No array[strings] DB1:0G:00EQ11-1:0602  

ID of the cabinet.

 

If providing cabinet, provide only 1 cabinet ID. Only 1 cabinet is currently being supported per cage.

accountNumber Yes string 109921  

The cage account number of the customer.

serviceDetails Yes object   

 

Service details information consists of date and time of incident, problem category, problem code, a call from cage requirement, and any additional details. 

incidentDateTime Yes string 2019-07-02T03:00:24.311Z  

Date and time of the incident in the local IBX time.

 

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.

problemCode Yes string ms01

pwr01, pwr02,

cc01 to cc03,

env01 to env04,

hdw01,

net01, net02,

sec01, sec02,

sv01 to sv05,

ms01, ms04
ms05, ms06,

ms07, ms08,

ms12, ms13,

sk01.

Problem code. 

 

For detailed information on the different problem codes, refer to Get Troubleticket Types under the API Reference section for more information. 

 

If this is a 'Network' product Cross Connect, please change to the correct 'Network' problem code.

serviceName Conditional string Firewall Issue
 
Firewall Issue, 
VPN Issue, 
Load Balancer Issue,
DDoS Mitigation Issue,
Network Device Issue,
Storage Issue,
Backup to disk Issue, 
Backup to tape Issue, 
Missing Tape, 
Other,
Device Monitoring Issue,
OS Issue

The specific service name issue for Managed Services.

 

This field is mandatory if the problem code belongs to Managed Services issues (problem codes: ms01, ms04, ms05, ms06, ms07, ms08, ms12, ms13).

 

 

assetNumber No string 12357987  

The asset ID number of the asset experiencing an issue. Providing the asset number can help expedite the processing time of your request.

 

If you need to retrieve your asset ID number, refer to How to retrieve assets? under the How-to Guide for ECP use cases section.

callMeFromCage No boolean

true

true

false

This is a requirement for the Technical contact person to be called from the cage.

 

If 'true', the Technical contact person will be called.

 

If 'false', no one will be called.

 

Default: false

needSupportFromASubmarineCableStationEngineer Conditional boolean false

true

false

Requirement for submarine cable station engineer support.

 

This is mandatory for customers with Monet accounts.

 

If 'true', submarine cable station engineer support is required. 

 

If 'false', submarine cable station engineer support is not required. 

 

Default value: false

additionalDetails No  string Refer to attachment.  

Any additional details, including the serial number or cable ID, that will help Equinix resolve the issue readily. This is free text input.

 

This field can only be up to 4000 characters long.  

attachments No array[objects]    

An array containing the attachment details.

 

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.

id Conditional string 372ffa24-c5ae-48d9-886b-88932cd30c9b  

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

name Conditional string

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

 

Refer to Post Attachment File under the API Reference section for more information. 

customerReferenceNumber No string TT072019-001  

Customer's own reference number. 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.  

contacts Yes array[objects]  

 

Contacts 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. All three contacts are mandatory.

 

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

- Technical contact person: Person who Equinix can reach out to for technical clarifications. Only one Technical 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.

userName Yes string johndoe
      
 

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

 

E.g. If 'email' and 'workPhone' information is passed with 'userName' for Notification contact, this information will be ignored.

name Conditional string Jane Smith
      
 

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

email Conditional string janesmith@corporation.com
      
 

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

workPhoneCountryCode No string +44  

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

 

E.g.: +571

 

It is recommended to include the work phone country code.

workPhone Conditional string 9876543210  

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

workPhonePrefToCall Yes string MY_BUSINESS_HOURS

ANYTIME,

MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS,

NEVER

Availability of Technical contact person to take calls anytime, during their business hours, during the local IBX business hours, during general business hours, or never.

 

This is mandatory for the Technical contact.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'workPhoneTimeZone' is mandatory.

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.

 

E.g. Area/Location

 

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 MY_BUSINESS_HOURS

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls on their mobile phone anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'mobilePhoneTimeZone' should be provided if the mobile phone timezone differs from the work phone timezone.

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

 

E.g. Area/Location

 

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. 

 

{
    "OrderNumber": "1-188243137021"
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
OrderNumber string 1-188243137021 The order number created after the order is submitted. 

 

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

 


body: 

How to create a Smart Hands order


body: 
How to order a cage escort?

 

 


body: 
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. 

 


body: 
Step 2: Schedule a work visit

 

To schedule a work visit, the user must have 'IBX Access Services' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

Schedule a work visit and retrieve the order number.

Retrieve the order number after scheduling a work visit.

 

Refer to How to schedule a Work Visit? under the How-to Guide for ECP use cases section for instructions on how to schedule a work visit, or refer to How to retrieve order history? under the How-to Guide for ECP use cases section for instructions on how to retrieve an order number for a work visit that has already been scheduled. You may skip this step if you already have the work visit order number.

 


body: 
Step 3: Get Smart Hands Details

 

To get Smart Hands details, the user must have 'Smart Hands' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

3a) Get Smart Hands Types

Retrieve all the Smart Hands categories supported by Equinix.

 

Refer to Get Smarthands Types under the API Reference section for instructions on how to get all Smart Hands types. You may skip this step if you already know the Smart Hands type.  

 

3b) 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 Smarthands 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.

 


body: 
Step 4: Order a Cage Escort

POST Smarthands Cage Escort

POST /smarthands/cageEscort

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

 ibxLocation {ibx, cages [{cage, cabinets [...], accountNumber}]}, serviceDetails {workVisitOrderNumber, openCabinetForVisitor, supervisionReqForVisitor, durationVisit, scopeOfWork, needSupportFromASubmarineCableStationEngineer}, attachments [{id, name}], schedule{scheduleType, requestedStartDate, requestedCompletionDate}, customerReferenceNumber, purchaseOrder {purchaseOrderType, attachment {id, name}},  contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}, {contactType, userName}, {contactType, userName}]

 

The Post smarthands cageEscort API orders an IBX security escort for a visitor to access your cage after you have scheduled a work visit to said IBX. This can only be done by a user with 'Smart Hands' 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.

 

A work visit order number must be provided to order a Smarthands Cage Escort. If you have not raised a work visit order, refer to How to schedule a Work Visit? under the How-to Guide for ECP use cases section. If you have already raised a work visit order, but do not know the work visit order number, refer to How to retrieve order history? under the How-to Guide for ECP use cases section to retrieve your work visit order number. 

 

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

 

The request indicates two scenarios: A cage escort ordered without additional information, attachments, or contacts, and a cage escort ordered with additional information, attachments, and contacts.

 

The response indicates the order was successful and returned the order number.

 

Cage Escort without additional information, attachments, or contacts

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/cageEscort"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "workVisitOrderNumber": "1-19864326570532",
    "openCabinetForVisitor": true,
    "supervisionReqForVisitor": true,
    "durationVisit": "4 Hours",
    "scopeOfWork": "If staff from customer company is unable to attend, please continue to accompany the visitor."
  },
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "userName": "johndoe",
      "workPhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

 

Cage Escort with additional information, attachments, and contacts

 

Before creating an order with attachment, call the Post Attachment File under the API Reference section.

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/cageEscort"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "cabinets": [
          "AM1:0J:00JD11:0001"
        ],
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "workVisitOrderNumber": "1-19864326570532",
    "openCabinetForVisitor": true,
    "supervisionReqForVisitor": true,
    "durationVisit": "4 Hours",
    "scopeOfWork": "If staff from customer company is unable to attend, please continue to accompany the visitor.",
    "needSupportFromASubmarineCableStationEngineer": true
  },
  "attachments": [
    {
      "id": "fcb2k8763-2947-456e-8d68-f280753d60ba",
      "name": "WorkVisitInstructions.docx"
    }
  ],
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "customerReferenceNumber": "EQX-PO2019-08-001",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@corporation.com",
      "workPhoneCountryCode": "+44",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Europe/London",
      "mobilePhoneCountryCode": "+44",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "MY_BUSINESS_HOURS",
      "mobilePhoneTimeZone": "Europe/London"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "jillsnow"
    }
  ]
}'

 

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 the cages information and IBX. 

ibx Yes string AM1  

The IBX location code.

 

E.g. AM1 is an IBX data centre in Amsterdam, Netherlands. 

cages Yes array[objects]    

Cages information consists of ID of cage, ID of cabinet, and cage account number.

 

Only 1 cage per order is currently being supported. Provide information for only 1 cage.

cage Yes string AM1:0J:00JD11  

ID of the cage.

cabinets No array[strings] AM1:0J:00JD11:0001  

ID of the cabinet.

 

If providing cabinet, provide only 1 cabinet ID. Only 1 cabinet is currently being supported per cage.

accountNumber Yes string 126854  

The customer account number that is linked to the cage.

serviceDetails Yes object     Service details consist of work visit order number, requirement to open cabinet for visitor, requirement for supervised escort for visitor, duration of visit, and scope of work.
workVisitOrderNumber Yes string 1-19864326570532  

The order number of the work visit request. This is free text input.

 

This number is provided after a work visit is scheduled.

 

This field can only be up to 50 characters long.

 

If you have not raised a work visit order, refer to How to schedule a Work Visit? under the How-to Guide for ECP use cases section.

 

If you have already raised a work visit order, but do not know the work visit order number, refer to How to retrieve order history? under the How-to Guide for ECP use cases section to retrieve your work visit order number. 

openCabinetForVisitor Yes boolean true

true, 

false

The requirement for Equinix to open the secured cabinet for the visitor. 

 

If 'true', Equinix will open the cabinet.

 

If 'false', cabinet will remain locked.

supervisionReqForVisitor Yes boolean true

true, 

false

The requirement for Equinix to provide an escort to for the visitor.

 

If 'true', Equinix will provide an escort. In this case, only 'SCHEDULED_MAINTENANCE' in parameter 'scheduleType' is allowed.

 

If 'false', an Equinix escort is not required. Any schedule type is allowed.

 

If a visitor escort is required, only the schedule type 'SCHEDULED_MAINTENANCE' and its corresponding scheduling parameters should be applied.

durationVisit Yes string 4 Hours 30 Minutes,
60 Minutes,
90 Minutes,
2 Hours,
2 Hours 30 Minutes,
3 Hours,
3 Hours 30 Minutes,
4 Hours
Duration of visit.
scopeOfWork Yes string If staff from customer company is unable to attend, please continue to accompany the visitor.  

A detailed description of the scope of work. This is free text input.

 

This field can only be up to 4000 characters long.

needSupportFromASubmarineCableStationEngineer Conditional boolean true

true,

false

Requirement for submarine cable station engineer support.

 

This is mandatory for customers with Monet accounts.

 

If 'true', submarine cable station engineer support is required. 

 

If 'false', submarine cable station engineer support is not required. 

 

Default value: false

attachments No array[objects]    

An array containing the attachment details.

 

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.

 

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

id Conditional string

fcb2k8763-2947-456e-

8d68-f280753d60ba

 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

name Conditional string CageEscortServiceDetailsPhoto.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.

 

Refer to Post Attachment File under the API Reference section for more information. 

schedule Yes object    

Schedule information that includes schedule type, and the starting and ending dates and times for the schedule.

scheduleType Yes string SCHEDULED_MAINTENANCE

STANDARD,

EXPEDITED,

SCHEDULED_MAINTENANCE

Define your preferred scheduling type.

 

Schedule Types 
 

STANDARD: Request will be processed in the standard turnaround time. Most requests are completed within 24 to 72 hours pending your install base readiness. Requests will be processed in the order they were received, unless they are expedited.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are not required. 

 

EXPEDITED: Request will be completed within the next 2 to 24 hours. Additional Smart Hands fees may apply. Schedule a time in the current local time of the IBX you selected. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameter 'requestedCompletionDate' is required. 

 

SCHEDULED_MAINTENANCE: Request will be scheduled as Customer Requested Maintenance. Additional Smart Hands fees may apply if your scheduled time is less than 24 hours from when the order is submitted. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are required.  

 

If a visitor escort is required, the only applicable schedule type is 'SCHEDULED_MAINTENANCE'.

 

If a visitor escort is not required, any of these schedules type may be applied.

requestedStartDate Conditional string 2019-08-30T22:00:49.776Z  

Requested start date and time.

 

If 'STANDARD' or 'EXPEDITED' schedule type, this parameter is not required.

 

If 'SCHEDULED_MAINTENANCE' schedule type, 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.

 

If a visitor escort is required, this parameter should adhere to schedule type, 'SCHEDULED_MAINTENANCE'.

requestedCompletionDate Conditional string 2019-08-31T22:00:49.776Z  

Requested end date and time.

 

If 'STANDARD' schedule type, this parameter is not required.

 

If 'EXPEDITED'  or 'SCHEDULED_MAINTENANCE' schedule type, 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.

 

Expedited scheduling date should not be less than IBX local time + 2 hours, and no more than IBX local time + 24 hours.

 

Scheduled maintenance scheduling should not be less than 24 hours from when the order is submitted. Otherwise, additional Smart Hands fees may apply.

 

If a visitor escort is required, this parameter should adhere to schedule type, 'SCHEDULED_MAINTENANCE'.

customerReferenceNumber No string EQX-PO2019-08-001  

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

 

This can be a Purchase Order number or 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. 

 

If you do not know your account's PO bearing status, refer to Get Smarthands Locations under the API Reference section.

purchaseOrderType Conditional string EXEMPTED

EXISTING,

EXEMPTED

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

 

However, only existing and exempted purchase order types are currently being 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, and a purchase order number is not required. 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 Conditional 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.

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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. All three contacts are mandatory.

 

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

- Technical contact person: Person who Equinix can reach out to for technical clarifications. Only one Technical 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.

userName Yes string

johndoe

      

 

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

 

E.g. If 'email' and 'workPhone' information is passed with 'userName' for Notification contact, this information will be ignored.

name Conditional string Jane Smith  

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

email Conditional string janesmith@corporation.com
      
 

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

workPhoneCountryCode No string +44
      
 

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

 

E.g.: +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 an active or locked Equinix-registered username.

workPhonePrefToCall Yes string ANYTIME

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

This is mandatory for the Technical contact.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'workPhoneTimeZone' is mandatory.

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.

 

E.g. Area/Location

 

This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.

mobilePhoneCountryCode No string  +1  

Country code for mobile phone number of 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 MY_BUSINESS_HOURS

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls on their mobile phone anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'mobilePhoneTimeZone' is mandatory. 

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

 

E.g. Area/Location

 

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. 

 

{
  "OrderNumber": "1-19876653568916"
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
OrderNumber string 1-19876653568916 The order number created after order is submitted. 

 

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

 


body: 
How to order equipment installation?

 

 


body: 
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. 

 


body: 
Step 2: Get Smart Hands Details

 

To get Smart Hands details, the user must have 'Smart Hands' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

2a) Get Smart Hands Types

Retrieve all the Smart Hands categories supported by Equinix.

 

Refer to Get Smarthands Types under the API Reference section for instructions on how to get all Smart Hands types. You may skip this step if you already know the Smart Hands type. 

 

2b) 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 Smarthands 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.

 


body: 
Step 3: Order Equipment Installation

POST Smarthands Equipment Install

POST /smarthands/equipmentInstall

 Method

 POST

 URL or End Point

 /v1/orders/smarthands/equipmentInstall

 Headers

 Authorization, Content-Type

 Query Parameters

 Not applicable

 Body

 ibxLocation {ibx, cages [{cage, cabinets[...], accountNumber}]}, serviceDetails {deviceLocation, elevationDrawingAttached, installationPoint, installedEquipmentPhotoRequired, mountHardwareIncluded, patchDevices, patchingInfo, powerItOn, scopeOfWork, needSupportFromASubmarineCableStationEngineer}, attachments [{id, name}], schedule {scheduleType, requestedStartDate, requestedCompletionDate}, customerReferenceNumber, purchaseOrder {purchaseOrderType, attachment {id, name}},  contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}, {contactType, userName}]

 

The Post smarthands equipmentInstall API orders equipment installation per customer specifications by an Equinix IBX Technician. This can only be done by a user with 'Smart Hands' 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 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 API.

 

The request indicates two scenarios: An equipment installation ordered without additional information, attachments, or contacts, and an equipment installation ordered with additional information, attachments, and contacts. 

 

The response indicates the order was successful and returned the order number.

 

Equipment Installation without additional information, attachments, or contacts

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/equipmentInstall"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

    "ibxLocation": {

    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "accountNumber": "126854"
      }
    ]
  },

  "serviceDetails": {
    "deviceLocation": "DHL tracking no. 1039 5739 92",
    "elevationDrawingAttached": false,
    "installationPoint": "Front and center.",

    "patchDevices": true,

    "patchingInfo": "When patching use the next available port, but maintain a symmetrical appearance.",

    "powerItOn": true,

    "mountHardwareIncluded": true,
    "installedEquipmentPhotoRequired": true,
    "scopeOfWork": "When installing make sure wires are all labeled."
  },

  "schedule": {

    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },

  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"

    },
    {
      "contactType": "TECHNICAL",

      "userName": "johndoe",
      "workPhonePrefToCall": "ANYTIME"

    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

 

Equipment Installation with additional information, attachments, and contacts

 

Before creating an order with attachment, call the Post Attachment File under the API Reference section.

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/equipmentInstall"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "cabinets": [
          "AM1:0J:00JD11:0001"
        ],
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "deviceLocation": "DHL tracking no. 1039 5739 92",
    "elevationDrawingAttached": true,
    "installationPoint": "Front and center.",
    "patchDevices": true,
    "patchingInfo": "When patching use the next available port, but maintain a symmetrical appearance.",
    "powerItOn": true,
    "mountHardwareIncluded": true,
    "installedEquipmentPhotoRequired": true,
    "scopeOfWork": "When installing make sure wires are all labeled.",
    "needSupportFromASubmarineCableStationEngineer": true
  },
  "attachments": [
    {
      "id": "fcb4a673-6308-456e-8f83-f745501d60ba",
      "name": "Elevation drawing.docx"
    }
  ],
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "customerReferenceNumber": "EQX-PO2019-08-001",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@corporation.com",
      "workPhoneCountryCode": "+44",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Europe/London",
      "mobilePhoneCountryCode": "+44",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "MY_BUSINESS_HOURS",
      "mobilePhoneTimeZone": "Europe/London"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "janesmith"
    }
  ]
}'

 

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 the cages information and IBX. 

ibx Yes string AM1  

The IBX location code.

 

E.g. AM1 is an IBX data centre in Amsterdam, Netherlands. 

cages Yes array[objects]    

Cages information consists of ID of cage, ID of cabinet, and cage account number.

 

Only 1 cage per order is currently being supported. Provide information for only 1 cage.

cage Yes string AM1:0J:00JD11  

ID of the cage.

cabinets No array[strings] AM1:0J:00JD11:0001  

ID of the cabinet.

 

If providing cabinet, provide only 1 cabinet ID. Only 1 cabinet is currently being supported per cage.

accountNumber Yes string 126854  

The customer account number that is linked to the cage.

serviceDetails Yes object     Service details consist of device location, indication if elevation drawing is attached, installation point instruction, patching requirement and information, power requirement, mount hardware inclusion, installation photo requirement, and scope of work information. 
deviceLocation Yes string DHL tracking no. 1039 5739 92  

Device location details from the customer such as equipment location, the inbound shipment number, or the courier name and tracking number. This is free text input.

 

This field can only be up to 200 characters long.

elevationDrawingAttached Yes boolean false

true, 

false

An indication that elevation drawing is attached.

 

If 'true', elevation drawing is attached.

 

If 'false', there is no attachment. 

installationPoint Yes string Front and center.

 

Instructions for specific installation point in the rack. This is free text input.

 

This field can only be up to 200 characters long.

patchDevices Yes boolean true

true, 

false

A request for patching between devices.

 

If 'true', patching is required between devices, and "patchingInfo" must be provided.

 

If 'false', patching is not required between devices. 

patchingInfo Conditional string When patching use the next available port, but maintain a symmetrical appearance.  

Instructions for specific patching information such as port, etc. This is free text input.

 

This field can only be up to 200 characters long.

 

This is mandatory information when patching is required. 

powerItOn Yes boolean true

true, 

false

A request to power on the equipment upon installation.

 

If 'true', it will be powered on.

 

If 'false', it will remain off.

mountHardwareIncluded Yes boolean true

true, 

false

An indication that mounting hardware is already included for the equipment installation.

 

If 'true', mounting hardware is already included.

 

If 'false', mounting hardware is not included.

installedEquipmentPhotoRequired Yes boolean true

true, 

false

A request for photos to be provided once the equipment installation is completed.

 

If 'true', photos will be provided.

 

If 'false', photos will not be provided.

scopeOfWork Yes string When installing make sure wires are all labeled.  

A detailed description of the scope of work. This is free text input.

 

This field can only be up to 4000 characters long.

needSupportFromASubmarineCableStationEngineer Conditional boolean true

true, 

false

Requirement for submarine cable station engineer support.

 

This is mandatory for customers with Monet accounts.

 

If 'true', submarine cable station engineer support is required. 

 

If 'false', submarine cable station engineer support is not required. 

 

Default value: false

attachments No array[objects]    

An array containing the attachment details.

 

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.

 

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

id Conditional string

fcb2k8763-2947-456e-

8d68-f280753d60ba

 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

name Conditional string Elevation drawing.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.

 

Refer to Post Attachment File under the API Reference section for more information. 

schedule Yes object     Schedule information that includes schedule type, and the starting and ending dates and times for the schedule.
scheduleType Yes string SCHEDULED_MAINTENANCE

STANDARD,

EXPEDITED,

SCHEDULED_MAINTENANCE

Define your preferred scheduling type.

 

Schedule Types 
 

STANDARD: Request will be processed in the standard turnaround time. Most requests are completed within 24 to 72 hours pending your install base readiness. Requests will be processed in the order they were received, unless they are expedited.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are not required. 

 

EXPEDITED: Request will be completed within the next 2 to 24 hours. Additional Smart Hands fees may apply. Schedule a time in the current local time of the IBX you selected. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameter 'requestedCompletionDate' is required. 

 

SCHEDULED_MAINTENANCE: Request will be scheduled as Customer Requested Maintenance. Additional Smart Hands fees may apply if your scheduled time is less than 24 hours from when the order is submitted. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are required.  

requestedStartDate Conditional string 2019-08-30T22:00:49.776Z  

Requested start date and time.

 

If 'STANDARD' or 'EXPEDITED' schedule type, this parameter is not required.

 

If 'SCHEDULED_MAINTENANCE' schedule type, 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.

requestedCompletionDate Conditional string 2019-08-31T22:00:49.776Z  

Requested end date and time.

 

If 'STANDARD' schedule type, this parameter is not required.

 

If 'EXPEDITED'  or 'SCHEDULED_MAINTENANCE' schedule type, 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.

 

Expedited scheduling date should not be less than IBX local time + 2 hours, and no more than IBX local time + 24 hours.

 

Scheduled maintenance scheduling should not be less than 24 hours from when the order is submitted. Otherwise, additional Smart Hands fees may apply.

customerReferenceNumber No string EQX-PO2019-08-001  

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

 

This can be a Purchase Order number or 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. 

 

If you do not know your account's PO bearing status, refer to Get Smarthands Locations under the API Reference section.

purchaseOrderType Conditional string EXEMPTED

EXISTING,

EXEMPTED

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

 

However, only existing and exempted purchase order types are currently being 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, and a purchase order number is not required. 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 Conditional 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.

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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. All three contacts are mandatory.

 

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

- Technical contact person: Person who Equinix can reach out to for technical clarifications. Only one Technical 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.

userName Yes string johndoe
      
 

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

 

E.g. If 'email' and 'workPhone' information is passed with 'userName' for Notification contact, this information will be ignored.

name Conditional string Jane Smith  

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

email Conditional string janesmith@corporation.com
      
 

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

workPhoneCountryCode No string +44
      
 

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

 

E.g.: +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 an active or locked Equinix-registered username.

workPhonePrefToCall Yes string ANYTIME

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

This is mandatory for the Technical contact.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'workPhoneTimeZone' is mandatory.

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.

 

E.g. Area/Location

 

This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.

mobilePhoneCountryCode No string  +1  

Country code for mobile phone number of 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 MY_BUSINESS_HOURS

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls on their mobile phone anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'mobilePhoneTimeZone' is mandatory. 

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

 

E.g. Area/Location

 

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. 

 

{
  "OrderNumber": "1-190986534844"
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
OrderNumber string 1-190986534844 The order number created after order is submitted. 

 

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

 


body: 
How to order a patch cable installation?

 

 


body: 
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. 

 


body: 
Step 2: Get Smart Hands Details

 

To get Smart Hands details, the user must have 'Smart Hands' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

2a) Get Smart Hands Types

Retrieve all the Smart Hands categories supported by Equinix.

 

Refer to Get Smarthands Types under the API Reference section for instructions on how to get all Smart Hands types. You may skip this step if you already know the Smart Hands type. 

 

2b) 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 Smarthands 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.

 


body: 
Step 3: Get Connection Details

 

To get the serial number of the connection, the user must have 'View Install Base' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

Retrieve the serial number of the connection.

 

Use this API to determine the serial number of the cross connection for the patch cable installation.

 

Refer to How to retrieve assets? under the How-to Guide for ECP use cases section for instructions on how to retirieve the cross connect serial number. You may skip this step if you already have the serial number.

 

If you cannot find the serial number of the cross connect, you should use "Serial # Not Found" as your serial number.

 


body: 
Step 4: Order Patch Cable Installation

POST Smarthands Patch Cable Install

POST /smarthands/patchCableInstall

 Method

 POST

 URL or End Point

 /v1/orders/smarthands/patchCableInstall

 Headers

 Authorization, Content-Type

 Query Parameters

 Not applicable

 Body

 ibxLocation {ibx, cages [{cage, cabinets[...], accountNumber}]}, serviceDetails {crossConnects [{serialNumber, deviceCabinet, deviceConnectorType, deviceDetails, devicePort, scopeOfWork, lightLinkVerification, needSupportFromASubmarineCableStationEngineer}]}, attachments [{id, name}], schedule {scheduleType, requestedStartDate, requestedCompletionDate}, customerReferenceNumber, purchaseOrder {purchaseOrderType, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}, {contactType, userName}]

 

The Post smarthands patchCableInstall API orders patch cable installations per customer specifications by an Equinix IBX Technician. This can only be done by a user with 'Smart Hands' 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 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 API.

 

The request indicates two scenarios: a patch cable installation ordered without additional information, attachments, or contacts, and a patch cable installation ordered with additional information, attachments, and contacts. 

 

The response indicates the order was successful and returned the order number.

 

Patch Cable Installation without additional information, attachments, or contacts

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/patchCableInstall"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "cabinets": [
          "AM1:0J:00JD11:0001"
        ],
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "crossConnects": [
      {
        "serialNumber": "123456789",
        "deviceCabinet": "501",
        "deviceConnectorType": "FC",
        "deviceDetails": "Router1",
        "devicePort": "Next Available"
      }
    ]
  },
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "userName": "johndoe",
      "workPhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

 

Patch Cable Installation with additional information, attachments, and contacts

 

Before creating an order with attachment, call the Post Attachment File under the API Reference section.

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/patchCableInstall"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "cabinets": [
          "AM1:0J:00JD11:0001"
        ],
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "crossConnects": [
      {
        "serialNumber": "123456789",
        "deviceCabinet": "501",
        "deviceConnectorType": "FC",
        "deviceDetails": "Router1",
        "devicePort": "Next Available",
        "scopeOfWork": "Refer to attachment for further instruction.",
        "lightLinkVerification": true,
        "needSupportFromASubmarineCableStationEngineer": true
      }
    ]
  },
  "attachments": [
    {
      "id": "fcb4a673-6308-456e-8f83-f745501d60ba",
      "name": "PatchCabelInstallationInstruction.docx"
    }
  ],
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "customerReferenceNumber": "EQX-PO2019-08-001",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@corporation.com",
      "workPhoneCountryCode": "+44",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Europe/London",
      "mobilePhoneCountryCode": "+44",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "MY_BUSINESS_HOURS",
      "mobilePhoneTimeZone": "Europe/London"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "janesmith"
    }
  ]
}'

 

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 the cages information and IBX. 

ibx Yes string AM1  

The IBX location code.

 

E.g. AM1 is an IBX data centre in Amsterdam, Netherlands. 

cages Yes array[objects]    

Cages information consists of ID of cage, ID of cabinet, and cage account number.

 

Only 1 cage per order is currently being supported. Provide information for only 1 cage.

cage Yes string AM1:0J:00JD11  

ID of the cage.

cabinets Yes array[strings] AM1:0J:00JD11:0001  

ID of the cabinet.

 

Only 1 cabinet per order is currently being supported. Provide information for only 1 cabinet.

accountNumber Yes string 126854  

The customer account number that is linked to the cage.

serviceDetails Yes object      Service details consists of cross connections information.
crossConnects Yes array[objects]    

Cross connections information consisting of the cross connection details due for patch cable installations.

serialNumber Yes string 123456789

Serial # Not Found

The serial number of the cross connect for the desired patch cable installation. 

 

If you are unsure of the serial number of the cross connection, refer to How to retrieve assets? under the How-to Guide for ECP use cases section for instructions on how to retrieve the serial number.

 

If you cannot find the serial number of the cross connect, you should use "Serial # Not Found" as your serial number.

deviceCabinet Yes string 501  

Cabinet where the device for patch cable installation is located. This is free text input. 

 

In Smart Hands Patch Cable Installation or Removal, the cabinet number, which can be derived from the cabinet ID, can be passed as the value for parameter 'deviceCabinet'. ID of the cabinet consists of {cage ID}:{cabinet number}. 

 

Refer to Get Smarthands Locations under the API Reference section for instructions on how to retrieve the cabinet number of your preferred device cabinet. 

deviceConnectorType Yes string FC

 

The connector type for the patch cable. This is free text input. 

deviceDetails Yes string Router1

 

The details of the device. This is free text input. 

devicePort Yes string Next Available  

The port number to install the patch cable. This is free text input. 

scopeOfWork No string Refer to attachment for further instruction. 

 

A detailed description of the scope of work. This is free text input.

 

This field can only be up to 4000 characters long.

lightLinkVerification No boolean true

true, 

false

This indicates if you would like a light reading provided and tx/rx verification after the cross connect is completed. In order to verify the correct transmit/receive alignment, please ensure your Z-Side Cross Connect Partner has their end fully extended to their equipment and their port is enabled. A separate billable activity will be created.

 

If 'true', light link verification will be provided and additional fees will apply.

 

If 'false', light link verification will not be provided.

 

Default value: false.

needSupportFromASubmarineCableStationEngineer Conditional boolean true

true, 

false

Requirement for submarine cable station engineer support.

 

This is mandatory for customers with Monet accounts.

 

If 'true', submarine cable station engineer support is required. 

 

If 'false', submarine cable station engineer support is not required. 

 

Default value: false

attachments No array[objects]    

An array containing the attachment details.

 

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.

 

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

id Conditional string

fcb2k8763-2947-456e-

8d68-f280753d60ba

 

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.

 

Refer to Post Attachment File under the API Reference section for more information.

name Conditional string PatchCabelInstallationInstruction.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.

 

Refer to Post Attachment File under the API Reference section for more information.

schedule Yes object     Schedule information that includes schedule type, and the starting and ending dates and times for the schedule.
scheduleType Yes string SCHEDULED_MAINTENANCE

STANDARD,

EXPEDITED,

SCHEDULED_MAINTENANCE

Define your preferred scheduling type.

 

Schedule Types 
 

STANDARD: Request will be processed in the standard turnaround time. Most requests are completed within 24 to 72 hours pending your install base readiness. Requests will be processed in the order they were received, unless they are expedited.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are not required. 

 

EXPEDITED: Request will be completed within the next 2 to 24 hours. Additional Smart Hands fees may apply. Schedule a time in the current local time of the IBX you selected. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameter 'requestedCompletionDate' is required. 

 

SCHEDULED_MAINTENANCE: Request will be scheduled as Customer Requested Maintenance. Additional Smart Hands fees may apply if your scheduled time is less than 24 hours from when the order is submitted. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are required.  

requestedStartDate Conditional string 2019-08-30T22:00:49.776Z  

Requested start date and time.

 

If 'STANDARD' or 'EXPEDITED' schedule type, this parameter is not required.

 

If 'SCHEDULED_MAINTENANCE' schedule type, 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.

requestedCompletionDate Conditional string 2019-08-31T22:00:49.776Z  

Requested end date and time.

 

If 'STANDARD' schedule type, this parameter is not required.

 

If 'EXPEDITED'  or 'SCHEDULED_MAINTENANCE' schedule type, 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.

 

Expedited scheduling date should not be less than IBX local time + 2 hours, and no more than IBX local time + 24 hours.

 

Scheduled maintenance scheduling should not be less than 24 hours from when the order is submitted. Otherwise, additional Smart Hands fees may apply.

customerReferenceNumber No string EQX-PO2019-08-001  

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

 

This can be a Purchase Order number or 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.

 

If you do not know your account's PO bearing status, refer to Get Smarthands Locations under the API Reference section.

purchaseOrderType Conditional string EXEMPTED

EXISTING,

EXEMPTED

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

 

However, only existing and exempted purchase order types are currently being 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, and a purchase order number is not required. 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 Conditional 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.

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.

 

Refer to Post Attachment File under the API Reference section for more information.

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.

 

Refer to Post Attachment File under the API Reference section for more information.

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. All three contacts are mandatory.

 

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

- Technical contact person: Person who Equinix can reach out to for technical clarifications. Only one Technical 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.

userName Yes string johndoe  

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

 

E.g. If 'email' and 'workPhone' information is passed with 'userName' for Notification contact, this information will be ignored.

name Conditional string Jane Smith  

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

email Conditional string janesmith@corporation.com        

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

workPhoneCountryCode No string +44        

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

 

E.g.: +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 an active or locked Equinix-registered username.

workPhonePrefToCall Conditional string ANYTIME

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

This is mandatory for the Technical contact.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'workPhoneTimeZone' is mandatory.

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.

 

E.g. Area/Location

 

This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.

mobilePhoneCountryCode No string  +1  

Country code for mobile phone number of 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 MY_BUSINESS_HOURS

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls on their mobile phone anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'mobilePhoneTimeZone' is mandatory. 

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

 

E.g. Area/Location

 

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. 

 

{
  "OrderNumber": "1-190986534844"
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
OrderNumber string 1-190986534844 The order number created after order is submitted. 

 

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

 


body: 
How to order inbound shipment unpacking and packaging disposal?

 

 

 


body: 
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. 

 


body: 
Step 2: Schedule an inbound shipment

 

To schedule an inbound shipment, the user must have 'Shipments' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

Schedule an inbound shipment and retrieve the order number

Retrieve the inbound shipment order number after scheduling an inbound shipment.

 

Refer to How to schedule an Inbound Shipment? under How to schedule shipments section of the How-to Guide for ECP use cases for instructions on how to schedule an inbound shipment, or refer to How to retrieve order history? under the How-to Guide for ECP use cases section for instructions on how to retrieve an order number for an inbound shipment that has already been scheduled. You may skip this step if you already have the inbound shipment order number.

 


body: 
Step 3: Get Smart Hands Details

 

To get Smart Hands details, the user must have 'Smart Hands' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

3a) Get Smart Hands Types

Retrieve all the Smart Hands categories supported by Equinix.

 

Refer to Get Smarthands Types under the API Reference section for instructions on how to get all Smart Hands types. You may skip this step if you already know the Smart Hands type.  

 

3b) 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 Smarthands 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.

 


body: 
Step 4: Order inbound shipment unpacking and packaging disposal

POST Smarthands Shipment Unpack

POST /smarthands/shipmentUnpack

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

 ibxLocation {ibx, cages [{cage, accountNumber}]}, customerReferenceNumber, purchaseOrder {purchaseOrderType, attachment {id, name}}, serviceDetails {estimatedDateTime, shipmentDetails inboundType, carrierName, otherCarrierName, noOfBoxes,isOverSized, trackingNumber [...]}, deliverToCage, inboundRequestDescription, attachments [{id, name}], contacts [{contactType, userName},{contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}, {contactType, userName}, {contactType,userName}]

 

The Post smarthands shipmentUnpack API requests inbound shipment unpacking and packaging disposal. This can only be done by a user with 'Smart Hands' 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.

 

An inbound shipment order number must be provided to order a Smarthands Shipment Unpack. If you have not raised an inbound shipment order, refer to How to schedule an inbound shipment? under the How-to Guide for ECP use cases section. If you have already raised an inbound shipment order, but do not know the inbound shipment order number, refer to How to retrieve order history? under the How-to Guide for ECP use cases section to retrieve your inbound shipment order number. 

 

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

 

The request indicates two scenarios: A shipment unpack requested without additional information, attachments, or contacts; and a shipment unpack requested with additional information, attachments, or contacts.

 

The response indicates the order was successful and returned the order number.

 

Shipment Unpack without additional information, attachments, or contacts

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/shipmentUnpack"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

   "ibxLocation": {

    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "accountNumber": "126854"
      }
    ]
  },

  "serviceDetails": {
    "inboundShipmentOrderNumber": "1-190403752735",

    "discardShipmentMaterial": false,
    "copyOfPackingSlipNeeded": false,
    "scopeOfWork": "Flatten the boxes and keep them by the side of the cage."
  },

  "schedule": {

    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },

  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"

    },
    {
      "contactType": "TECHNICAL",

      "userName": "johndoe",
      "workPhonePrefToCall": "ANYTIME"

    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

 

Shipment Unpack with additional information, attachments, and contacts

 

Before creating an order with attachment, call the Post Attachment File under the API Reference section.

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/shipmentUnpack"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "cabinets": [
          "AM1:0J:00JD11:0001"
        ],
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "inboundShipmentOrderNumber": "1-190403752735",
    "discardShipmentMaterial": false,
    "copyOfPackingSlipNeeded": false,
    "scopeOfWork": "Flatten the boxes and keep them by the side of the cage.",
    "needSupportFromASubmarineCableStationEngineer": true
  },
  "attachments": [
    {
      "id": "26f40e6e-dd6e-48fa-a797-62c0d3157388",
      "name": "AdditionalShipmentWorkDetails.docx"
    }
  ],
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "customerReferenceNumber": "EQX-PO2019-08-001",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@corporation.com",
      "workPhoneCountryCode": "+44",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Europe/London",
      "mobilePhoneCountryCode": "+44",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "MY_BUSINESS_HOURS",
      "mobilePhoneTimeZone": "Europe/London"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "janesmith"
    }
  ]
}'

 

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 the cages information and IBX. 

ibx Yes string AM1  

The IBX location code.

 

E.g. AM1 is an IBX data centre in Amsterdam, Netherlands. 

cages Yes array[objects]    

Cages information consists of ID of cage, ID of cabinet, and cage account number.

 

Only 1 cage per order is currently being supported. Provide information for only 1 cage.

cage Yes string AM1:0J:00JD11  

ID of the cage.

cabinets No array[strings] AM1:0J:00JD11:0001  

ID of the cabinet.

 

If providing cabinet, provide only 1 cabinet ID. Only 1 cabinet is currently being supported per cage.

accountNumber Yes string 126854  

The customer account number that is linked to the cage.

serviceDetails Yes object     Service details consist of inbound shipment order number, requirement to dispose packaging, requirement to provide customer with a packing slip copy, and scope of work.
inboundShipmentOrderNumber Yes string 1-190403752735  

The order number for inbound shipment. This is free text input.

 

This field can only be up to 50 characters long.  

 

If you have not raised an inbound shipment order, refer to How to schedule an inbound shipment? under the How-to Guide for ECP use cases section. 

 

If you have already raised an inbound shipment order, but do not know the inbound shipment order number, refer to How to retrieve order history? under the How-to Guide for ECP use cases section to retrieve your inbound shipment order number. 

discardShipmentMaterial Yes boolean false

true, 

false

Customer requirement to discard the packaging.

 

If 'true', Equinix will discard the packaging.

 

If 'false', Equinix will not dispose of the packaging.

copyOfPackingSlipNeeded Yes boolean false

true, 

false

Customer requirement for a copy of the packing slip.

 

If 'true', Equinix will provide the customer with a copy of the packing slip.

 

If 'false', customer does not need a copy of the packing slip and none will be provided.

scopeOfWork Yes string Flatten the boxes and keep them by the side of the cage.  

A detailed description of the scope of work. This is free text input.

 

This field can only be up to 4000 characters long.

needSupportFromASubmarineCableStationEngineer Conditional boolean true

true, 

false

Requirement for submarine cable station engineer support.

 

This is mandatory for customers with Monet accounts.

 

If 'true', submarine cable station engineer support is required. 

 

If 'false', submarine cable station engineer support is not required. 

 

Default value: false

attachments No array[objects]    

An array containing the attachment details.

 

Up to 5 attachments, each not exceeding 2MB, 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.

id Conditional string

26f40e6e-dd6e-48fa-
a797-62c0d3157388

 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

name Conditional string AdditionalShipmentWorkDetails.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.

 

Refer to Post Attachment File under the API Reference section for more information. 

schedule Yes object     Schedule information that includes schedule type, and the starting and ending dates and times for the schedule.
scheduleType Yes string SCHEDULED_MAINTENANCE

STANDARD,

EXPEDITED,

SCHEDULED_MAINTENANCE

Define your preferred scheduling type.

 

Schedule Types 
 

STANDARD: Request will be processed in the standard turnaround time. Most requests are completed within 24 to 72 hours pending your install base readiness. Requests will be processed in the order they were received, unless they are expedited.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are not required. 

 

EXPEDITED: Request will be completed within the next 2 to 24 hours. Additional Smart Hands fees may apply. Schedule a time in the current local time of the IBX you selected. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameter 'requestedCompletionDate' is required. 

 

SCHEDULED_MAINTENANCE: Request will be scheduled as Customer Requested Maintenance. Additional Smart Hands fees may apply if your scheduled time is less than 24 hours from when the order is submitted. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are required.  

requestedStartDate Conditional string 2019-08-30T22:00:49.776Z  

Requested start date and time.

 

If 'STANDARD' or 'EXPEDITED' schedule type, this parameter is not required.

 

If 'SCHEDULED_MAINTENANCE' schedule type, 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.

requestedCompletionDate Conditional string 2019-08-31T22:00:49.776Z  

Requested end date and time.

 

If 'STANDARD' schedule type, this parameter is not required.

 

If 'EXPEDITED'  or 'SCHEDULED_MAINTENANCE' schedule type, 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.

 

Expedited scheduling date should not be less than IBX local time + 2 hours, and no more than IBX local time + 24 hours.

 

Scheduled maintenance scheduling should not be less than 24 hours from when the order is submitted. Otherwise, additional Smart Hands fees may apply.

customerReferenceNumber No string EQX-PO2019-08-001  

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

 

This can be a Purchase Order number or 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. 

 

If you do not know your account's PO bearing status, refer to Get Smarthands Locations under the API Reference section.

purchaseOrderType Conditional string EXEMPTED

 

EXISTING,

EXEMPTED

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

 

However, only existing and exempted purchase order types are currently being 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, and a purchase order number is not required. 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 Conditional 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.

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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. All three contacts are mandatory.

 

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

- Technical contact person: Person who Equinix can reach out to for technical clarifications. Only one Technical 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.

userName Yes string johndoe
      
 

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

 

E.g. If 'email' and 'workPhone' information is passed with 'userName' for Notification contact, this information will be ignored.

name Conditional string Jane Smith  

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

email Conditional string janesmith@corporation.com
      
 

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

workPhoneCountryCode No string +44     

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

 

E.g.: +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 an active or locked Equinix-registered username.

workPhonePrefToCall Yes string ANYTIME

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

This is mandatory for the Technical contact.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'workPhoneTimeZone' is mandatory.

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.

 

E.g. Area/Location

 

This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.

mobilePhoneCountryCode No string  +1  

Country code for mobile phone number of 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 MY_BUSINESS_HOURS

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls on their mobile phone anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'mobilePhoneTimeZone' is mandatory. 

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

 

E.g. Area/Location

 

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. 

 

{
  "OrderNumber": "1-457809872838"
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
OrderNumber string 1-457809872838 The order number created after order is submitted. 

 

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

 


body: 
How to order more cables?

 

 


body: 
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. 

 


body: 
Step 2: Get Smart Hands Details

 

To get Smart Hands details, the user must have 'Smart Hands' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

2a) Get Smart Hands Types

Retrieve all the Smart Hands categories supported by Equinix.

 

Refer to Get Smarthands Types under the API Reference section for instructions on how to get all Smart Hands types. You may skip this step if you already know the Smart Hands type. 

 

2b) 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 Smarthands 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.

 


body: 
Step 3: Order Cables

POST Smarthands Cable Request

POST /smarthands/cableRequest

 Method

 POST

 URL or End Point

 /v1/orders/smarthands/cableRequest

 Headers

 Authorization, Content-Type

 Query Parameters

 Not applicable

 Body

 ibxLocation {ibx, cages [{cage, cabinets[...], accountNumber}]}, serviceDetails {quantity, mediaType, connectorType, length, scopeOfWork}, attachments [{id, name}], schedule {scheduleType, requestedStartDate, requestedCompletionDate}, customerReferenceNumber, purchaseOrder {purchaseOrderType, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}, {contactType, userName}]

 

The Post smarthands cableRequest API orders cables per customer specifications. This can only be done under a user with 'Smart Hands' 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 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 API.

 

The request indicates four scenarios:

(A) An order for the same type of cable(s) without additional information, attachments, or contacts

(B) An order for the same type of cable(s)  with additional information, attachments, and contacts

(C) An order for different cables without additional information, attachments, or contacts

(D) An order for different cables with additional information, attachments, and contacts

 

The response indicates the order was successful and returned the order number.

 

(A) An order for the same type of cable(s) without additional information, attachments, or contacts

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/cableRequest"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "quantity": "1",
    "scopeOfWork": "25m Multi-mode 62.5mic with RJ45 connector cable(s). Leave cable in cage(s)."
  },
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "userName": "johndoe",
      "workPhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

 

(B) An order for the same type of cable(s)  with additional information, attachments, and contacts

 

Before creating an order with attachment, call the Post Attachment File under the API Reference section.

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/cableRequest"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "quantity": "10",
    "mediaType": "Multi-mode 62.5mic",
    "connectorType": "RJ45",
    "length": "25cm",
    "scopeOfWork": "Refer to attachment.",
    "needSupportFromASubmarineCableStationEngineer": true
  },
  "attachments": [
    {
      "id": "fcb4a673-6308-456e-8f83-f745501d60ba",
      "name": "additionalattachment.docx"
    }
  ],
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "customerReferenceNumber": "EQX-PO2019-08-001",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@corporation.com",
      "workPhoneCountryCode": "+44",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Europe/London",
      "mobilePhoneCountryCode": "+44",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "MY_BUSINESS_HOURS",
      "mobilePhoneTimeZone": "Europe/London"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "jillsnow"
    }
  ]
}'

 

(C) An order for different cables without additional information, attachments, or contacts

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/cableRequest"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "quantity": ">10",
    "scopeOfWork": "x8 25m Multi-mode 62.5mic with RJ45 connector cables, and x5 5m Multi-mode 62.5mic with ST connector cables. Leave in cage."
  },
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "userName": "johndoe",
      "workPhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

 

(D) An order for different cables with additional information, attachments, and contacts

 

Before creating an order with attachment, call the Post Attachment File under the API Reference section.

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/cableRequest"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "cabinets": [
          "AM1:0J:00JD11:0001"
        ],
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "quantity": ">10",
    "scopeOfWork": "Refer to attachment.",
    "needSupportFromASubmarineCableStationEngineer": true
  },
  "attachments": [
    {
      "id": "fcb4a673-6308-456e-8f83-f745501d60ba",
      "name": "additionalattachment.docx"
    }
  ],
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "customerReferenceNumber": "EQX-PO2019-08-001",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@corporation.com",
      "workPhoneCountryCode": "+44",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Europe/London",
      "mobilePhoneCountryCode": "+44",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "MY_BUSINESS_HOURS",
      "mobilePhoneTimeZone": "Europe/London"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "jillsnow"
    }
  ]
}'

 

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 the cages information and IBX. 

ibx Yes string AM1  

The IBX location code.

 

E.g. AM1 is an IBX data centre in Amsterdam, Netherlands. 

cages Yes array[objects]    

Cages information consists of ID of cage, ID of cabinet, and cage account number.

 

Only 1 cage per order is currently being supported. Provide information for only 1 cage.

cage Yes string AM1:0J:00JD11  

ID of the cage.

cabinets No array[strings] AM1:0J:00JD11:0001  

ID of the cabinet.

 

If providing cabinet, provide only 1 cabinet ID. Only 1 cabinet is currently being supported per cage.

accountNumber Yes string 126854  

The customer account number that is linked to the cage.

serviceDetails Yes object     

Service details consist of the total quantity of cables the customer wants to order, and the scope of work.

 

Additional information such as media type of cable, connector type of cable, and length of cable can also be included as fields. If you are ordering only one cable or multiple cables with the same specifications, it is recommended to include these fields.

 

If you are ordering multiple cables with varying specifications, please specify these in the scope of work. You may also attach your scope of work as a document if you exceed the character limit in this field.

quantity Yes string 1 1,
2,
3,
4,
5,
6,
7,
8,
9,
10,
>10

Total number of cables customer wants to order.

mediaType No string Multi-mode 62.5mic

Multi-mode 62.5mic,
Multi-mode 50mic,
Single-mode,
Cat-5,
Cat-6,
Coax,
POTS,
T1,
E1

Prefered media type of cable.

 

This is recommended when quantity is '1' or all ordered cables are the same specification.

connectorType

No string RJ45 RJ45,
SC,
LC,
BNC,
Other

Prefered connector type of cable.

 

This is recommended when quantity is '1' or all ordered cables are the same specification.

length No string 25cm

 

Length of cable specified in centimetres or feet. This is free text input.

 

This is recommended when quantity is '1' or all ordered cables are the same specification.

scopeOfWork Yes string

25m Multi-mode 62.5mic with RJ45 connector cable. Leave cable in cage,

 

Refer to attachment,

 

All are same cables. Leave in cage.

 

 

A detailed description of the scope of work. This is free text input.

 

This field can only be up to 4000 characters long.

needSupportFromASubmarineCableStationEngineer Conditional boolean true

true, 

false

Requirement for submarine cable station engineer support.

 

This is mandatory for customers with Monet accounts.

 

If 'true', submarine cable station engineer support is required. 

 

If 'false', submarine cable station engineer support is not required. 

 

Default value: false

attachments No array[objects]    

An array containing the attachment details.

 

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.

 

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

id Conditional string

fcb2k8763-2947-456e-

8d68-f280753d60ba

 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

name Conditional string additionalattachment.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.

 

Refer to Post Attachment File under the API Reference section for more information. 

schedule Yes object     Schedule information that includes schedule type, and the starting and ending dates and times for the schedule.
scheduleType Yes string SCHEDULED_MAINTENANCE

STANDARD,

EXPEDITED,

SCHEDULED_MAINTENANCE

Define your preferred scheduling type.

 

Schedule Types 
 

STANDARD: Request will be processed in the standard turnaround time. Most requests are completed within 24 to 72 hours pending your install base readiness. Requests will be processed in the order they were received, unless they are expedited.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are not required. 

 

EXPEDITED: Request will be completed within the next 2 to 24 hours. Additional Smart Hands fees may apply. Schedule a time in the current local time of the IBX you selected. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameter 'requestedCompletionDate' is required. 

 

SCHEDULED_MAINTENANCE: Request will be scheduled as Customer Requested Maintenance. Additional Smart Hands fees may apply if your scheduled time is less than 24 hours from when the order is submitted. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are required.  

requestedStartDate Conditional string 2019-08-30T22:00:49.776Z  

Requested start date and time.

 

If 'STANDARD' or 'EXPEDITED' schedule type, this parameter is not required.

 

If 'SCHEDULED_MAINTENANCE' schedule type, 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.

requestedCompletionDate Conditional string 2019-08-31T22:00:49.776Z  

Requested end date and time.

 

If 'STANDARD' schedule type, this parameter is not required.

 

If 'EXPEDITED'  or 'SCHEDULED_MAINTENANCE' schedule type, 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.

 

Expedited scheduling date should not be less than IBX local time + 2 hours, and no more than IBX local time + 24 hours.

 

Scheduled maintenance scheduling should not be less than 24 hours from when the order is submitted. Otherwise, additional Smart Hands fees may apply.

customerReferenceNumber No string EQX-PO2019-08-001  

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

 

This can be a Purchase Order number or 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. 

 

If you do not know your account's PO bearing status, refer to Get Smarthands Locations under the API Reference section.

purchaseOrderType Conditional string EXEMPTED

EXISTING,

EXEMPTED

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

 

However, only existing and exempted purchase order types are currently being 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, and a purchase order number is not required. 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 Conditional 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.

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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. All three contacts are mandatory.

 

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

- Technical contact person: Person who Equinix can reach out to for technical clarifications. Only one Technical 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.

userName Yes string

johndoe

      

 

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

 

E.g. If 'email' and 'workPhone' information is passed with 'userName' for Notification contact, this information will be ignored.

name Conditional string Jane Smith  

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

email Conditional string janesmith@corporation.com
      
 

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

workPhoneCountryCode No string +44
      
 

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

 

E.g.: +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 an active or locked Equinix-registered username.

workPhonePrefToCall Yes string ANYTIME

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

This is mandatory for the Technical contact.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'workPhoneTimeZone' is mandatory.

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.

 

E.g. Area/Location

 

This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.

mobilePhoneCountryCode No string  +1  

Country code for mobile phone number of 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 MY_BUSINESS_HOURS

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls on their mobile phone anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'mobilePhoneTimeZone' is mandatory. 

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

 

E.g. Area/Location

 

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. 

 

{
  "OrderNumber": "1-190986534844"
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
OrderNumber string 1-190986534844 The order number created after order is submitted. 

 

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

 


body: 
How to order an unlisted Smart Hands?

 

 


body: 
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. 

 


body: 
Step 2: Get Smart Hands Details

 

To get Smart Hands details, the user must have 'Smart Hands' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

2a) Get Smart Hands Types

Retrieve all the Smart Hands categories supported by Equinix.

 

Refer to Get Smarthands Types under the API Reference section for instructions on how to get all Smart Hands types. You may skip this step if you already know the Smart Hands type. 

 

2b) 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 Smarthands 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.

 


body: 
Step 3: Order Smart Hands: Others

POST Smarthands Other

POST /smarthands/other

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

 ibxLocation {ibx, cages [{cage, cabinets[...], accountNumber}]}, serviceDetails {scopeOfWork, needSupportFromASubmarineCableStationEngineer}, attachments [{id, name}], schedule {scheduleType, requestedStartDate, requestedCompletionDate}, customerReferenceNumber, purchaseOrder {purchaseOrderType, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}, {contactType, userName}, {contactType, userName}]

 

The Post smarthands other API requests an unlisted Smart Hands order at an IBX location where the user has 'Smart Hands' 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 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 API.

 

The request indicates two scenarios: a Smart Hands: Other order made without additional information, attachments, or contacts; and  a Smart Hands: Other order made with additional information, attachments, and contacts.

 

The response indicates the order was successful and returned the order number.

 

 Smart Hands: Other order without additional information, attachments, or contacts

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/other"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "scopeOfWork": "The camera vision tends to blur from 10pm-2am every night. Spend the night in the cage to monitor what the issue is."
  },
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "userName": "johndoe",
      "workPhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

 

Smart Hands: Other order with additional information, attachments, and contacts

 

Before creating an order with attachment, call the Post Attachment File under the API Reference section.

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/other"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "cabinets": [
          "AM1:0J:00JD11:0001"
        ],
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "scopeOfWork": "The camera vision tends to blur from 10pm-2am every night. Spend the night in the cage to monitor what the issue is.",
    "needSupportFromASubmarineCableStationEngineer": true
  },
  "attachments": [
    {
      "id": "fcb2k8763-2947-456e-8d68-f280753d60ba",
      "name": "SupportingPhotos.docx"
    }
  ],
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "customerReferenceNumber": "EQX-PO2019-08-001",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@corporation.com",
      "workPhoneCountryCode": "+44",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Europe/London",
      "mobilePhoneCountryCode": "+44",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "MY_BUSINESS_HOURS",
      "mobilePhoneTimeZone": "Europe/London"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "janesmith"
    }
  ]
}'

 

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 the cages information and IBX. 

ibx Yes string AM1  

The IBX location code.

 

E.g. AM1 is an IBX data centre in Amsterdam, Netherlands. 

cages Yes array[objects]    

Cages information consists of ID of cage, ID of cabinet, and cage account number.

 

Only 1 cage per order is currently being supported. Provide information for only 1 cage.

cage Yes string AM1:0J:00JD11  

ID of the cage.

cabinets No array[strings] AM1:0J:00JD11:0001  

ID of the cabinet.

 

If providing cabinet, provide only 1 cabinet ID. Only 1 cabinet is currently being supported per cage.

accountNumber Yes string 126854  

The customer account number that is linked to the cage.

serviceDetails Yes object     Service details consist of scope of work. 
scopeOfWork Yes string The camera vision tends to blur from 10pm-2am every night. Spend the night in the cage to monitor what the issue is.  

A detailed description of the scope of work. This is free text.

 

This field can only be up to 4000 characters long.

needSupportFromASubmarineCableStationEngineer Conditional boolean true

true,

false

Requirement for submarine cable station engineer support.

 

This is mandatory for customers with Monet accounts.

 

If 'true', submarine cable station engineer support is required. 

 

If 'false', submarine cable station engineer support is not required. 

 

Default value: false

attachments No array[objects]    

An array containing the attachment details.

 

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.

 

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

id Conditional string

fcb2k8763-2947-456e-

8d68-f280753d60ba

 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

name Conditional string SupportingPhotos.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.

 

Refer to Post Attachment File under the API Reference section for more information. 

schedule Yes object     Schedule information that includes schedule type, and the starting and ending dates and times for the schedule.
scheduleType Yes string SCHEDULED_MAINTENANCE

STANDARD,

EXPEDITED,

SCHEDULED_MAINTENANCE

Define your preferred scheduling type.

 

Schedule Types 
 

STANDARD: Request will be processed in the standard turnaround time. Most requests are completed within 24 to 72 hours pending your install base readiness. Requests will be processed in the order they were received, unless they are expedited.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are not required. 

 

EXPEDITED: Request will be completed within the next 2 to 24 hours. Additional Smart Hands fees may apply. Schedule a time in the current local time of the IBX you selected. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameter 'requestedCompletionDate' is required. 

 

SCHEDULED_MAINTENANCE: Request will be scheduled as Customer Requested Maintenance. Additional Smart Hands fees may apply if your scheduled time is less than 24 hours from when the order is submitted. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are required.  

requestedStartDate Conditional string 2019-08-30T22:00:49.776Z  

Requested start date and time.

 

If 'STANDARD' or 'EXPEDITED' schedule type, this parameter is not required.

 

If 'SCHEDULED_MAINTENANCE' schedule type, 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.

requestedCompletionDate Conditional string 2019-08-31T22:00:49.776Z  

Requested end date and time.

 

If 'STANDARD' schedule type, this parameter is not required.

 

If 'EXPEDITED'  or 'SCHEDULED_MAINTENANCE' schedule type, 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.

 

Expedited scheduling date should not be less than IBX local time + 2 hours, and no more than IBX local time + 24 hours.

 

Scheduled maintenance scheduling should not be less than 24 hours from when the order is submitted. Otherwise, additional Smart Hands fees may apply.

customerReferenceNumber No string EQX-PO2019-08-001  

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

 

This can be a Purchase Order number or 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. 

 

If you do not know your account's PO bearing status, refer to Get Smarthands Locations under the API Reference section.

purchaseOrderType Conditional string EXEMPTED

EXISTING,

EXEMPTED

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

 

However, only existing and exempted purchase order types are currently being 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, and a purchase order number is not required. 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 Conditional 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.

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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. All three contacts are mandatory.

 

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

- Technical contact person: Person who Equinix can reach out to for technical clarifications. Only one Technical 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.

userName Yes string johndoe
      
 

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

 

E.g. If 'email' and 'workPhone' information is passed with 'userName' for Notification contact, this information will be ignored.

name Conditional string Jane Smith  

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

email Conditional string janesmith@corporation.com
      
 

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

workPhoneCountryCode No string +44
      
 

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

 

E.g.: +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 an active or locked Equinix-registered username.

workPhonePrefToCall Conditional string ANYTIME

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

This is mandatory for the Technical contact.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'workPhoneTimeZone' is mandatory.

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.

 

E.g. Area/Location

 

This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.

mobilePhoneCountryCode No string  +1  

Country code for mobile phone number of 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 MY_BUSINESS_HOURS

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls on their mobile phone anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'mobilePhoneTimeZone' is mandatory. 

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

 

E.g. Area/Location

 

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. 

 

{
  "OrderNumber": "1-2457908765329",
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
OrderNumber string 1-2457908765329 The order number created after order is submitted. 

 

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

 


body: 
How to order packages location?

 

 


body: 
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. 

 


body: 
Step 2: Schedule an inbound shipment

 

To schedule an inbound shipment, the user must have 'Shipments' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

Schedule an inbound shipment and retrieve the order number

Retrieve the inbound shipment order number after scheduling an inbound shipment.

 

Refer to How to schedule an Inbound Shipment? under How to schedule shipments section of the How-to Guide for ECP use cases for instructions on how to schedule an inbound shipment, or refer to How to retrieve order history? under the How-to Guide for ECP use cases section for instructions on how to retrieve an order number for an inbound shipment that has already been scheduled. You may skip this step if you already have the inbound shipment order number.

 


body: 
Step 3: Get Smart Hands Details

 

To get Smart Hands details, the user must have 'Smart Hands' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

3a) Get Smart Hands Types

Retrieve all the Smart Hands categories supported by Equinix.

 

Refer to Get Smarthands Types under the API Reference section for instructions on how to get all Smart Hands types. You may skip this step if you already know the Smart Hands type.  

 

3b) 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 Smarthands 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.

 


body: 
Step 4: Order packages location

POST Smarthands Locate Package

POST /smarthands/locatePackage

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

 ibxLocation {ibx, cages [{cage, cabinets[...], accountNumber}]}, serviceDetails {shipmentOrderNumber, trackingNumber, possibleLocation, packageDescription, scopeOfWork, needSupportFromASubmarineCableStationEngineer}, attachments [{id, name}], schedule {scheduleType, requestedStartDate, requestedCompletionDate}, customerReferenceNumber, purchaseOrder {purchaseOrderType, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall, mobilePhoneTimeZone}, contactType, userName}, {contactType, userName}]

 

The Post smarthands locatePackage API requests the location of your packages at the IBX. This can only be done by a user with 'Smart Hands' 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.

 

An inbound shipment order number must be provided to order a Smarthands Locate Package. If you have not raised an inbound shipment order, refer to How to schedule an inbound shipment? under the How-to Guide for ECP use cases section. If you have already raised an inbound shipment order, but do not know the inbound shipment order number, refer to How to retrieve order history? under the How-to Guide for ECP use cases section to retrieve your inbound shipment order number. 

 

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

 

The request indicates two scenarios: an order to locate packages without additional information, attachments, or contacts; and an order to locate packages with additional information, attachments, or contacts.

 

The response indicates the order was successful and returned the order number.

 

Locate Package without additional information, attachments, or contacts

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/locatePackage"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {

    "shipmentOrderNumber": "1-1234567890",

    "trackingNumber": "All tracking numbers in this shipment order.",

    "possibleLocation": "Last known location was the loading bay.",

    "packageDescription": "Multiple DHL boxes.",

    "scopeOfWork": "Locate and group all boxes together in a fixed location for easy identification and later collection."
  },
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "userName": "johndoe",
      "workPhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

 

Locate Package with additional information, attachments, and contacts

 

Before creating an order with attachment, call the Post Attachment File API under the API Reference section.

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/locatePackage"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "cabinets": [
          "AM1:0J:00JD11:0001"
        ],
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "shipmentOrderNumber": "1-1234567890",
    "trackingNumber": "All tracking numbers in this shipment order.",
    "possibleLocation": "Last known location was the loading bay.",
    "packageDescription": "Multiple DHL boxes.",
    "scopeOfWork": "Locate and group all boxes together in a fixed location for easy identification and later collection.",
    "needSupportFromASubmarineCableStationEngineer": true
  },
  "attachments": [
    {
      "id": "fcb2k8763-2947-456e-8d68-f280753d60ba",
      "name": "AdditionalShipmentWorkDetails.docx"
    }
  ],
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "customerReferenceNumber": "EQX-PO2019-08-001",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@corporation.com",
      "workPhoneCountryCode": "+44",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Europe/London",
      "mobilePhoneCountryCode": "+44",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "MY_BUSINESS_HOURS",
      "mobilePhoneTimeZone": "Europe/London"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "janesmith"
    }
  ]
}'

 

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 the cages information and IBX. 

ibx Yes string AM1  

The IBX location code.

 

E.g. AM1 is an IBX data centre in Amsterdam, Netherlands. 

cages Yes array[objects]    

Cages information consists of ID of cage, ID of cabinet, and cage account number.

 

Only 1 cage per order is currently being supported. Provide information for only 1 cage.

cage Yes string AM1:0J:00JD11  

ID of the cage.

cabinets No array[strings] AM1:0J:00JD11:0001  

ID of the cabinet.

 

If providing cabinet, provide only 1 cabinet ID. Only 1 cabinet is currently being supported per cage.

accountNumber Yes string 126854  

The customer account number that is linked to the cage.

serviceDetails Yes object     Service details consist of inbound shipment order number, requirement to dispose packaging, requirement to provide customer with a packing slip copy, and scope of work.
inboundShipmentOrderNumber Yes string 1-1234567890  

The order number for inbound shipment. This is free text input.

 

This field can only be up to 50 characters long.  

 

If you have not raised an inbound shipment order, refer to How to schedule an inbound shipment? under the How-to Guide for ECP use cases section. 

 

If you have already raised an inbound shipment order, but do not know the inbound shipment order number, refer to How to retrieve order history? under the How-to Guide for ECP use cases section to retrieve your inbound shipment order number. 

trackingNumber Yes string All tracking numbers in this shipment order.

 

Tracking number(s) of specific shipments to be located. This is free text input.

 

Multiple tracking numbers should be comma-separated.

 

This field can only be up to 200 characters long.  

possibleLocation Yes string Last known location was the loading bay.

 

Possible location(s) where the packages may be found. This will help to expedite the search. This is free text input.

 

This field can only be up to 200 characters long.  

packageDescription Yes string Multiple DHL boxes.  

Description of packages. This will help to expedite the search. This is free text input.

 

E.g. 4 Brown boxes with bright red lettering measuring 1m x 1m x 1m. 

 

This field can only be up to 200 characters long.  

scopeOfWork Yes string Locate and group all boxes together in a fixed location for easy identification and later collection.  

A detailed description of the scope of work. This is free text input.

 

This field can only be up to 4000 characters long.

needSupportFromASubmarineCableStationEngineer Conditional boolean true

true, 

false

Requirement for submarine cable station engineer support.

 

This is mandatory for customers with Monet accounts.

 

If 'true', submarine cable station engineer support is required. 

 

If 'false', submarine cable station engineer support is not required. 

 

Default value: false

attachments No array[objects]    

An array containing the attachment details.

 

Up to 5 attachments, each not exceeding 2MB, 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.

id Conditional string

fcb2k8763-2947-456e-

8d68-f280753d60ba

 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

name Conditional string AdditionalShipmentWorkDetails.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.

 

Refer to Post Attachment File under the API Reference section for more information. 

schedule Yes object     Schedule information that includes schedule type, and the starting and ending dates and times for the schedule.
scheduleType Yes string SCHEDULED_MAINTENANCE

STANDARD,

EXPEDITED,

SCHEDULED_MAINTENANCE

Define your preferred scheduling type.

 

Schedule Types 
 

STANDARD: Request will be processed in the standard turnaround time. Most requests are completed within 24 to 72 hours pending your install base readiness. Requests will be processed in the order they were received, unless they are expedited.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are not required. 

 

EXPEDITED: Request will be completed within the next 2 to 24 hours. Additional Smart Hands fees may apply. Schedule a time in the current local time of the IBX you selected. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameter 'requestedCompletionDate' is required. 

 

SCHEDULED_MAINTENANCE: Request will be scheduled as Customer Requested Maintenance. Additional Smart Hands fees may apply if your scheduled time is less than 24 hours from when the order is submitted. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are required.  

requestedStartDate Conditional string 2019-08-30T22:00:49.776Z  

Requested start date and time.

 

If 'STANDARD' or 'EXPEDITED' schedule type, this parameter is not required.

 

If 'SCHEDULED_MAINTENANCE' schedule type, 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.

requestedCompletionDate Conditional string 2019-08-31T22:00:49.776Z  

Requested end date and time.

 

If 'STANDARD' schedule type, this parameter is not required.

 

If 'EXPEDITED'  or 'SCHEDULED_MAINTENANCE' schedule type, 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.

 

Expedited scheduling date should not be less than IBX local time + 2 hours, and no more than IBX local time + 24 hours.

 

Scheduled maintenance scheduling should not be less than 24 hours from when the order is submitted. Otherwise, additional Smart Hands fees may apply.

customerReferenceNumber No string EQX-PO2019-08-001  

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

 

This can be a Purchase Order number or 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. 

 

If you do not know your account's PO bearing status, refer to Get Smarthands Locations under the API Reference section.

purchaseOrderType Conditional string EXISTING

 

EXISTING,

EXEMPTED

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

 

However, only existing and exempted purchase order types are currently being 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, and a purchase order number is not required. 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 Conditional 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.

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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. All three contacts are mandatory.

 

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

- Technical contact person: Person who Equinix can reach out to for technical clarifications. Only one Technical 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.

userName Yes string johndoe
      
 

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

 

E.g. If 'email' and 'workPhone' information is passed with 'userName' for Notification contact, this information will be ignored.

name Conditional string Jane Smith  

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

email Conditional string janesmith@corporation.com
      
 

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

workPhoneCountryCode No string +44  

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

 

E.g.: +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 an active or locked Equinix-registered username.

workPhonePrefToCall Yes string ANYTIME

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

This is mandatory for the Technical contact.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'workPhoneTimeZone' is mandatory.

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.

 

E.g. Area/Location

 

This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.

mobilePhoneCountryCode No string  +1  

Country code for mobile phone number of 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 MY_BUSINESS_HOURS

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls on their mobile phone anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'mobilePhoneTimeZone' is mandatory. 

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

 

E.g. Area/Location

 

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. 

 

{
  "OrderNumber": "1-457809872838"
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
OrderNumber string 1-457809872838 The order number created after order is submitted. 

 

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

 


body: 
How to order a cage clean-up?

 

 


body: 
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. 

 


body: 
Step 2: Get Smart Hands Details

 

To get Smart Hands details, the user must have 'Smart Hands' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

2a) Get Smart Hands Types

Retrieve all the Smart Hands categories supported by Equinix.

 

Refer to Get Smarthands Types under the API Reference section for instructions on how to get all Smart Hands types. You may skip this step if you already know the Smart Hands type. 

 

2b) 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 Smarthands 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.

 


body: 
Step 3: Order a Cage Clean-Up

POST Smarthands Cage Cleanup

POST /smarthands/cageCleanup

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

 ibxLocation {ibx, cages [{cage, cabinets[...], accountNumber}]}, serviceDetails {permissionToDiscardBoxes, dampMoistMopRequired, scopeOfWork, needSupportFromASubmarineCableStationEngineer}, attachments [{id, name}], schedule {scheduleType, requestedStartDate, requestedCompletionDate}, customerReferenceNumber, purchaseOrder {purchaseOrderType, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}, {contactType, userName}, {contactType, userName}]}

 

The Post smarthands cageCleanup API orders trash removal or cage cleanup from a specific cage in the IBX where the user has 'Smart Hands' 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 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 API.

 

The request indicates two scenarios: a cage cleanup ordered without additional information, attachments, or contacts;  and a cage cleanup ordered with additional information, attachments, and contacts. 

 

The response indicates the order was successful and returned the order number.

 

Cage Cleanup without additional information, attachments, or contacts

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/cageCleanup"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
    "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "permissionToDiscardBoxes": true,
    "dampMoistMopRequired": true,
    "scopeOfWork": "Light dusting of equipment, microfiber mop to be used."
  },
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "userName": "johndoe",
      "workPhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

 

Cage Cleanup with additional information, attachments, and contacts

 

Before creating an order with attachment, call the Post Attachment File under the API Reference section.

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/cageCleanup"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "cabinets": [
          "AM1:0J:00JD11:0001"
        ],
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "permissionToDiscardBoxes": true,
    "dampMoistMopRequired": true,
    "scopeOfWork": "Light dusting of equipment, microfiber mop to be used.",
    "needSupportFromASubmarineCableStationEngineer": true
  },
  "attachments": [
    {
      "id": "fcb2k8763-2947-456e-8d68-f280753d60ba",
      "name": "PhotoForCageCleanupServiceDetails.docx"
    }
  ],
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "customerReferenceNumber": "EQX-PO2019-08-001",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@corporation.com",
      "workPhoneCountryCode": "+44",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Europe/London",
      "mobilePhoneCountryCode": "+44",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "MY_BUSINESS_HOURS",
      "mobilePhoneTimeZone": "Europe/London"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "janesmith"
    }
  ]
}'

 

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 the cages information and IBX. 

ibx Yes string AM1  

The IBX location code.

 

E.g. AM1 is an IBX data centre in Amsterdam, Netherlands. 

cages Yes array[objects]    

Cages information consists of ID of cage, ID of cabinet, and cage account number.

 

Only 1 cage is currently being supported. Provide information for only 1 cage.

cage Yes string AM1:0J:00JD11  

ID of the cage.

cabinets No array[strings] AM1:0J:00JD11:0001  

ID of the cabinet.

 

If providing cabinet, provide only 1 cabinet ID. Only 1 cabinet is currently being supported.

accountNumber Yes string 126854  

The customer account number that is linked to the cage.

serviceDetails Yes object     Service details consist of permission to discard boxes, the requirement for mopping, and scope of work.
permissionToDiscardBoxes Yes boolean true

true, 

false

Granting permission to Equinix to discard any boxes found in the cage.

 

If 'true', permission is granted to Equinix to discard any boxes found in the cage.

 

If 'false', permission is not granted to Equinix to discard any boxes found in the cage.

dampMoistMopRequired Yes boolean true

true, 

false

A specific request for damp/ moist mop to be used to clean the cage.

 

If 'true', damp/ moist mop will be used.

 

If 'false', damp/ moist mop will not be used. 

scopeOfWork Yes string Light dusting of equipment, microfiber mop to be used.

 

A detailed description of the scope of work. This is free text input.

 

This field can only be up to 4000 characters long.

needSupportFromASubmarineCableStationEngineer Conditional boolean true

true, 

false

Requirement for submarine cable station engineer support.

 

This is mandatory for customers with Monet accounts.

 

If 'true', submarine cable station engineer support is required. 

 

If 'false', submarine cable station engineer support is not required. 

 

Default value: false

attachments No array[objects]    

An array containing the attachment details.

 

Up to 5 attachments, each not exceeding 2MB, 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.

id Conditional string

fcb2k8763-2947-456e-

8d68-f280753d60ba

 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

name Conditional string PhotoForCageCleanupServiceDetails.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.

 

Refer to Post Attachment File under the API Reference section for more information. 

schedule Yes object    

Schedule information that includes schedule type, and the starting and ending dates and times for the schedule.

scheduleType Yes string SCHEDULED_MAINTENANCE

STANDARD,

EXPEDITED,

SCHEDULED_MAINTENANCE

Define your preferred scheduling type.

 

Schedule Types 
 

STANDARD: Request will be processed in the standard turnaround time. Most requests are completed within 24 to 72 hours pending your install base readiness. Requests will be processed in the order they were received, unless they are expedited.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are not required. 

 

EXPEDITED: Request will be completed within the next 2 to 24 hours. Additional Smart Hands fees may apply. Schedule a time in the current local time of the IBX you selected. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameter 'requestedCompletionDate' is required. 

 

SCHEDULED_MAINTENANCE: Request will be scheduled as Customer Requested Maintenance. Additional Smart Hands fees may apply if your scheduled time is less than 24 hours from when the order is submitted. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are required.  

 

This is mandatory when including schedule.

requestedStartDate Conditional string 2019-08-30T22:00:49.776Z  

Requested start date and time.

 

If 'STANDARD' or 'EXPEDITED' schedule type, this parameter is not required.

 

If 'SCHEDULED_MAINTENANCE' schedule type, 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.

requestedCompletionDate Conditional string 2019-08-31T22:00:49.776Z  

Requested end date and time.

 

If 'STANDARD' schedule type, this parameter is not required.

 

If 'EXPEDITED'  or 'SCHEDULED_MAINTENANCE' schedule type, 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.

 

Expedited scheduling date should not be less than IBX local time + 2 hours, and no more than IBX local time + 24 hours.

 

Scheduled maintenance scheduling should not be less than 24 hours from when the order is submitted. Otherwise, additional Smart Hands fees may apply.

customerReferenceNumber No string EQX-PO2019-08-001  

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

 

This can be a Purchase Order number or 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. 

 

If you do not know your account's PO bearing status, refer to Get Smarthands Locations under the API Reference section.

purchaseOrderType Conditional string EXEMPTED

NEW,

EXISTING,

EXEMPTED

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

 

However, only existing and exempted purchase order types are currently being 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, and a purchase order number is not required. 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 Conditional 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.

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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. All three contacts are mandatory.

 

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

- Technical contact person: Person who Equinix can reach out to for technical clarifications. Only one Technical 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.

userName Yes string johndoe
      
 

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

 

E.g. If 'email' and 'workPhone' information is passed with 'userName' for Notification contact, this information will be ignored.

name Conditional string Jane Smith  

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

email Conditional string janesmith@corporation.com
      
 

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

workPhoneCountryCode No string +44
      
 

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

 

E.g.: +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 an active or locked Equinix-registered username.

workPhonePrefToCall Yes string ANYTIME

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

This is mandatory for the Technical contact.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'workPhoneTimeZone' is mandatory.

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.

 

E.g. Area/Location

 

This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.

mobilePhoneCountryCode No string  +1  

Country code for mobile phone number of 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 MY_BUSINESS_HOURS

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls on their mobile phone anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'mobilePhoneTimeZone' is mandatory. 

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

 

E.g. Area/Location

 

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. 

 

{
  "OrderNumber": "1-190368976438"
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
OrderNumber string 1-190368976438 The order number created after order is submitted. 

 

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

 


body: 
How to order patch cable removal?

 

 


body: 
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. 

 


body: 
Step 2: Get Smart Hands Details

 

To get Smart Hands details, the user must have 'Smart Hands' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

2a) Get Smart Hands Types

Retrieve all the Smart Hands categories supported by Equinix.

 

Refer to Get Smarthands Types under the API Reference section for instructions on how to get all Smart Hands types. You may skip this step if you already know the Smart Hands type. 

 

2b) 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 Smarthands 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.

 


body: 
Step 3: Get Connection Details

 

To get the serial number of the connection, the user must have 'View Install Base' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

Retrieve the serial number of the connection.

 

Use this API to determine the serial number of the cross connection for the patch cable removal.

 

Refer to How to retrieve assets? under the How-to Guide for ECP use cases section for instructions on how to retirieve the cross connect serial number. You may skip this step if you already have the serial number.

 

If you cannot find the serial number of the cross connect, you should use "Serial # Not Found" as your serial number.

 


body: 
Step 4: Order Patch Cable Removal

POST Smarthands Patch Cable Removal

POST /smarthands/patchCableRemoval

 Method

 POST

 URL or End Point

 /v1/orders/smarthands/patchCableRemoval

 Headers

 Authorization, Content-Type

 Query Parameters

 Not applicable

 Body

 ibxLocation {ibx, cages [{cage, cabinets[...], accountNumber}]}, serviceDetails {crossConnects [{serialNumber, deviceCabinet, deviceConnectorType, deviceDetails, devicePort, scopeOfWork, needSupportFromASubmarineCableStationEngineer}]}, attachments [{id, name}], schedule {scheduleType, requestedStartDate, requestedCompletionDate}, customerReferenceNumber, purchaseOrder {purchaseOrderType, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}, {contactType, userName}]

 

The Post smarthands patchCableRemovalAPI orders patch cable removal per customer specifications by an Equinix IBX Technician. This can only be done by a user with 'Smart Hands' 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 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 API.

 

The request indicates two scenarios: a patch cable removal without additional information, attachments, or contacts; and a patch cable removal with additional information, attachments, and contacts. 

 

The response indicates the order was successful and returned the order number.

 

Patch Cable Removal without additional information, attachments, or contacts

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/patchCableRemoval"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "cabinets": [
          "AM1:0J:00JD11:0001"
        ],
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "crossConnects": [
      {
        "serialNumber": "123456789",
        "deviceCabinet": "501",
        "deviceConnectorType": "FC",
        "deviceDetails": "Router1",
        "devicePort": "1"
      }
    ]
  },
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "userName": "johndoe",
      "workPhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

 

Patch Cable Removal with additional information, attachments, and contacts

 

Before creating an order with attachment, call the Post Attachment File under the API Reference section.

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/patchCableRemoval"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "cabinets": [
          "AM1:0J:00JD11:0001"
        ],
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "crossConnects": [
      {
        "serialNumber": "123456789",
        "deviceCabinet": "501",
        "deviceConnectorType": "FC",
        "deviceDetails": "Router1",
        "devicePort": "1",
        "removePatchCableWithLiveTraffic": true,
        "scopeOfWork": "Refer to attachment for further instruction.",
        "needSupportFromASubmarineCableStationEngineer": true
      }
    ]
  },
  "attachments": [
    {
      "id": "fcb4a673-6308-456e-8f83-f745501d60ba",
      "name": "PatchCabelRemovalInstruction.docx"
    }
  ],
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "customerReferenceNumber": "EQX-PO2019-08-001",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@corporation.com",
      "workPhoneCountryCode": "+44",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Europe/London",
      "mobilePhoneCountryCode": "+44",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "MY_BUSINESS_HOURS",
      "mobilePhoneTimeZone": "Europe/London"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "jillsnow"
    }
  ]
}'

 

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 the cages information and IBX. 

ibx Yes string AM1  

The IBX location code.

 

E.g. AM1 is an IBX data centre in Amsterdam, Netherlands. 

cages Yes array[objects]    

Cages information consists of ID of cage, ID of cabinet, and cage account number.

 

Only 1 cage per order is currently being supported. Provide information for only 1 cage.

cage Yes string AM1:0J:00JD11  

ID of the cage.

cabinets Yes array[strings] AM1:0J:00JD11:0001  

ID of the cabinet.

 

Only 1 cabinet per order is currently being supported. Provide information for only 1 cabinet.

accountNumber Yes string 126854  

The customer account number that is linked to the cage.

serviceDetails Yes object      Service details consists of cross connections information.
crossConnects Yes array[objects]    

Cross connections information consisting of the cross connection details due for patch cable removal.

serialNumber Yes string 123456789

Serial # Not Found

The serial number of the cross connect for the desired patch cable removal. 

 

If you are unsure of the serial number of the cross connection, refer to How to retrieve assets? under the How-to Guide for ECP use cases section for instructions on how to retrieve the serial number.

 

If you cannot find the serial number of the cross connect, you should use "Serial # Not Found" as your serial number.

deviceCabinet Yes string 501  

Cabinet where the device for patch cable removal is located. This is free text input

 

In Smart Hands Patch Cable Installation or Removal, the cabinet number, which can be derived from the cabinet ID, can be passed as the 'deviceCabinet' value. ID of the cabinet consists of {cage ID}:{cabinet number}. 

 

Refer to Get Smarthands Locations under the API Reference section for instructions on how to retrieve the cabinet number of your preferred device cabinet. 

deviceConnectorType Yes string FC

 

The connector type for the patch cable. This is free text input. 

deviceDetails Yes string Router1

 

The details of the device. This is free text input. 

devicePort Yes string 1  

The port number to remove the patch cable. This is free text input. 

removePatchCableWithLiveTraffic No boolean true

true, 

false

Request to proceed with removal even if live traffic is detected.

 

Disclaimer: Equinix will complete the requested removal based on your instructions and will not be responsible for any service outages resulting from this removal.

 

If 'true', cross connect asset will be removed regardless of live traffic. By selecting this option, you agree to the terms for removal with live traffic.

 

If this request is not required, do not include this parameter.

 

Default value: false

scopeOfWork No string Refer to attachment for further instruction. 

 

A detailed description of the scope of work. This is free text input.

 

This field can only be up to 4000 characters long.

needSupportFromASubmarineCableStationEngineer Conditional boolean true

true, 

false

Requirement for submarine cable station engineer support.

 

This is mandatory for customers with Monet accounts.

 

If 'true', submarine cable station engineer support is required. 

 

If 'false', submarine cable station engineer support is not required. 

 

Default value: false

attachments No array[objects]    

An array containing the attachment details.

 

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.

 

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

id Conditional string

fcb2k8763-2947-456e-

8d68-f280753d60ba

 

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.

 

Refer to Post Attachment File under the API Reference section for more information.

name Conditional string PatchCabelRemovalInstruction.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.

 

Refer to Post Attachment File under the API Reference section for more information.

schedule Yes object     Schedule information that includes schedule type, and the starting and ending dates and times for the schedule.
scheduleType Yes string SCHEDULED_MAINTENANCE

STANDARD,

EXPEDITED,

SCHEDULED_MAINTENANCE

Define your preferred scheduling type.

 

Schedule Types 
 

STANDARD: Request will be processed in the standard turnaround time. Most requests are completed within 24 to 72 hours pending your install base readiness. Requests will be processed in the order they were received, unless they are expedited.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are not required. 

 

EXPEDITED: Request will be completed within the next 2 to 24 hours. Additional Smart Hands fees may apply. Schedule a time in the current local time of the IBX you selected. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameter 'requestedCompletionDate' is required. 

 

SCHEDULED_MAINTENANCE: Request will be scheduled as Customer Requested Maintenance. Additional Smart Hands fees may apply if your scheduled time is less than 24 hours from when the order is submitted. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are required.  

requestedStartDate Conditional string 2019-08-30T22:00:49.776Z  

Requested start date and time.

 

If 'STANDARD' or 'EXPEDITED' schedule type, this parameter is not required.

 

If 'SCHEDULED_MAINTENANCE' schedule type, 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.

requestedCompletionDate Conditional string 2019-08-31T22:00:49.776Z  

Requested end date and time.

 

If 'STANDARD' schedule type, this parameter is not required.

 

If 'EXPEDITED'  or 'SCHEDULED_MAINTENANCE' schedule type, 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.

 

Expedited scheduling date should not be less than IBX local time + 2 hours, and no more than IBX local time + 24 hours.

 

Scheduled maintenance scheduling should not be less than 24 hours from when the order is submitted. Otherwise, additional Smart Hands fees may apply.

customerReferenceNumber No string EQX-PO2019-08-001  

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

 

This can be a Purchase Order number or 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.

 

If you do not know your account's PO bearing status, refer to Get Smarthands Locations under the API Reference section.

purchaseOrderType Conditional string EXEMPTED

EXISTING,

EXEMPTED

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

 

However, only existing and exempted purchase order types are currently being 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, and a purchase order number is not required. 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 Conditional 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.

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.

 

Refer to Post Attachment File under the API Reference section for more information.

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.

 

Refer to Post Attachment File under the API Reference section for more information.

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. All three contacts are mandatory.

 

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

- Technical contact person: Person who Equinix can reach out to for technical clarifications. Only one Technical 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.

userName Yes string

johndoe

      

 

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

 

E.g. If 'email' and 'workPhone' information is passed with 'userName' for Notification contact, this information will be ignored.

name Conditional string Jane Smith  

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

email Conditional string janesmith@corporation.com  

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

workPhoneCountryCode No string +44    

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

 

E.g.: +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 an active or locked Equinix-registered username.

workPhonePrefToCall Yes string ANYTIME

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

This is mandatory for the Technical contact.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'workPhoneTimeZone' is mandatory.

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.

 

E.g. Area/Location

 

This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.

mobilePhoneCountryCode No string  +1  

Country code for mobile phone number of 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 MY_BUSINESS_HOURS

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls on their mobile phone anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'mobilePhoneTimeZone' is mandatory. 

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

 

E.g. Area/Location

 

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. 

 

{
  "OrderNumber": "1-190986534844"
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
OrderNumber string 1-190986534844 The order number created after order is submitted. 

 

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

 


body: 
How to order photos or documentation of your cage?

 

 


body: 
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. 

 


body: 
Step 2: Get Smart Hands Details

 

To get Smart Hands details, the user must have 'Smart Hands' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

2a) Get Smart Hands Types

Retrieve all the Smart Hands categories supported by Equinix.

 

Refer to Get Smarthands Types under the API Reference section for instructions on how to get all Smart Hands types. You may skip this step if you already know the Smart Hands type. 

 

2b) 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 Smarthands 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.

 


body: 
How to order to move patch cables?

 

 


body: 
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. 

 


body: 
Step 2: Get Smart Hands Details

 

To get Smart Hands details, the user must have 'Smart Hands' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

2a) Get Smart Hands Types

Retrieve all the Smart Hands categories supported by Equinix.

 

Refer to Get Smarthands Types under the API Reference section for instructions on how to get all Smart Hands types. You may skip this step if you already know the Smart Hands type. 

 

2b) 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 Smarthands 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.

 


body: 
Step 3: Order Move Patch Cables

POST Smarthands MoveJumperCable

POST /smarthands/moveJumperCable

 Method

 POST

 URL or End Point

 /v1/orders/smarthands/moveJumperCable

 Headers

 Authorization, Content-Type

 Query Parameters

 Not applicable

 Body

 ibxLocation {ibx, cages [{cage, cabinets[...], accountNumber}]}, serviceDetails
{quantity, cableId, currentDeviceDetails {name, slot, port}, newDeviceDetails {name, slot, port}, scopeOfWork, needSupportFromASubmarineCableStationEngineer}, attachments [{id, name}], schedule {scheduleType, requestedStartDate, requestedCompletionDate}, customerReferenceNumber, purchaseOrder {purchaseOrderType, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}, {contactType, userName}, {contactType, userName}]

 

The Post smarthands moveJumperCable API orders patch cables to be moved between devices by an Equinix IBX Technician. This can only be done by a user with 'Smart Hands' 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 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 API.

 

The request indicates four scenarios: 

(A) An order to move a patch cable without additional information, attachments, or contacts

(B) An order to move a patch cable with additional information, attachments, and contacts

(C) An order to move multiple patch cables with additional information, attachments, and contacts

(D) An order to move multiple patch cables with additional information, attachments, and contacts. 

 

The response indicates the order was successful and returned the order number. 

 

(A) Move a patch cable without additional information, attachments, or contacts

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/moveJumperCable"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "quantity": "1",
    "scopeOfWork": "Move cable from Server01 to Server 09, and ensure cable tag is easily seen at all times. Cable ID is 1-12345-67890. Any available slots or ports."
  },
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "userName": "johndoe",
      "workPhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

 

(B) Move a patch cable with additional information, attachments, and contacts

 

Before creating an order with attachment, call the Post Attachment File under the API Reference section.

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/moveJumperCable"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
  "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "quantity": "1",
    "cableId": "1-12345-67890",
    "currentDeviceDetails": {
      "name": "NH-Server-01",
      "slot": "50",
      "port": "50"
    },
    "newDeviceDetails": {
      "name": "NH-Server-09",
      "slot": "Next Available",
      "port": "Next Available"
    },
    "scopeOfWork": "Refer to attachment for cable details.",

    "needSupportFromASubmarineCableStationEngineer": true
  },
  "attachments": [
    {
      "id": "fcb4a673-6308-456e-8f83-f745501d60ba",
      "name": "MoveCablesInstructions.docx"
    }
  ],
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "customerReferenceNumber": "EQX-PO2019-08-001",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@corporation.com",
      "workPhoneCountryCode": "+44",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Europe/London",
      "mobilePhoneCountryCode": "+44",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "MY_BUSINESS_HOURS",
      "mobilePhoneTimeZone": "Europe/London"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "jillsnow"
    }
  ]
}'

 

(C) Move multiple patch cables without additional information, attachments, or contacts

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/moveJumperCable"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
  "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "cabinets": [
          "AM1:0J:00JD11:0001"
        ],
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "quantity": "12+",
    "scopeOfWork": "Move all cables from Server01 to Server 09, and ensure cable tag is easily seen at all times. Any available slots or ports"
  },
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "userName": "johndoe",
      "workPhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

 

(D) Move multiple patch cables with additional information, attachments, and contacts

 

Before creating an order with attachment, call the Post Attachment File under the API Reference section.

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/moveJumperCable"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "cabinets": [
          "AM1:0J:00JD11:0001"
        ],
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "quantity": "12+",
    "scopeOfWork": "Refer to attachment for cable details.",
    "needSupportFromASubmarineCableStationEngineer": true
  },
  "attachments": [
    {
      "id": "fcb4a673-6308-456e-8f83-f745501d60ba",
      "name": "MoveCablesInstructions.docx"
    }
  ],
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "customerReferenceNumber": "EQX-PO2019-08-001",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@corporation.com",
      "workPhoneCountryCode": "+44",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Europe/London",
      "mobilePhoneCountryCode": "+44",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "MY_BUSINESS_HOURS",
      "mobilePhoneTimeZone": "Europe/London"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "jillsnow"
    }
  ]
}'

 

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 the cages information and IBX. 

ibx Yes string AM1  

The IBX location code.

 

E.g. AM1 is an IBX data centre in Amsterdam, Netherlands. 

cages Yes array[objects]    

Cages information consists of ID of cage, ID of cabinet, and cage account number.

 

Only 1 cage per order is currently being supported. Provide information for only 1 cage.

cage Yes string AM1:0J:00JD11  

ID of the cage.

cabinets No array[strings] AM1:0J:00JD11:0001  

ID of the cabinet.

 

If providing cabinet, provide only 1 cabinet ID. Only 1 cabinet is currently being supported per cage.

accountNumber Yes string 126854  

The customer account number that is linked to the cage.

serviceDetails Yes object      Service details consists of cross connections information.
quantity Yes string 1 1, 
2, 
3, 
4, 
5, 
6, 
7, 
8, 
9, 
10, 
11, 
12, 
12+ 

The total number of jumper cables to be moved. 

 

You may choose to include the cable and device specifications in the following ways ;-

a) as cableId, newDeviceDetails, and currentDeviceDetails fields (This is recommended when quantity is '1'.)

b) in the scopeOfWork information, or

c) in an attachment.

 

If there are multiple cables being moved, it is recommended to provide the following details in the scopeOfWork information, or in an attachment (if the specifications exceeds the scopeOfWork field) for each cable:

1. Cable ID (if applicable)
2. Current Device : Name, Slot, and Port.

3. New Device: Name, Slot, and Port.

cableId No string 1-12345-67890

 

The cable ID number. This is free text input.

 

This is recommended when quantity is '1'.

currentDeviceDetails No object    

The details of the current device where the cable is connected. 

 

This is recommended when quantity is '1'.

name No string NH-Server-01

 

The name of the current device. This is free text input.  

 

This is recommended when quantity is '1'.

 

This field can only be up to 200 characters long.

slot No string 50

 

The slot in the current device where the cable is connected. This is free text input. 

 

This is recommended when quantity is '1'.

 

This field can only be up to 50 characters long.

port No string 50  

The port in the current device where the cable is connected. This is free text input. 

 

This is recommended when quantity is '1'.

 

This field can only be up to 50 characters long.

newDeviceDetails No object    

The details of the new device to connect the cable to. 

 

This is recommended when quantity is '1'.

name No string NH-Server-09  

The name of the new device. This is free text input. 

 

This is recommended when quantity is '1'.

 

This field can only be up to 200 characters long.

slot No string Next Available  

The slot in the new device where the cable should be connected. This is free text input. 

 

This is recommended when quantity is '1'.

 

This field can only be up to 50 characters long.

port No string Next Available  

The port in the new device where the cable should be connected. This is free text input. 

 

This is recommended when quantity is '1'.

 

This field can only be up to 50 characters long.

scopeOfWork Yes string

Move cable(s) from Server01 to Server 09, and ensure cable tag is easily seen at all times. Cable ID is 1-12345-67890. Any available slots or ports ,

 

 

Refer to attachment for cable details ,

 

 

Move all cables from Server01 to Server 09, and ensure cable tag is easily seen at all times. Any available slots or ports

 

A detailed description of the scope of work. This is free text input.

 

If there are multiple cables being moved, it is recommended to provide the following details here, or in an attachment (if the specifications exceeds the character limit) for each cable:

1. Cable ID (if applicable)
2. Current Device : Name, Slot, and Port.

3. New Device: Name, Slot, and Port.

 

This field can only be up to 4000 characters long.

needSupportFromASubmarineCableStationEngineer Conditional boolean true

true, 

false

Requirement for submarine cable station engineer support.

 

This is mandatory for customers with Monet accounts.

 

If 'true', submarine cable station engineer support is required. 

If 'false', submarine cable station engineer support is not required. 

 

Default value: false

attachments No array[objects]    

An array containing the attachment details.

 

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.

 

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

id Conditional string

fcb2k8763-2947-456e-

8d68-f280753d60ba

 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

name Conditional string MoveCablesInstructions.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.

 

Refer to Post Attachment File under the API Reference section for more information. 

schedule Yes object     Schedule information that includes schedule type, and the starting and ending dates and times for the schedule.
scheduleType Yes string SCHEDULED_MAINTENANCE

STANDARD,

EXPEDITED,

SCHEDULED_MAINTENANCE

Define your preferred scheduling type.

 

 

Schedule Types 
 

STANDARD: Request will be processed in the standard turnaround time. Most requests are completed within 24 to 72 hours pending your install base readiness. Requests will be processed in the order they were received, unless they are expedited.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are not required. 

 

EXPEDITED: Request will be completed within the next 2 to 24 hours. Additional Smart Hands fees may apply. Schedule a time in the current local time of the IBX you selected. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameter 'requestedCompletionDate' is required. 

 

SCHEDULED_MAINTENANCE: Request will be scheduled as Customer Requested Maintenance. Additional Smart Hands fees may apply if your scheduled time is less than 24 hours from when the order is submitted. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are required.  

requestedStartDate Conditional string 2019-08-30T22:00:49.776Z  

Requested start date and time.

 

If 'STANDARD' or 'EXPEDITED' schedule type, this parameter is not required.

 

If 'SCHEDULED_MAINTENANCE' schedule type, 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.

requestedCompletionDate Conditional string 2019-08-31T22:00:49.776Z  

Requested end date and time.

 

If 'STANDARD' schedule type, this parameter is not required.

 

If 'EXPEDITED'  or 'SCHEDULED_MAINTENANCE' schedule type, 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.

 

Expedited scheduling date should not be less than IBX local time + 2 hours, and no more than IBX local time + 24 hours.

 

Scheduled maintenance scheduling should not be less than 24 hours from when the order is submitted. Otherwise, additional Smart Hands fees may apply.

customerReferenceNumber No string EQX-PO2019-08-001  

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

 

This can be a Purchase Order number or 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. 

 

If you do not know your account's PO bearing status, refer to Get Smarthands Locations under the API Reference section.

purchaseOrderType Conditional string EXEMPTED

EXISTING,

EXEMPTED

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

 

However, only existing and exempted purchase order types are currently being 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, and a purchase order number is not required. 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 Conditional 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.

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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. All three contacts are mandatory.

 

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

- Technical contact person: Person who Equinix can reach out to for technical clarifications. Only one Technical 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.

userName Yes string

johndoe

      

 

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

 

E.g. If 'email' and 'workPhone' information is passed with 'userName' for Notification contact, this information will be ignored.

name Conditional string Jane Smith  

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

email Conditional string janesmith@corporation.com
      
 

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

workPhoneCountryCode No string +44
      
 

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

 

E.g.: +571

 

It is recommended to include the work phone country code.

workPhone Yes string 0148211111  

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

 

This is mandatory for the Technical contact.

workPhonePrefToCall Yes string ANYTIME

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

This is mandatory for the Technical contact.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'workPhoneTimeZone' is mandatory.

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.

 

E.g. Area/Location

 

This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.

mobilePhoneCountryCode No string  +1  

Country code for mobile phone number of 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 MY_BUSINESS_HOURS

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls on their mobile phone anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'mobilePhoneTimeZone' is mandatory. 

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

 

E.g. Area/Location

 

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. 

 

{
  "OrderNumber": "1-190986534844"
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
OrderNumber string 1-190986534844 The order number created after order is submitted. 

 

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

 


body: 
How to order to run jumper cables?

 

 


body: 
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. 

 


body: 
Step 2: Get Smart Hands Details

 

To get Smart Hands details, the user must have 'Smart Hands' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

2a) Get Smart Hands Types

Retrieve all the Smart Hands categories supported by Equinix.

 

Refer to Get Smarthands Types under the API Reference section for instructions on how to get all Smart Hands types. You may skip this step if you already know the Smart Hands type. 

 

2b) 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 Smarthands 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.

 


body: 
Step 3: Order Run Jumper Cables 

POST Smarthands Run Jumper Cable

POST /smarthands/runJumperCable

 Method

 POST

 URL or End Point

 /v1/orders/smarthands/runJumperCable

 Headers

 Authorization, Content-Type

 Query Parameters

 Not applicable

 Body

 ibxLocation {ibx, cages [{cage, cabinets[...], accountNumber}]}, serviceDetails {quantity, jumperType, mediaType, connector, cableId, provideTxRxLightLevels, deviceDetails[{name, slot, port}, {name, slot, port}], scopeOfWork, needSupportFromASubmarineCableStationEngineer}, attachments [{id, name}], schedule {scheduleType, requestedStartDate, requestedCompletionDate}, customerReferenceNumber, purchaseOrder {purchaseOrderType, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}, {contactType, userName}, {contactType, userName}]

 

The Post smarthands runJumperCable API orders jumper cables to be run between devices by an Equinix IBX Technician. This can only be done by a user with 'Smart Hands' 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 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 API.

 

The request indicates four scenarios: 

(A) An order to run a jumper cable without additional information, attachments, or contacts

(B) An order to run a jumper cable with additional information, attachments, and contacts

(C) An order to run multiple jumper cables without additional information, attachments, or contacts

(D) An order to run multiple jumper cables with additional information, attachments, and contacts

 

The response indicates the order was successful and returned the order number. 

 

(A) Run a jumper cable without additional information, attachments, or contacts

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/runJumperCable"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "quantity": "1",
    "jumperType": "Jumper",
    "mediaType": "Multi-mode 62.5mic",
    "connector": "RJ45",
    "provideTxRxLightLevels": true,
    "deviceDetails": [
      {
        "name": "Device1: NH-Server-01",
        "slot": "1",
        "port": "1"
      }
    ],
    "scopeOfWork": "Run cable(s) from Server01 to Server 09, and ensure cable tag is easily seen at all times."
  },
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "userName": "johndoe",
      "workPhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

 

(B) Run a jumper cable with additional information, attachments, and contacts

 

Before creating an order with attachment, call the Post Attachment File under the API Reference section.

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/runJumperCable"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "quantity": "1",
    "jumperType": "Jumper",
    "mediaType": "Multi-mode 62.5mic",
    "connector": "RJ45",
    "cableId": "1-12345-67890",
    "provideTxRxLightLevels": true,
    "deviceDetails": [
      {
        "name": "Device1: NH-Server-01",
        "slot": "1",
        "port": "1"
      },
      {
        "name": "Device2: NH-Server-09",
        "slot": "1",
        "port": "1"
      }
    ],
    "scopeOfWork": "Refer to attachment for cable details.",
    "needSupportFromASubmarineCableStationEngineer": true
  },
  "attachments": [
    {
      "id": "fcb4a673-6308-456e-8f83-f745501d60ba",
      "name": "RunCablesInstructions.docx"
    }
  ],
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "customerReferenceNumber": "EQX-PO2019-08-001",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@corporation.com",
      "workPhoneCountryCode": "+44",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Europe/London",
      "mobilePhoneCountryCode": "+44",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "MY_BUSINESS_HOURS",
      "mobilePhoneTimeZone": "Europe/London"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "janesnow"
    }
  ]
}'

 

(C) Run multiple jumper cables without additional information, attachments, or contacts

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/runJumperCable"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "quantity": "12+",
    "provideTxRxLightLevels": true,
    "scopeOfWork": "Run cable(s) from Server01 to Server 09, and ensure cable tag is easily seen at all times."
  },
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "userName": "johndoe",
      "workPhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

 

(D) Run multiple jumper cables with additional information, attachments, and contacts

 

Before creating an order with attachment, call the Post Attachment File under the API Reference section.

 

curl -X

POST "https://api.equinix.com/v1/orders/smarthands/runJumperCable"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "cabinets": [
          "AM1:0J:00JD11:0001"
        ],
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "quantity": "12+",
    "provideTxRxLightLevels": true,
    "scopeOfWork": "Refer to attachment for cable details.",
    "needSupportFromASubmarineCableStationEngineer": true
  },
  "attachments": [
    {
      "id": "fcb4a673-6308-456e-8f83-f745501d60ba",
      "name": "RunCablesInstructions.docx"
    }

  ],
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "customerReferenceNumber": "EQX-PO2019-08-001",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@corporation.com",
      "workPhoneCountryCode": "+44",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Europe/London",
      "mobilePhoneCountryCode": "+44",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "MY_BUSINESS_HOURS",
      "mobilePhoneTimeZone": "Europe/London"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "janesnow"
    }
  ]
}'

 

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 the cages information and IBX. 

ibx Yes string AM1  

The IBX location code.

 

E.g. AM1 is an IBX data centre in Amsterdam, Netherlands. 

cages Yes array[objects]    

Cages information consists of ID of cage, ID of cabinet, and cage account number.

 

Only 1 cage per order is currently being supported. Provide information for only 1 cage.

cage Yes string AM1:0J:00JD11  

ID of the cage.

cabinets No array[strings] AM1:0J:00JD11:0001  

ID of the cabinet.

 

If providing cabinet, provide only 1 cabinet ID. Only 1 cabinet is currently being supported per cage.

accountNumber Yes string 126854  

The customer account number that is linked to the cage.

serviceDetails Yes object      Service details consists of cross connections information.
quantity Yes string 1 1, 
2, 
3, 
4, 
5, 
6, 
7, 
8, 
9, 
10, 
11, 
12, 
12+ 

The total number of jumper cables to run. 

 

If the quantity requested is 1, the following parameters are mandatory: 'jumperType', 'mediaType', 'connector', 'provideTxRxLightLevels', and 'deviceDetails'. The parameter 'cableId' may also be provided.

 

If there are multiple cables being requested, it is recommended to provide the following details in the scopeOfWork information, or in an attachment (if the specifications exceeds the scopeOfWork field) for each cable:

 

1. Jumper Type

 

2. Media Type

 

3. Connector Type

 

4. Cable ID (optional)

 

5. Should Equinix provide you Tx/Rx light levels, Yes Or No?

 

6. Devices to Connect

 

Device #1:

Name/Panel:
Device Slot:
Device Ports:

 

Device #2(Optional):
Name/Panel:
Device Slot:
Device Ports:

 

7. If any device is being shipped to Equinix, please include the shipment number.

 

You may mix jumper types but if you require more than 12 jumpers ran, the site will contact you for scheduling of your request based on parts and availability. Please select the best option for your scheduling needs.

jumperType Conditional string Jumper Jumper, 
Pre-Wiring, 
Patch Cable, 
Other 

The type of jumper cable to run.

 

This is mandatory when quantity requested is '1'.

mediaType Conditional string Multi-mode 62.5mic Multi-mode 62.5mic, 
Multi-mode 50mic, 
Single-mode, 
Cat-5, 
Cat-6, 
Coax, 
POTS, 
T1, 
E1

Preferred media type of requested cable.

 

This is mandatory when quantity requested is '1'.

connector Conditional string RJ45 RJ45, 
SC, 
LC, 
BNC, 
Other 

Preferred connector type of requested cable.

 

This is mandatory when quantity requested is '1'.

cableId No string 1-12345-67890

 

The cable ID number. This is free text input.

 

This field can only be up to 50 characters long.

provideTxRxLightLevels Conditional boolean true

true, 

false

Requirement for light reading and tx/rx verification to be provided. 

If  'true', light reading and tx/rx verification will be provided once the cables are run.

If 'false', light reading or tx/rx verification will not be provided.

 

This is mandatory when quantity requested is '1'.

deviceDetails Conditional array[objects]    

The details of the device(s) to run the cables. 

 

At least one object of device details representing one device is mandatory when quantity requested is '1'. An object representing one device consists of the name, slot, and port of the device. A second object of device details when quantity requested is '1'is optional. There should be no more than two objects of device details. 

 

This is mandatory when quantity requested is '1'.

name Conditional string Device1: NH-Server-01

 

The name of the device. This is free text input. 

 

This field can only be up to 200 characters long.

 

This is mandatory when including the parameter 'deviceDetails'.

slot Conditional string 50

 

The slot of device where the cable is connected. This is free text input. 

 

This field can only be up to 50 characters long.

 

This is mandatory when including the parameter 'deviceDetails'.

port Conditional string 50  

The port of the device where the cable is connected. This is free text input. 

 

This field can only be up to 50 characters long.

 

This is mandatory when including the parameter 'deviceDetails'.

scopeOfWork Yes string

Run cable(s) from Server01 to Server 09, and ensure cable tag is easily seen at all times.,

 

Refer to attachment for cable details.

 

A detailed description of the scope of work. This is free text input.

 

If there are multiple cables being requested, it is recommended to provide the following details in the scopeOfWork information, or in an attachment (if the specifications exceed the scopeOfWork field) for each cable:

 

1. Jumper Type

 

2. Media Type

3. Connector Type

4. Cable ID (optional)

5. Should Equinix provide you Tx/Rx light levels, Yes Or No?

6. Devices to Connect:

Device #1:
Name/Panel:
Device Slot:
Device Ports:

Device #2(Optional):
Name/Panel:
Device Slot:
Device Ports:

 

7. If any device is being shipped to Equinix, please include the shipment number.

You may mix jumper types but if you require more than 12 jumpers ran, the site will contact you for scheduling of your request based on parts and availability. Please select the best option for your scheduling needs.

 

This field can only be up to 4000 characters long.

needSupportFromASubmarineCableStationEngineer Conditional boolean true

true, 

false

Requirement for submarine cable station engineer support.

 

This is mandatory for customers with Monet accounts.

 

If 'true', submarine cable station engineer support is required. 

If 'false', submarine cable station engineer support is not required. 

 

Default value: false

attachments No array[objects]    

An array containing the attachment details.

 

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.

 

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

id Conditional string

fcb2k8763-2947-456e-

8d68-f280753d60ba

 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

name Conditional string

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

 

Refer to Post Attachment File under the API Reference section for more information. 

schedule Yes object      Schedule information that includes schedule type, and the starting and ending dates and times for the schedule.
scheduleType Yes string SCHEDULED_MAINTENANCE

STANDARD,

EXPEDITED,

SCHEDULED_MAINTENANCE

Define your preferred scheduling type.

 

Schedule Types 
 

STANDARD: Request will be processed in the standard turnaround time. Most requests are completed within 24 to 72 hours pending your install base readiness. Requests will be processed in the order they were received, unless they are expedited.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are not required. 

 

EXPEDITED: Request will be completed within the next 2 to 24 hours. Additional Smart Hands fees may apply. Schedule a time in the current local time of the IBX you selected. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameter 'requestedCompletionDate' is required. 

 

SCHEDULED_MAINTENANCE: Request will be scheduled as Customer Requested Maintenance. Additional Smart Hands fees may apply if your scheduled time is less than 24 hours from when the order is submitted. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameters 'requestedStartDate' and 'requestedCompletionDate' are required.  

requestedStartDate Conditional string 2019-08-30T22:00:49.776Z  

Requested start date and time.

 

If 'STANDARD' or 'EXPEDITED' schedule type, this parameter is not required.

 

If 'SCHEDULED_MAINTENANCE' schedule type, 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.

requestedCompletionDate Conditional string 2019-08-31T22:00:49.776Z  

Requested end date and time.

 

If 'STANDARD' schedule type, this parameter is not required.

 

If 'EXPEDITED'  or 'SCHEDULED_MAINTENANCE' schedule type, 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.

 

Expedited scheduling date should not be less than IBX local time + 2 hours, and no more than IBX local time + 24 hours.

 

Scheduled maintenance scheduling should not be less than 24 hours from when the order is submitted. Otherwise, additional Smart Hands fees may apply.

customerReferenceNumber No string EQX-PO2019-08-001  

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

 

This can be a Purchase Order number or 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. 

 

If you do not know your account's PO bearing status, refer to Get Smarthands Locations under the API Reference section.

purchaseOrderType Conditional string EXEMPTED

EXISTING,

EXEMPTED

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

 

However, only existing and exempted purchase order types are currently being 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, and a purchase order number is not required. 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 Conditional 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.

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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. All three contacts are mandatory.

 

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

- Technical contact person: Person who Equinix can reach out to for technical clarifications. Only one Technical 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.

userName Yes string

johndoe,

 

janesnow
      

 

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

 

E.g. If 'email' and 'workPhone' information is passed with 'userName' for Notification contact, this information will be ignored.

name Conditional string Jane Smith  

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

email Conditional string janesmith@corporation.com
      
 

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

workPhoneCountryCode No string +44
      
 

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

 

E.g.: +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 an active or locked Equinix-registered username.

workPhonePrefToCall Yes string ANYTIME

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

This is mandatory for the Technical contact.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'workPhoneTimeZone' is mandatory.

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.

 

E.g. Area/Location

 

This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.

mobilePhoneCountryCode No string  +1  

Country code for mobile phone number of 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 MY_BUSINESS_HOURS

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls on their mobile phone anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'mobilePhoneTimeZone' is mandatory. 

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

 

E.g. Area/Location

 

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. 

 

{
  "OrderNumber": "1-190986534844"
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
OrderNumber string 1-190986534844 The order number created after order is submitted. 

 

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

 


body: 

How to create a Cross Connect order


body: 
How to order a standard cross connect?

 

 


body: 
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. 

 


body: 
Step 2: Check cross connect permissions

 

To get cross connect types, the user must have 'Cross Connect & Intra-Facility Cables' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

Get Cross Connect Types

Retrieve the cross connect types that the user has permission to order.
 

Use this API to determine if the user can order the preferred cross connect type.

 

Refer to Get Crossconnect Types under the API Reference section for instructions on how to retrieve available cross connect types. You may skip this step if you already know the user has permission to order this cross connect type.


body: 
Step 3: Get Cross Connect Details

 

To get cross connect details, the user must have 'Cross Connect & Intra-Facility Cables' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

3a) Get Cross Connect Location information for the starting point of the cross connect (A-side)

Retrieve the IBX location information for the preferred cross connect type.
 

Use this API to determine the exact IBX location code, cage ID, cage account number, and cabinet ID for your A-side criteria.

 

Refer to Get Crossconnect Locations under the API Reference section for instructions on how to get all the cross connect location information. You may skip this step if you already know the location information for your A-side.  

 

3b) Get Connection Services information for your A-side criteria 

Retrieve all the connection services information. 
 

Use this API to determine which connection service, media type, connector type, and protocol type to use for your A-side criteria.

 

Refer to Get Crossconnect Connection Services under the API Reference section for instructions on how to retrieve available connection services. You may skip this step if you already know the connection services information for your A-side.

 

3c) Get Patch Panel information for your A-side criteria 

Retrieve all the patch panel information for the preferred cross connect type. 
 

Use this API to identify the patch panel number, and the patch panel ports to use for the selected connection service. This will fulfill the A-side criteria patch panel information that consists of patch panel serial number, port A, and port B.

 

Refer to Get Crossconnect Patchpanel under the API Reference section for instructions on how to get all the patch panel information. You may skip this step if you already know the patch panel information for your A-side.  

 

3d) Get Service Providers information (end point of the cross connect i.e. Z-side)

Retrieve all the service providers information for the preferred cross connect type. 
 

Use this API to retrieve the service provider's account name and account number. This will fulfill the Z-side criteria customer name and customer account number.

 

Refer to Get Crossconnect Providers under the API Reference section for instructions on how to get the service provider's information. You may skip this step if you already know the service provider's information.  

 

3e)Get your Z-side criteria details by repeating steps 3a to 3c 

Retrieve all the same details from steps 3a to 3c for the Z-side criteria.

 

3f) Get Circuit ID for your Z-side criteria

Retrieve the Circuit ID cable reference number from your Z-side for verification purposes.
 

Refer to your service provider for their Circuit ID cable reference number. You may skip this step if you already know the Circuit ID.  

 


body: 
Step 4: Order a Standard Cross Connect

Post Crossconnect Standard

POST /crossconnect/standard

 Method  POST
 URL or End Point  /v1/orders/crossconnect/standard
 Headers  Authorization, Content-Type
 Query Parameters  action
 Body

 quantityRequested, customerReferenceNumber, purchaseOrder {purchaseOrderType, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall, mobilePhoneTimeZone}, {contactType, username}]}, schedule {requestedCompletionDate, scheduleType}, additionalDetails, attachments [{id, name}], serviceDetails{aside {ibxLocation {ibx, cages [{cage, cabinets[...], accountNumber}]}, connectionService, mediaType, proceedIfMediaCoverterIsRequired, protocolType, connectorType, focDate, patchpanel {name, portA, portB}}, zside {customer, customerAccount, ibxLocation {ibx, cages [{cage, cabinets[...]}]}, connectionService, connectorType, patchpanel {name, portA, portB}, circuitId, loa [attachments{id, name}]}, notifyZsideUponCompletion, zSideContactEmail}, patchEquipment, device {cabinet, connectorType, details, port}, lightLinkVerificationRequired, needSupportFromASubmarineCableStationEngineer}

 

The Post crossconnect standard API creates a standard cross connect 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.

 

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 API. There is a request for a standard cross connect without additional information or attachment, and a standard cross connect with additional information and attachment. The response indicates the order was successful and returned the order number, order reference number, and service request number. 

 

Standard cross connect order without additional information or attachment 

 

curl -X

POST "https://api.equinix.com/v1/orders/crossconnect/standard?action=SUBMIT"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe1"
    },
    {
      "contactType": "TECHNICAL",
      "userName": "johndoe1",
      "workPhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe1"
    }
  ],
  "schedule": {
    "requestedCompletionDate": "2019-07-25T01:59:58.201Z",
    "scheduleType": "EXPEDITED"
  },
  "serviceDetails": {
    "aside": {
      "ibxLocation": {
        "ibx": "DA1",
        "cages": [
          {
            "cage": "DA1:R1:V0350-1-254",
            "cabinets": [
              "DA1:R1:V0350-1-254:V001002"
            ],
            "accountNumber": "987"
          }
        ]
      },
      "connectionService": "COAX",
      "mediaType": "COAX",
      "protocolType": "ANTENNA",
      "connectorType": "BNC",
      "patchpanel": {
        "name": "PP:0102:2345",
        "portA": "Next Available",
        "portB": "Next Available"
      }
    },
    "zside": {
      "customerAccount": "3988",
      "ibxLocation": {
        "ibx": "DA3",
        "cages": [
          {
            "cage": "DA3:001:0100300",
            "cabinets": [
              "DA3:001:0100300:00206"
            ]
          }
        ]
      },
      "connectionService": "COAX",
      "connectorType": "BNC",
      "patchpanel": {
        "name": "CP:0206:102232",
        "portA": "5",
        "portB": "Next Available"
      },
      "circuitId": "73/HCGS/123456/000/CC",
      "loa": {
        "attachments": []
      }
    }
  }
}'

 

Standard cross connect order with additional information and attachments

 

Before creating an order with attachment, call the Post Attachment File under the API Reference section.

 

curl -X

POST "https://api.equinix.com/v1/orders/crossconnect/standard?action=SUBMIT"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "quantityRequested": 1,
  "customerReferenceNumber": "SCC138765",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe1"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@thiscorp.com",
      "workPhoneCountryCode": "+1",
      "workPhone": "800-322-9280",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "America/Chicago",
      "mobilePhoneCountryCode": "+1",
      "mobilePhone": "555-555-1234",
      "mobilePhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe1"
    }
  ],
  "schedule": {
    "requestedCompletionDate": "2019-07-25T01:59:58.201Z",
    "scheduleType": "EXPEDITED"
  },
  "additionalDetails": "Refer to attachment.",
  "attachments": [
    {
      "id": "507f8877-4894-4ca6-ac9f-3995c59a4ce6",
      "name": "AdditionalDetailsAttachment.docx"
    }
  ],
  "serviceDetails": {
    "aside": {
      "ibxLocation": {
        "ibx": "DA1",
        "cages": [
          {
            "cage": "DA1:R1:V0350-1-254",
            "cabinets": [
              "DA1:R1:V0350-1-254:V001002"
            ],
            "accountNumber": "987"
          }
        ]
      },
      "connectionService": "COAX",
      "mediaType": "COAX",
      "proceedIfMediaCoverterIsRequired": false,
      "protocolType": "ANTENNA",
      "connectorType": "BNC",
      "focDate": "2019-07-25T01:59:58.201Z",
      "patchpanel": {
        "name": "PP:0102:2345",
        "portA": "Next Available",
        "portB": "Next Available"
      }
    },
    "zside": {
      "customer": "Carigan Communications",
      "customerAccount": "3988",
      "ibxLocation": {
        "ibx": "DA3",
        "cages": [
          {
            "cage": "DA3:001:0100300",
            "cabinets": [
              "DA3:001:0100300:00206"
            ]
          }
        ]
      },
      "connectionService": "COAX",
      "connectorType": "BNC",
      "patchpanel": {
        "name": "CP:0206:102232",
        "portA": "5",
        "portB": "Next Available"
      },
      "circuitId": "73/HCGS/123456/000/CC",
      "loa": {
        "attachments": [
          {
            "id": "0549c413-acc9-4c4b-9067-e7551890b46d",
            "name": "LOA2017/36912.docx"
          }
        ]
      },
      "notifyZsideUponCompletion": true,
      "zSideContactEmail": "johndoe@corp.com"
    },
    "patchEquipment": true,
    "device": {
      "cabinet": "V0102",
      "connectorType": "BNC",
      "details": "Call the technical contact before patching.",
      "port": "any available"
    },
    "lightLinkVerificationRequired": true,
    "needSupportFromASubmarineCableStationEngineer": true
  }
}'

 

The description of the query and request payload is as follows:

 

Query Parameter Name Mandatory Type Example Applicable Values Description
action Yes string

SUBMIT

SUBMIT

The action to submit the order.

 

 

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

 

Body Parameter Name Mandatory Type Example Applicable Values Description
quantityRequested No integer 1 1

Number of cross connects ordered.

 

Default value:1

 

Currently, Equinix does not support multi-quantity, so “quantityRequested” will be considered as 1 by default.

customerReferenceNumber No string SCC138765  

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

 

This can be a Purchase Order number or 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. 

 

If you do not know your account's PO bearing status, refer to Get Crossconnect Locations under the API Reference section.

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 being 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, and a purchase order number is not required. 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 Conditional 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 Attachment 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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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. All three contacts are mandatory.

 

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

- Technical contact person: Person who Equinix can reach out to for technical clarifications. Only one Technical 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.

userName Yes string johndoe1  

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.

 

E.g. If 'email' and 'workPhone' information is passed with 'userName' for Notification contact, this information will be ignored.

name Conditional string Jane Smith  

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

email Conditional string janesmith@thiscorp.com  

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

workPhoneCountryCode No string +1  

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

 

E.g.: +571

 

It is recommended to include the work phone country code. 

workPhone Conditional string 800-322-9280

 

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

workPhonePrefToCall Yes string MY_BUSINESS_HOURS

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'workPhoneTimeZone' is mandatory.

workPhoneTimeZone Conditional string America/Chicago 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.

 

E.g. Area/Location

 

This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.

mobilePhoneCountryCode No string +1

 

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

 

Example: +571

mobilePhone No string 555-555-1234  

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 anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'mobilePhoneTimeZone' is mandatory. 

mobilePhoneTimeZone Conditional 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.

 

E.g. Area/Location

 

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. 

schedule Yes

object

    Scheduling information for the installation of the cross connect order.  
requestedCompletionDate Conditional string 2019-07-25T01:59:58.201Z  

Requested completion date and time of scheduled cross connect installation. 

 

Expedited scheduling date should not be less than IBX local time + 2 hours, and no more than IBX local time + 24 hours.

 

If 'EXPEDITED' schedule type, 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.

 

In the case of 'STANDARD' schedule type, this parameter is not required.

scheduleType Yes string EXPEDITED

EXPEDITED,

STANDARD

Define your preferred scheduling type.

 

These are the scheduling types supported for this cross connect.

 

Schedule Types 
 

STANDARD: Request will be processed in the standard turnaround time. Most requests are completed within 24 to 72 hours pending your install base readiness. Requests will be processed in the order they were received, unless they are expedited.
- Parameter 'requestedCompletionDate' is not required. 

 

EXPEDITED: Request will be completed within the next 2 to 24 hours. Additional Smart Hands fees may apply. Schedule a time in the current local time of the IBX you selected. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameter 'requestedCompletionDate' is required. 

additionalDetails No string Refer to attachment.  

Additional details the Equinix Technician may need to complete your request. This is free text input.

 

This field can only be up to 4000 characters long.

attachments No array[objects]    

Additional attachment. Provide any other supportive photos or documents to help the technician to complete your order. 

 

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

 

Refer to Post Attachment File under the API Reference section for more information. 

id Conditional string 507f8877-4894-4ca6-ac9f-3995c59a4ce6  

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

name Conditional string AdditionalDetailsAttachment.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.

 

Refer to Post Attachment File under the API Reference section for more information. 

serviceDetails Yes object   

 

Service details information consisting of the A-side (starting point of cross connect) and Z-side (end point of cross connect) locations and their corresponding cross connect details. 

aside Yes object     

A-side cross connect information that consists of IBX location information, connection service, media type, media converter requirement, protocol type, connector type, and patch panel information.

ibxLocation Yes object    

IBX location information that consists of the IBX location code, cages information, and cage account number.

 

Refer to Get Crossconnect Locations under the API Reference section for more information. 

ibx Yes string DA1  

The IBX location code.

cages Yes array[objects]    

Cages information consists of ID of cage, ID of cabinet, and cage account number.

 

Only 1 cage per order is currently being supported. Provide information for only 1 cage.

cage Yes string DA1:R1:V0350-1-254  

ID of the cage.

cabinets Yes array[strings] DA1:R1:V0350-1-254:V001002  

ID of the cabinet.

 

If providing cabinet, provide only 1 cabinet ID. Only 1 cabinet is currently being supported per cage.

accountNumber Yes string 987  

The account number linked to the cage.

connectionService Yes string COAX

Multi-Mode Fiber,

Single-Mode Fiber,

UTP,

COAX,

POTS

The name of the available connection service media type.

 

Refer to Get Crossconnect Connection Services under the API Reference section for more information. 

mediaType Yes string COAX

50 MICRON MULTI-MODE FIBER OM3,
62.5 MICRON MULTI-MODE FIBER,

Single-Mode Fiber

CAT5e,

CAT6

COAX

CAT3

Name of the sub-media type that corresponds with the connection service media type.

 

Connection service - Name of media type

Multi-Mode Fiber - 50 Micron Multi-Mode Fiber OM3, 62.5 Micron Multi-Mode Fiber, Fiber Channel.

Single-Mode Fiber - Single-Mode Fiber.

UTP - Cat5e, Cat6.
COAX - COAX

POTS - CAT3

 

Refer to Get Crossconnect Connection Services under the API Reference section for more information. 

proceedIfMediaCoverterIsRequired No boolean True

true,

false

Requirement for media converter. 

 

If 'true', media converter is required. 

 

If 'false', media converter is not required.

 

Default value: false

 

Media converters are not applicable to single mode fiber connections. You should exclude this if your connection service is 'Single-Mode Fiber'.

 

Cross Connect installations that require a media converter due to distance will be held unless 'true' is selected. 

protocolType Yes string ANTENNA

100 GIG ETHERNET,

10 GIG ETHERNET,

40 GIG ETHERNET,

FIBRE CHANNEL,

GIGABIT ETHERNET,

FAST ETHERNET,

DARK FIBER,

DWDM,

OC-12,

OC-192,

OC-3,

OC-48,

STM-1,

STM-16,

STM-4,

STM-64,

56K,

E1,

ETHERNET,

ISDN,

T1,

ANTENNA,

DS-3,

E3,

POTS

Name of the protocol type that corresponds with the name of the media type.

 

Media type - Name of protocol type

50 Micron Multi-Mode Fiber OM3 - 100 Gig Ethernet, 10 Gig Ethernet, 40 Gig Ethernet, Fibre Channel, Gigabit Ethernet.

62.5 Micron Multi-Mode Fiber - Fast Ethernet, Fibre Channel, Gigabit Ethernet.

Single-Mode Fiber - 100 Gig Ethernet, 10 Gig Ethernet, 40 Gig Ethernet, Dark Fibre, DWDM, Fibre Channel, Gigabit Ethernet, OC-12, OC-192, OC-3, OC-48, STM-1, STM-16, STM-4, STM-64.

Cat5e - 56K, E1, Ethernet, Fast Ethernet, Gigabit Ethernet, ISDN, T1.

Cat 6 - 56K, E1, Ethernet, Fast Ethernet, Gigabit Ethernet, ISDN, T1.

COAX - Antenna, DS-3, E3

CAT3 - POTS

 

Refer to Get Crossconnect Connection Services under the API Reference section for more information. 

connectorType Yes string BNC

BNC, 

FC, 

LC, 

RJ45,

SC,

ST

Name of the connector type that corresponds with the name of the connection service media type.

 

Connection service media type - Name of connector type

Multi-Mode Fiber - LC, SC, ST.

Single-Mode Fiber - FC, LC, SC, ST.

UTP - RJ45.
COAX - BNC, LC.

POTS - RJ45, LC.

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

focDate  No string 2019-07-25T01:59:58.201Z  

An FOC (Firm Order Completion) date is the Carrier Circuit delivery date when the Carrier commits to enable the circuit. Your order will be placed on hold, pending the date you enter. Equinix will wait for the Carrier to deliver the service and then will complete the installation.

 

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.

 

If expedited schedule type is selected, this FOC date cannot surpass the date given in the 'requestedCompletionDate' body parameter. 

patchpanel Yes object    

Patch panel information that consists of patch panel serial number and port details.

 

Patch panel and port availability information details can be obtained from using the GET Crossconnect Patchpanel API. 

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

name Yes string PP:0102:2345  

Patch panel number. 

 

Patch panel and port availability information details can be obtained from using the GET Crossconnect Patchpanel API. 

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

portA Yes string Next Available

Next Available

Available port A of patch panel.

 

Patch panel and port availability information details can be obtained from using the GET Crossconnect Patchpanel API. 

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

portB Conditional string Next Available

Next Available

Available port B of patch panel. This is mandatory depending on the connector type.

 

Connector type - Whether port B is mandatory

BNC - mandatory

FC - mandatory

LC - optional

RJ45 - not necessary

SC - mandatory

ST - mandatory

 

Patch panel and port availability information details can be obtained from using the GET Crossconnect Patchpanel API. 

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

zside Yes object     

Z-side cross connect information that consists of customer account name, customer account number, IBX location information, connection service, media type, media converter requirement, protocol type, connector type, and patch panel information. 

 

The following information indicates the mandatory fields for new and existing service providers, both with and without attaching a Letter of Agreement (LOA). 

 

For existing service providers

 

- With LOA: If the provider is an existing service provider and you are attaching an LOA, the following Z-side parameters are mandatory: customerAccount, ibxLocation, ibx, connectionService, patchpanel (left as blank object),  loa, attachments, id, name. The LOA should address all information that is otherwise mandatory. Equinix will contact A and Z sides for further verification before the order can be fulfilled.

 

- Without LOA: If the provider is an existing service provider, the following Z-side parameters are mandatory: customerAccount, ibxLocation, ibx, cages, cage, cabinets, connectionService, connectorType, patchpanel, name, portA, portB, circuitId, loa, attachments, id, name. 

 

For new service providers

 

- With LOA: If the service provider is new and you are attaching an LOA, the following Z-side parameters are mandatory to pass: customerAccount, ibxLocation, ibx, connectionService, loa, attachments, id, name. It is recommended to include the parameter 'customer' to include the new service provider's name. The LOA should address all information that is otherwise mandatory. Equinix will contact A and Z sides for further verification before the order can be fulfilled.

- Without LOA: If you are unable to provide an LOA for the new service provider, the following Z-side parameters are mandatory to pass: customerAccount, ibxLocation, ibx, cages, cage, cabinets, connectionService, circuitId, and loa (left as blank object). It is recommended to include the parameter 'customer' to include the new service provider's name. Equinix will contact A and Z sides for further verification before the order can be fulfilled.

customer No string Carigan Communications  

The account name of the service provider. 

 

For existing service providers

Customers may choose to include this.

 

For new service providers

It is recommended for customer to provide the new service provider's name.  

 

Refer to GET Crossconnect Providers under the API Reference section for more information. 

customerAccount Yes string 3988

 

 

-1

The account number of the service provider. 

 

For new service providers
The customer account number must be '-1'. 

 

Refer to GET Crossconnect Providers under the API Reference section for more information. 

ibxLocation Yes object    

IBX location information that consists of the IBX location code, cages information, and cage account number.

 

Refer to Get Crossconnect Locations under the API Reference section for more information. 

ibx Yes string DA3  

The IBX location code.

 

For existing service providers
This field is mandatory.

 

For new service providers

This field is mandatory and is free text input with a character range of 1 to 40.

cages Conditional array[objects]    

Cages information that consists of cage ID and cabinet ID details.

 

For existing service providers

- With LOA: This field is optional.

- Without LOA: This field is mandatory.

 

For new service providers 

- With LOA: This field is optional.

- Without LOA: This field is mandatory.

 

Only 1 cage per order is currently being supported. Provide information for only 1 cage.

cage Conditional string DA3:001:0100300  

ID of the cage.

 

For existing service providers

- With LOA: This field is optional.

- Without LOA: This field is mandatory.

 

For new service providers 

- With LOA: This field is optional.

- Without LOA: This field is mandatory.

cabinets Conditional array[strings] DA3:001:0100300:00206  

ID of the cabinet.

 

For existing service providers

- With LOA: This field is optional.

- Without LOA: This field is mandatory.

 

For new service providers 

- With LOA: This field is optional.

- Without LOA: This field is mandatory.

 

If providing cabinet, provide only 1 cabinet ID. Only 1 cabinet is currently being supported per cage.

connectionService Yes string COAX

Multi-Mode Fiber,

Single-Mode Fiber,

UTP,

COAX,

POTS

The name of the available connection service.

 

Refer to Get Crossconnect Connection Services under the API Reference section for more information. 

connectorType Conditional string BNC

BNC, 

FC, 

LC, 

RJ45,

SC,

ST

Name of the connector type that corresponds with the connection service.

 

Connection service - Connector type

Multi-Mode Fiber - LC, SC, ST.

Single-Mode Fiber - FC, LC, SC, ST.

UTP - RJ45.
COAX - BNC, LC.

POTS - RJ45, LC.

 

For existing service providers

- With LOA: This field is optional.

- Without LOA: This field is mandatory.

 

For new service providers 

- With LOA: This field is optional.

- Without LOA: This field is mandatory.

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

patchpanel Conditional object    

Patch panel information that consists of patch panel serial number and port details.

 

Patch panel and port availability information details can be obtained from using the GET Crossconnect Patchpanel API. 

 

For existing service providers

- With LOA: This field is optional.

- Without LOA: This field is mandatory.

 

For new service providers 

- With LOA: This field is optional.

- Without LOA: This field is mandatory.

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

name Conditional string CP:0206:102232  

Patch panel serial number. 

 

Patch panel and port availability information details can be obtained from using the GET Crossconnect Patchpanel API. 

 

For existing service providers

- With LOA: This field is optional.

- Without LOA: This field is mandatory.

 

For new service providers 

- With LOA: This field is optional.

- Without LOA: This field is mandatory.

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

portA Conditional string 5

Next Available

Available port A of patch panel. 

 

Patch panel and port availability information details can be obtained from using the GET Crossconnect Patchpanel API. 

 

For existing service providers

- With LOA: This field is optional.

- Without LOA: This field is mandatory.

 

For new service providers 

- With LOA: This field is optional.

- Without LOA: This field is mandatory.

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

portB Conditional string Next Available

Next Available

Available port B of patch panel. This is mandatory depending on the connector type.

 

Connector type - Whether port B is mandatory

BNC - mandatory

FC - mandatory

LC - optional

RJ45 - not necessary

SC - mandatory

ST - mandatory

 

Patch panel and port availability information details can be obtained from using the GET Crossconnect Patchpanel API. 

 

For existing service providers

- With LOA: This field is optional.

- Without LOA: This field is mandatory.

 

For new service providers 

- With LOA: This field is optional.

- Without LOA: This field is mandatory.

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

circuitId Conditional string 73/HCGS/123456/000/CC  

Customer or carrier circuit ID cable reference number for verification purposes. 

 

For existing service providers

- With LOA: This field is optional.

- Without LOA: This field is mandatory.

 

For new service providers 

- With LOA: This field is optional.

- Without LOA: This field is mandatory.

loa Yes object    

Letter of Agreement (LOA) information that consists of the attachments information.

 

If there is no LOA to attach, this parameter is still mandatory, but the object should be left blank.

attachments No array[objects]    

LOA file attachment information that consists of attachment ID and attachment name. 

 

Each LOA attachment, not exceeding 10MB, 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.

 

Refer to Post Attachment File under the API Reference section for more information for more information. 

id Conditional string 0549c413-acc9-4c4b-9067-e7551890b46d  

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.

 

Refer to Post Attachment File under the API Reference section for more information for more information. 

name Conditional string LOA2017/36912.docx  

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

 

This is mandatory when an attachment is included.

 

Refer to Post Attachment File under the API Reference section for more information for more information. 

notifyZsideUponCompletion No boolean true

true,

false

Requirement to notify Z-side customer once cross connect is complete.

 

If 'true', Z-side will be notified.

 

If 'false', Z-side will not be notified. 

 

Default value: false

zSideContactEmail Conditional string johndoe@corp.com   Z-side customer email address that will receive notification of cross connect completion. 

This is only required if Z-side must be notified upon completion of the cross connection.

patchEquipment No boolean true

true,

false

Requirement to patch equipment. Smart Hands fees will apply for providing this extension.

 

If 'true', Equinix will install the cross connect from the demarcation panel to your equipment. 

 

If 'false', Equinix will not do any additional installation.

 

Default value: false

device Conditional object    

Device information that Equinix requires to install the cross connect from demarcation panel to customer equipment. 

 

This is only required if patching is required.

cabinet Conditional string V0102  

Cabinet number of customer equipment for cross connection. 

 

The cabinet for patching must belong to the specific cage defined in the A-side details. 

This is only required if patching is required.

connectorType Conditional string BNC

BNC, 

FC, 

LC, 

RJ45,

SC,

ST

Device connector type to facilitate cross connection.

 

This is only required if patching is required.

details Conditional string Call the technical contact before patching.  

Additional device details to facilitate cross connection, for customer to provide. 

This is only required if patching is required.

port Conditional string any available  

Device port number for customer to provide in free text. 

 

This is only required if patching is required.

lightLinkVerificationRequired No boolean true

true,

false

Requirement for a cross connect Light Link verification. Customer may request for a Light Link reading, and transmit and receive verifications to be carried out after the cross connect is completed . In order to verify correct transmit and receive alignment, please ensure customer's Z-Side connect partner has their end fully extended to their equipment and their port is enabled. This will incur a fixed fee based on your contract pricing.

 

If 'true', Light Link verification is required.

 

If 'false', Light Link verification is not required.

Default value: false

needSupportFromASubmarineCableStationEngineer
 
Conditional boolean true

true,

false

Requirement for submarine cable station engineer support.

 

This is mandatory for customers with Monet accounts.

 

If 'true', submarine cable station engineer support is required. 

 

If 'false', submarine cable station engineer support is not required. 

 

Default value: false

 

{
  "OrderReferenceId": "971sld52-84aa-4db1-2746-c51659",
  "OrderNumber": "1-189639404838",
  "SRNumber": "9-18907405795"
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
OrderReferenceId string 971sld52-84aa-4db1-2746-c51659

Equinix internal order reference identification number.

 

You may ignore this.

OrderNumber string 1-189639404838 The order number created after order is submitted. 
SRNumber string

9-18907405795

Equinix internal service request number.

 

You may ignore this.

 

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

 


body: 
How to order an intra-customer cross connect?

 

 


body: 
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. 

 


body: 
Step 2: Check cross connect permissions

 

To get cross connect types, the user must have 'Cross Connect & Intra-Facility Cables' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

Get Cross Connect Types

Retrieve the cross connect types that the user has permission to order.
 

Use this API to determine if the user can order the preferred cross connect type.

 

Refer to Get Crossconnect Types under the API Reference section for instructions on how to retrieve available cross connect types. You may skip this step if you already know the user has permission to order this cross connect type.

 


body: 
Step 3: Get Cross Connect Details

 

To get cross connect details, the user must have 'Cross Connect & Intra-Facility Cables' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

3a) Get Cross Connect Location information for the starting point of the cross connect (A-side) 

Retrieve the IBX location information for the preferred cross connect type.
 

Use this API to determine the exact IBX location code, cage ID, cage account number, and cabinet ID to start the cross connect from (A-side).

 

Refer to Get Crossconnect Locations under the API Reference section for instructions on how to get all the cross connect location information. You may skip this step if you already know the location information for your A-side.  

 

3b) Get Connection Services information for your A-side criteria

Retrieve all the connection services information. 
 

Use this API to determine which connection service, media type, connector type, and protocol type to use for your A-side criteria.

 

Refer to Get Crossconnect Connection Services under the API Reference section for instructions on how to retrieve available connection services. You may skip this step if you already know the connection services information for your A-side.

 

3c) Get Patch Panel information for your A-side criteria

Retrieve all the patch panel information for the preferred cross connect type. 
 

Use this API to identify the patch panel number, and the patch panel ports to use for the selected connection service. This will fulfill the A-side criteria patch panel information that consists of patchpanel name, port A, and port B.

 

Refer to Get Crossconnect Patchpanel under the API Reference section for instructions on how to get all the patch panel information. You may skip this step if you already know the patch panel information for your A-side.  

 

3d) Get your Z-side criteria details by repeating steps 3a to 3c 

Retrieve all the same details from steps 3a to 3c for the end point of the cross connect (Z-side).

 


body: 
Step 4: Order an Intra-Customer Cross Connect

Post Crossconnect Intracustomer

POST /crossconnect/intracustomer

 Method  POST
 URL or End Point  /v1/orders/crossconnect/intracustomer
 Headers  Authorization, Content-Type
 Query Parameters  action
 Body

 quantityRequested, customerReferenceNumber, purchaseOrder {purchaseOrderType, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, mobilePhoneCountryCode, mobilePhone,mobilePhonePrefToCall},{contactType, username}, {contactType, username}], schedule {requestedCompletionDate, scheduleType}, additionalDetails, attachments [{id,name}], serviceDetails {aside {ibxLocation {ibx, cages [{cage, cabinets[...], accountNumber}]}, connectionService, mediaType, proceedIfMediaCoverterIsRequired, protocolType, connectorType, patchpanel {name, portA, portB}}, zside {customer, customerAccount, ibxLocation {ibx, cages [{cage, cabinets[...], accountNumber}]}, connectionService, connectorType, patchpanel {name, portA, portB}, loa{attachments[{id,name}]}, notifyZsideUponCompletion, zSideContactEmail}, patchEquipment, device{cabinet, connectorType,details,port}, lightLinkVerificationRequired, needSupportFromASubmarineCableStationEngineer}

 

The Post crossconnect intracustomer API creates an intra-customer cross connect order. This allows the customer to connect to their own company on the same floor in the same IBX.

 

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 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 API. There is a request for an intra-customer cross connect without additional information or attachment , and with additional information and attachment . The response indicates the order was successful and returned the order number, order reference number, and service request number. 

 

Intracustomer cross connect order without additional information or attachment 

 

curl -X

POST "https://api.equinix.com/v1/orders/crossconnect/intracustomer?action=SUBMIT"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe1"
    },
    {
      "contactType": "TECHNICAL",
      "userName": "johndoe1",
      "workPhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe1"
    }
  ],
  "schedule": {
    "requestedCompletionDate": "2019-08-28T15:00:06.686Z",
    "scheduleType": "EXPEDITED"
  },
  "serviceDetails": {
    "aside": {
      "ibxLocation": {
        "ibx": "AM1",
        "cages": [
          {
            "cage": "AM1:0J:00PG11",
            "cabinets": [
              "AM1:0J:00PG11:0851"
            ],
            "accountNumber": "45786"
          }
        ]
      },
      "connectionService": "Multi-Mode Fiber",
      "mediaType": "62.5 MICRON MULTI-MODE FIBER",
      "protocolType": "FAST ETHERNET",
      "connectorType": "ST",
      "patchpanel": {
        "name": "PP:0501:10356887",
        "portA": "Next Available",
        "portB": "Next Available"
      }
    },
    "zside": {
      "customerAccount": "45786",
      "ibxLocation": {
        "ibx": "AM1",
        "cages": [
          {
            "cage": "AM1:0J:00PG36",
            "cabinets": [
              "AM1:0G:00PG36:0105"
            ],
            "accountNumber": "45786"
          }
        ]
      },
      "connectionService": "Multi-Mode Fiber",
      "connectorType": "ST",
      "patchpanel": {
        "name": "PP:0105:1034578",
        "portA": "Next Available",
        "portB": "Next Available"
      },
      "circuitId": "73/HCGS/123456/000/CC",
      "loa": {
        "attachments": []
      }
    }
  }
}'

 

Intracustomer cross connect order with additional information and attachments

 

Before creating an order with attachment, call the Post Attachment File under the API Reference section.

 

curl -X

POST "https://api.equinix.com/v1/orders/crossconnect/intracustomer?action=SUBMIT"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "quantityRequested": 1,
  "customerReferenceNumber": "ICCC138864",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe1"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@thiscorp.com",
      "workPhoneCountryCode": "+1",
      "workPhone": "800-322-9280",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "America/Chicago",
      "mobilePhoneCountryCode": "+1",
      "mobilePhone": "555-555-1234",
      "mobilePhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe1"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "JohnJacob369"
    }
  ],
  "schedule": {
    "requestedCompletionDate": "2019-08-28T15:00:06.686Z",
    "scheduleType": "EXPEDITED"
  },
  "additionalDetails": "Please look at attachment for detailed instructions.",
  "attachments": [
    {
      "id": "507f8877-4894-4ca6-ac9f-3995c59a4ce6",
      "name": "AdditionalDetailsAttachment.docx"
    }
  ],
  "serviceDetails": {
    "aside": {
      "ibxLocation": {
        "ibx": "AM1",
        "cages": [
          {
            "cage": "AM1:0J:00PG11",
            "cabinets": [
              "AM1:0J:00PG11:0851"
            ],
            "accountNumber": "45786"
          }
        ]
      },
      "connectionService": "Multi-Mode Fiber",
      "mediaType": "62.5 MICRON MULTI-MODE FIBER",
      "proceedIfMediaCoverterIsRequired": true,
      "protocolType": "FAST ETHERNET",
      "connectorType": "ST",
      "patchpanel": {
        "name": "PP:0501:10356887",
        "portA": "Next Available",
        "portB": "Next Available"
      }
    },
    "zside": {
      "customerAccount": "45786",
      "ibxLocation": {
        "ibx": "AM1",
        "cages": [
          {
            "cage": "AM1:0J:00PG36",
            "cabinets": [
              "AM1:0G:00PG36:0105"
            ],
            "accountNumber": "45786"
          }
        ]
      },
      "connectionService": "Multi-Mode Fiber",
      "connectorType": "ST",
      "patchpanel": {
        "name": "PP:0105:1034578",
        "portA": "Next Available",
        "portB": "Next Available"
      },
      "circuitId": "73/HCGS/123456/000/CC",
      "loa": {
        "attachments": [
          {
            "id": "6a42173d-f52c-4fac-bf30-3638c1f71a10",
            "name": "LOA2017/36912.docx"
          }
        ]
      },
      "notifyZsideUponCompletion": true,
      "zSideContactEmail": "johndoe@corp.com"
    },
    "patchEquipment": true,
    "device": {
      "cabinet": "0851",
      "connectorType": "ST",
      "details": "Refer to attachment.",
      "port": "any available"
    },
    "lightLinkVerificationRequired": true,
    "needSupportFromASubmarineCableStationEngineer": true
  }
}'

 

The description of the query and request payload is as follows:

 

Query Parameter Name Mandatory Type Example Applicable Values Description
action Yes string

SUBMIT

SUBMIT

The action to submit the order.

 

 

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

 

Body Parameter Name Mandatory Type Example Applicable Values Description
quantityRequested No integer 1 1

Number of cross connects ordered.

 

Default value:1

 

Currently, Equinix does not support multi-quantity, so “quantityRequested” will be considered as 1 by default.

customerReferenceNumber No string ICCC138864 null

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

 

This can be a Purchase Order number or 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. 

 

If you do not know your account's PO bearing status, refer to Get Crossconnect Locations under the API Reference section.

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 being 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, and a purchase order number is not required. 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 Conditional 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 Attachment 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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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. All three contacts are mandatory.

 

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

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

- Notification contact person: Person who will be notified of status updates. More than one Notification contact can be passed.

userName Yes string johndoe1  

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

 

E.g. If 'email' and 'workPhone' information is passed with 'userName' for Notification contact, this information will be ignored.

name Conditional string Jane Smith  

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

email Conditional string janesmith@thiscorp.com  

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

workPhoneCountryCode No string +1  

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

 

E.g.: +571

 

It is recommended to include the work phone country code. 

workPhone Conditional string 800-322-9280

 

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

workPhonePrefToCall Yes string MY_BUSINESS_HOURS

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

This is mandatory for the Technical contact.

workPhoneTimeZone No string America/Chicago 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.

 

E.g. Area/Location

 

This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.

mobilePhoneCountryCode No string +1

 

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

mobilePhone No string 555-555-1234  

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 anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'mobilePhoneTimeZone' is mandatory. 

mobilePhoneTimeZone Conditional 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.

 

E.g. Area/Location

 

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. 

schedule Yes object     Scheduling information for the installation of the cross connect order.  
requestedCompletionDate Conditional string 2019-08-28T15:00:06.686Z  

Requested completion date and time of scheduled cross connect installation. 

 

Expedited scheduling date should not be less than IBX local time + 2 hours, and no more than IBX local time + 24 hours.

 

If 'EXPEDITED' schedule type, 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.

 

In the case of 'STANDARD' schedule type, this parameter is not required.

scheduleType Yes string EXPEDITED

EXPEDITED,

STANDARD

Define your preferred scheduling type.

 

These are the scheduling types supported for this cross connect.

 

Schedule Types 
 

STANDARD: Request will be processed in the standard turnaround time. Most requests are completed within 24 to 72 hours pending your install base readiness. Requests will be processed in the order they were received, unless they are expedited.
- Parameter 'requestedCompletionDate' is not required. 

 

EXPEDITED: Request will be completed within the next 2 to 24 hours. Additional Smart Hands fees may apply. Schedule a time in the current local time of the IBX you selected. Equinix will contact customer for schedule negotiation if preferred scheduling cannot be met.
- Parameter 'requestedCompletionDate' is required. 

additionalDetails No string

Please look at attachment for detailed instructions.

 

Additional details the Equinix Technician may need to complete your request. This is free text input. 

 

This field can only be up to 4000 characters long.

attachments No array[objects]    

Additional attachment. Provide any other supportive photos or documents to help the technician to complete your order. 

 

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

 

Refer to Post Attachment File under the API Reference section for more information. 

id Conditional string 507f8877-4894-4ca6-ac9f-3995c59a4ce6  

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

name

Conditional

string AdditionalDetailsAttachment.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.

 

Refer to Post Attachment File under the API Reference section for more information. 

serviceDetails Yes object  

 

Service details information consisting of the A-side and Z-side locations and their corresponding cross connect details. 

aside Yes object     

A-side cross connect information that consists of IBX location information, connection service, media type, media converter requirement, protocol type, connector type, and patch panel information.

ibxLocation Yes object    

IBX location information that consists of the IBX location code, cages information, and cage account number.

 

Refer to Get Crossconnect Locations under the API Reference section for more information. 

ibx Yes string AM1  

The IBX location code.

cages Yes array[objects]    

Cages information consists of ID of cage, ID of cabinet, and cage account number.

 

Only 1 cage per order is currently being supported. Provide information for only 1 cage.

cage Yes string AM1:0J:00PG11  

ID of the cage.

cabinets Yes array[strings] AM1:0J:00PG11:0851  

ID of the cabinet.

 

If providing cabinet, provide only 1 cabinet ID. Only 1 cabinet is currently being supported per cage.

accountNumber Yes string 45786  

The account number linked to the cage.

connectionService Yes string Multi-Mode Fiber

Multi-Mode Fiber,

Single-Mode Fiber,

UTP,

COAX,

POTS

The name of the available connection service media type.

 

Refer to Get Crossconnect Connection Services under the API Reference section for more information. 

mediaType Yes string 62.5 MICRON MULTI-MODE FIBER

50 MICRON MULTI-MODE FIBER OM3,
62.5 MICRON MULTI-MODE FIBER,

Single-Mode Fiber

CAT5e,

CAT6

COAX

CAT3

Name of the sub-media type that corresponds with the connection service media type.

 

Connection service media type - Sub-media type

Multi-Mode Fiber - 50 Micron Multi-Mode Fiber OM3, 62.5 Micron Multi-Mode Fiber, Fiber Channel.

Single-Mode Fiber - Single-Mode Fiber.

UTP - Cat5e, Cat6.
COAX - COAX

POTS - CAT3

 

Refer to Get Crossconnect Connection Services under the API Reference section for more information. 

proceedIfMediaCoverterIsRequired No boolean true

true,

false

Requirement for media converter. 

 

If 'true', media converter is required. 

If 'false', media converter is not required.

 

Default value: false

 

Media converters are not applicable to single mode fiber connections.

 

Cross Connect installations that require a media converter due to distance will be held unless 'true' is selected. 

protocolType Yes string FAST ETHERNET

100 GIG ETHERNET,

10 GIG ETHERNET,

40 GIG ETHERNET,

FIBRE CHANNEL,

GIGABIT ETHERNET,

FAST ETHERNET,

DARK FIBER,

DWDM,

OC-12,

OC-192,

OC-3,

OC-48,

STM-1,

STM-16,

STM-4,

STM-64,

56K,

E1,

ETHERNET,

ISDN,

T1,

ANTENNA,

DS-3,

E3,

POTS

Name of the protocol type that corresponds with the name of the sub-media type.

 

Sub-media type - Name of protocol type

50 Micron Multi-Mode Fiber OM3 - 100 Gig Ethernet, 10 Gig Ethernet, 40 Gig Ethernet, Fibre Channel, Gigabit Ethernet.

62.5 Micron Multi-Mode Fiber - Fast Ethernet, Fibre Channel, Gigabit Ethernet.

Single-Mode Fiber - 100 Gig Ethernet, 10 Gig Ethernet, 40 Gig Ethernet, Dark Fibre, DWDM, Fibre Channel, Gigabit Ethernet, OC-12, OC-192, OC-3, OC-48, STM-1, STM-16, STM-4, STM-64.

Cat5e - 56K, E1, Ethernet, Fast Ethernet, Gigabit Ethernet, ISDN, T1.

Cat 6 - 56K, E1, Ethernet, Fast Ethernet, Gigabit Ethernet, ISDN, T1.

COAX - Antenna, DS-3, E3

CAT3 - POTS

 

Refer to Get Crossconnect Connection Services under the API Reference section for more information. 

connectorType Yes string ST

BNC, 

FC, 

LC, 

RJ45,

SC,

ST

Name of the connector type that corresponds with the name of the connection service media type.

 

Connection service media type - Name of connector type

Multi-Mode Fiber - LC, SC, ST.

Single-Mode Fiber - FC, LC, SC, ST.

UTP - RJ45.
COAX - BNC, LC.

POTS - RJ45, LC.

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

patchpanel Yes object    

Patch panel information that consists of patch panel serial number and port details.

 

Patch panel and port availability information details can be obtained from using the GET Crossconnect Patchpanel API. 

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

name Yes string PP:0501:10356887  

Patch panel number. 

 

Patch panel and port availability information details can be obtained from using the GET Crossconnect Patchpanel API. 

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

portA Yes string Next Available

Next Available,

any available port number

Available port A of patch panel.

 

Patch panel and port availability information details can be obtained from using the GET Crossconnect Patchpanel API. 

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

portB Conditional string Next Available

Next Available,

any available port number

Available port B of patch panel. This is mandatory depending on the connector type.

 

Connector type - Whether port B is mandatory

BNC - mandatory

FC - mandatory

LC - optional

RJ45 - not necessary

SC - mandatory

ST - mandatory

 

Patch panel and port availability information details can be obtained from using the GET Crossconnect Patchpanel API. 

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

zside Yes object    

Z-side cross connect information that consists of customer account name, customer account number, IBX location information, connection service, media type, media converter requirement, protocol type, connector type, and patch panel information.

 

The following information indicates the mandatory fields with and without attaching a Letter of Agreement (LOA). 

-With LOA: The following Z-side parameters are mandatory: customerAccount, ibxLocation, ibx, cages, cage, accountNumber; connection service, patch panel, name, portA, portB, loa, attachments, id, name. The LOA should address all information that is otherwise mandatory. Equinix will contact customer for further verification before the order can be fulfilled.

 

-Without LOA: The following Z-side parameters are mandatory: customerAccount, ibxLocation, ibx, cages, cage, accountNumber, connectionService, connectorType, patch panel, name, portA, portB, loa.

customerAccount Yes string 45786   The account number of the customer linked to this cage.

For Intracustomer Cross Connect, this value is normally the same as the A-side account number. In some instances, the values may differ, but this is acceptable so long as both account numbers mentioned belong to your organization.

ibxLocation Yes object     

IBX location information that consists of the IBX location code, cages information, and cage account number.

 

Refer to Get Crossconnect Locations under the API Reference section for more information. 

ibx Yes string AM1   The IBX location code.
cages Yes array[objects]    

Cages information consists of ID of cage, ID of cabinet, and cage account number.

 

Only 1 cage per order is currently being supported. Provide information for only 1 cage.

cage Yes string AM1:0G:00PG36   ID of the cage.
cabinets Conditional array[strings] AM1:0G:00PG36:0105  

ID of the cabinet.

 

If attaching an LOA, this field is optional.

If not attaching an LOA, his field is mandatory.

 

If providing cabinet, provide only 1 cabinet ID. Only 1 cabinet is currently being supported per cage.

accountNumber Yes string 45786  

The account number of the customer linked to this cage.

 

This is the same value as the value for the 'customerAccount' parameter.

connectionService Yes string Multi-Mode Fiber

Multi-Mode Fiber,

Single-Mode Fiber,

UTP,

COAX,

POTS

The name of the available connection service.

 

Refer to Get Crossconnect Connection Services under the API Reference section for more information. 

connectorType Conditional string ST

BNC, 

FC, 

LC, 

RJ45,

SC,

ST

Name of the connector type that corresponds with the connection service.

 

Connection service - Connector type

Multi-Mode Fiber - LC, SC, ST.

Single-Mode Fiber - FC, LC, SC, ST.

UTP - RJ45.
COAX - BNC, LC.

POTS - RJ45, LC.

 

If attaching an LOA, this field is optional.

If not attaching an LOA, this field is mandatory.

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

patchpanel Yes object    

Patch panel information that consists of patch panel serial number and port details.

 

Patch panel and port availability information details can be obtained from using the GET Crossconnect Patchpanel API. 

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

name Yes string PP:0105:1034578  

Patch panel serial number. 

 

Patch panel and port availability information details can be obtained from using the GET Crossconnect Patchpanel API. 

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

portA Yes string Next Available

Next Available,

any available port number

Available port A of patch panel.

 

Patch panel and port availability information details can be obtained from using the GET Crossconnect Patchpanel API. 

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

portB Conditional string Next Available

Next Available,

any available port number

Available port B of patch panel. This is mandatory depending on the connector type.

 

Connector type - Whether port B is mandatory

BNC - mandatory

FC - mandatory

LC - optional

RJ45 - not necessary

SC - mandatory

ST - mandatory

 

Patch panel and port availability information details can be obtained from using the GET Crossconnect Patchpanel API. 

 

If attaching an LOA, this field is optional.

If not attaching an LOA, this field is mandatory if the connector type requires a port B input.

 

Refer to GET Crossconnect Patchpanel under the API Reference section for more information. 

circuitId Conditional string 73/HCGS/123456/000/CC  

Customer or carrier circuit ID cable reference number for verification purposes. 

 

If attaching an LOA, this field is optional.



If not attaching an LOA, this field is mandatory.

loa Yes object    

Letter of Agreement (LOA) information that consists of the attachments information.

 

If not attaching an LOA, this parameter is still mandatory, but the object should be left blank.

attachments No array[objects]    

LOA file attachment information that consists of attachment ID and attachment name. 

 

Each LOA attachment, not exceeding 10MB, 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.

 

Refer to Post Attachment File under the API Reference section for more information. 

id Conditional string 6a42173d-f52c-4fac-bf30-3638c1f71a10  

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

name Conditional string LOA2017/36912.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.

 

Refer to Post Attachment File under the API Reference section for more information. 

notifyZsideUponCompletion No boolean true

true,

false

Requirement to notify Z-side customer once cross connect is complete.

 

If 'true', Z-side will be notified.

 

If 'false', Z-side will not be notified. 

 

Default value: false

zSideContactEmail Conditional string johndoe@corp.com  

Z-side customer email address that will receive notification of cross connect completion. 

 

This is only required if Z-side must be notified upon completion of the cross connection.

patchEquipment No boolean true

true,

false

Requirement to patch equipment. Smart Hands fees will apply for providing this extension.

 

If 'true', Equinix will install the cross connect from the demarcation panel to your equipment. 

 

If 'false', Equinix will not do any additional installation.

 

Default value: false

device Conditional object    

Device information that Equinix requires to install the cross connect from demarcation panel to customer equipment. 

 

This is only required if patching is required.

cabinet Conditional string 0851  

Cabinet number of customer equipment for cross connection. 

 

The cabinet for patching must belong to the specific cage defined in the A-side details. 

This is only required if patching is required.

connectorType Conditional string ST

BNC, 

FC, 

LC, 

RJ45,

SC,

ST

Device connector type to facilitate cross connection.

 

This is only required if patching is required.

details Conditional string Refer to attachment.  

Additional device details to facilitate cross connection, for customer to provide. 

This is only required if patching is required.

port Conditional string any available any available port number

Device port number for customer to provide.

 

This is only required if patching is required.

lightLinkVerificationRequired No boolean true

true,

false

Requirement for a cross connect Light Link verification. Customer may request for a Light Link reading, and transmit and receive verifications to be carried out after the cross connect is completed . In order to verify correct transmit and receive alignment, please ensure customer's Z-Side connect partner has their end fully extended to their equipment and their port is enabled. This will incur a fixed fee based on your contract pricing.

 

If 'true', Light Link verification is required.

 

If 'false', Light Link verification is not required.

Default value: false

needSupportFromASubmarineCableStationEngineer Conditional boolean true

true,

false

Requirement for submarine cable station engineer support.

 

This is mandatory for customers with Monet accounts.

 

If 'true', submarine cable station engineer support is required. 

 

If 'false', submarine cable station engineer support is not required. 

 

Default value: false

 

{
  "OrderReferenceId": "a944jfds-07532-47d9-8kdy-5e96e3",
  "OrderNumber": "1-194578941895",
  "SRNumber": "9-19875413946"
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
OrderReferenceId string a944jfds-07532-47d9-8kdy-5e96e3

Equinix internal order reference identification number.

 

You may ignore this.

OrderNumber string 1-194578941895 The order number created after order is submitted. 
SRNumber string

9-19875413946

Equinix internal service request number.

 

You may ignore this.

 

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

 


body: 

How to schedule on-site services


body: 
How to schedule a Work Visit?

 

 


body: 
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. 

 


body: 
Step 2: Get Work Visit Details

 

To get work visit details, the user must have 'IBX Access Services' 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.

 


body: 
Step 3: Schedule Work Visit

Post Work Visit

POST /orders/workvisit

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

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

 

The Post workvisit API creates a work visit request to grant IBX visitors access for up to two weeks. This can only be done under a user with 'IBX Access Services' 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.

 

In light of the current COVID-19 situation, a Work Visit Request Form is mandatory to include when placing a work visit order for IBXs with restricted access.

 

Forms should be duly completed to avoid the order being rejected. Download Work Visit Request Form and refer to the work visit scenario with attachment for more information on how to include this form in the request.

 

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 the access restriction on your IBX, refer to Get Workvisit Locations in the API Reference section for more information. 

 

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

 

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 for customer verification, together with 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 Attachment 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 '{
   "customerReferenceNumber": "WV082019-101",
  "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"
      }
    ]
  },
  "attachments": [
    {
      "id": "68a81166-decf-4d7b-8e23-b192b0ac6d85",
      "name": "AdditionalWorkVisitDetails.docx"
    }
  ],
  "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
  },
  "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
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. 

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 of the cabinet.

 

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

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.

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.

 

Refer to Post Attachment File in the API Reference section for more information. 

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.

 

Refer to Post Attachment File in the API Reference section for more information. 

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. E.g. 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. E.g. 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. 

 

E.g. +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 Smart Hands request for Equinix staff to open the cabinet during the work visit.

 

If 'true', Equinix staff will open the cabinet, and Smart Hands fees will apply.

 

If 'false', the cabinet will remain closed during the work visit. 

 

Default value: false

 

Additional Smart Hands labor item is added to your Work Visit order after the Open Cabinet Assistance service has been completed. There is no need to create a separate Smart Hands order.

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 trouble ticket. 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. who is active and approved, or locked.

 

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

 

For Notification and Technical contacts, Equinix-registered username of contact person can be active and approved, 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. 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.

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.

 

E.g.: +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 the additional Technical contact person to take calls anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

This is mandatory for the Technical contact.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'workPhoneTimeZone' is mandatory.

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.

 

E.g. Europe/London

 

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 anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'mobilePhoneTimeZone' is mandatory. Refer to 'workPhoneTimeZone' body parameter for the same applicable values. 

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.

 

E.g. Europe/London

 

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
           }
         ]
      },
      "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.
cabinetId string AT2:02:V050005-6-591:V0106 The ID of the cabinet 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.
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.

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  

Category type of notes.

 

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 for Smart Hands Cage Escort.

 

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

 

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

 


body: 

How to schedule shipments


body: 
How to schedule an inbound shipment?

 

 


body: 
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. 

 


body: 
Step 2: Get Shipment Details

 

To get shipment details, the user must have 'Shipments' 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 location information such as the ibx location code, cage ID, and cage account number.

 

Refer to Get Shipment 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.

 


body: 
Step 3: Schedule Inbound Shipment

Post Shipment Inbound

POST /shipment/inbound

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

 ibxLocation {ibx, cages [{cage, accountNumber}]}, customerReferenceNumber, purchaseOrder {purchaseOrderType, attachment {id, name}}, serviceDetails {estimatedDateTime, shipmentDetails {trackingNumber [...], inboundType, noOfBoxes, isOverSized, carrierName}, deliverToCage, inboundRequestDescription, attachments [{id, name}], contacts [{contactType, userName},{contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}, {contactType, userName}, {contactType,userName}]

 

The Post shipment inbound API creates an inbound shipment order for inbound shipment of equipment to any IBX that the user has access to. This can only be done under a user with 'Shipments' 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 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 API.

 

The requests indicates four scenarios: 

 

(A) An inbound shipment by the customer without additional information,  attachment, or contacts, but with added Smart Hands fee (delivery after business hours)

 

(B) An inbound shipment by the customer with added additional information,  attachment, contacts, and Smart Hands fee (delivery after business hours)

 

(C) An inbound shipment by a carrier without additional information, attachment, contacts, or Smart Hands request, but with added Smart Hands fee (delivery after business hours)

 

(D) An inbound shipment by a carrier with additional information, attachment, contacts, Smart Hands request, and added Smart Hands fee (delivery after business hours)

 

The response indicates that the order was successful and returned the order number.

 

(A) An inbound shipment by the customer without additional information,  attachment, or contacts, but with added Smart Hands fee (delivery after business hours)

 

curl -X

POST "https://api.equinix.com/v1/orders/shipment/inbound"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "DC3",
    "cages": [
      {
        "cage": "DC3:01:005000",
        "accountNumber": "2983"
      }
    ]
  },
  "serviceDetails": {
    "estimatedDateTime": "2019-08-23T00:00:30.610Z",
    "shipmentDetails": {
      "inboundType": "CUSTOMER_CARRY",
      "noOfBoxes": 2
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

 

(B) An inbound shipment by the customer with added additional information,  attachment, contacts, and Smart Hands fee (delivery after business hours)

 

Before creating an order with attachment, call the Post Attachment File to attach a file.

 

curl -X

POST "https://api.equinix.com/v1/orders/shipment/inbound"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "DC3",
    "cages": [
      {
        "cage": "DC3:01:005000",
        "accountNumber": "2983"
      }
    ]
  },
  "customerReferenceNumber": "ISO082019-101",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "serviceDetails": {
    "estimatedDateTime": "2019-08-23T00:00:30.610Z",
    "shipmentDetails": {
      "inboundType": "CUSTOMER_CARRY",
      "noOfBoxes": 2,
      "isOverSized": true,
      "trackingNumber": [
        "t1Z294AK92654678989",
        "t1Z086DK96424456780"
      ]
    },
    "inboundRequestDescription": "Place all boxes upright with labels facing upwards."
  },
  "attachments": [
    {
      "id": "26f40e6e-dd6e-48fa-a797-62c0d3157388",
      "name": "AdditionalShipmentWorkDetails.docx"
    }
  ],
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@corporation.com",
      "workPhoneCountryCode": "+1",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Pacific/Honolulu",
      "mobilePhoneCountryCode": "+1",
      "mobilePhone": "0123456789"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "jillsnow"
    }
  ]
}'

 

(C) An inbound shipment by a carrier without additional information, attachment, contacts, or Smart Hands request, but with added Smart Hands fee (delivery after business hours)

 

curl -X

POST "https://api.equinix.com/v1/orders/shipment/inbound"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "DC3",
    "cages": [
      {
        "cage": "DC3:01:005000",
        "accountNumber": "2983"
      }
    ]
  },
  "serviceDetails": {
    "estimatedDateTime": "2019-08-23T00:00:30.610Z",
    "shipmentDetails": {
      "inboundType": "CARRIER",
      "carrierName": "OTHER",   
      "otherCarrierName": "YAMATO", 
      "noOfBoxes": 2,    
      "isOverSized": true,
      "trackingNumber": [
        "t1Z294AK92654678989",
        "t1Z086DK96424456780"
      ]
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

 

(D) An inbound shipment by a carrier with additional information, attachment, contacts, Smart Hands request, and added Smart Hands fee (delivery after business hours)

 

Before creating an order with attachment, call the Post Attachment File to attach a file.

 

curl -X

POST "https://api.equinix.com/v1/orders/shipment/inbound"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "DC3",
    "cages": [
      {
        "cage": "DC3:01:005000",
        "accountNumber": "2983"
      }
    ]
  },
  "customerReferenceNumber": "ISO082019-101",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "serviceDetails": {
    "estimatedDateTime": "2019-08-23T00:00:30.610Z",
    "shipmentDetails": {
      "inboundType": "CARRIER",
      "carrierName": "OTHER",   
      "otherCarrierName": "YAMATO", 
      "noOfBoxes": 2,    
      "isOverSized": true,
      "trackingNumber": [
        "t1Z294AK92654678989",
        "t1Z086DK96424456780"
      ]
    },
    "deliverToCage": true,
    "inboundRequestDescription": "Place all boxes upright with labels facing upwards."
  },
  "attachments": [
    {
      "id": "26f40e6e-dd6e-48fa-a797-62c0d3157388",
      "name": "AdditionalShipmentWorkDetails.docx"
    }
  ],
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@corporation.com",
      "workPhoneCountryCode": "+1",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Pacific/Honolulu",
      "mobilePhoneCountryCode": "+1",
      "mobilePhone": "0123456789"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "jillsnow"
    }
  ]
}'

 

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 DC3   The IBX location code. 
cages Yes array[objects]    

Cages information consists of ID of cage, ID of cabinet, and cage account number.

 

Only 1 cage per order is currently being supported. Provide information for only 1 cage.

cage Yes string DC3:01:005000  

ID of the cage.

accountNumber Yes string 2983  

The customer account number that is linked to the cage.

customerReferenceNumber No string ISO082019-101  

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

 

This can be a Purchase Order number or 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 No object    

Purchase order (PO) information details. 

 

This is mandatory for PO bearing accounts. 

 

If you do not know your account's PO bearing status, refer to Get Shipment Locations under the API Reference section.

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 being 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, and a purchase order number is not required. 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.

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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. 

 

Refer to Post Attachment File under the API Reference section for more information. 

serviceDetails Yes object  

 

Service details consist of the estimated date and time of inbound shipment, and shipment details information. Additional information such as additional Smart Hands request for Equinix to deliver the packages to the cage, and additional details are also included. 

estimatedDateTime Yes string 2019-08-23T00:00:30.610Z

 

Estimated shipment time. Dock hours are from 07:00 to 17:00.

 

Additional fees may be applied for deliveries during non-business hours (after hours or weekend deliveries) and require prior approval and will be billed to your account as an Equinix Smart Hands fee.

 

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.

shipmentDetails Yes object  

 

Shipment details information consists of tracking numbers, type of inbound shipment, total number of boxes in the shipment, size of box, and name of the carrier.

inboundType

Yes

string

CARRIER,

 

CUSTOMER_CARRY

CARRIER, 

CUSTOMER_CARRY

Type of inbound shipment.

 

If 'CARRIER', a carrier service is delivering the shipment. The additional parameters 'trackingNumber' and 'carrierName' must be provided.

 

If 'CUSTOMER_CARRY', a member from the customer's company will be delivering this shipment to the IBX.

carrierName Conditional string OTHER

FEDEX,
DHL,
UPS,
OTHER

The name of the carrier service.

This is mandatory when the type of inbound shipment is 'CARRIER'.

otherCarrierName No string YAMATO  

The name of the unlisted carrier service. This is free text input. 

 

This field can only be up to 50 characters long.

 

It is recommended to include this. If this is excluded, the order will be created, but there will be a delay in fulfillment. 

noOfBoxes Yes integer 2   Total number of boxes that the IBX should expect to receive in the shipment.

Maximum number of boxes allowed is 10000000000000000000. 

isOverSized No boolean true

true, 

false

Indicates if the shipment is oversized. 

 

As shipment size allowance varies by IBX, contact the receiving IBX for their acceptable shipment sizes.

 

If 'true', shipment is oversized.

 

If 'false', shipment is normal-sized. 

 

Default value: true

trackingNumber Conditional array[strings] t1Z294AK92654678989,
t1Z086DK96424456780
 

Tracking number(s). This is free text input.

 

At least one tracking number must be included when a carrier service is delivering the shipment.

Multiple tracking numbers should be comma-separated.

 

The maximum number of characters allowed per tracking number is 100, and the maximum number of tracking numbers that can be included is 10.

 

This is mandatory when the type of inbound shipment is 'CARRIER'.

deliverToCage No boolean true

true, 

false

A Smart Hands request for Equinix to deliver the shipment to the customer cage or suite.

 

If 'true', shipment will be delivered to customer cage by Equinix. Smart Hands fees will apply.

 

Additional Smart Hands fees may be applied to your account at your contracted rate after the package delivery has been completed. There is no need to create a separate Smart Hands order.

 

If 'false', the customer will pick up the shipment from the IBX shipping dock. Shipments must be picked up within 5 days of delivery. After 5 days, if all attempts to contact the customer results in no response, further action will be taken. Refer to Global IBX Policies for additional details.

 

Default value: false

inboundRequestDescription No string Place all boxes upright with labels facing upwards.  

Additional shipment work details from the customer. This is free text input.

 

This field can only be up to 4000 characters long. 

attachments No array[objects]    

An array containing the attachment details.

 

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.

 

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

id Conditional string

fcb2k8763-2947-456e-

8d68-f280753d60ba

 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

name Conditional string AdditionalShipmentWorkDetails.docx  

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

 

This is mandatory when an attachment is included.

 

Refer to Post Attachment File under the API Reference section for more information. 

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 trouble ticket. 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 johndoe
      
 

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

name Conditional string Jane Smith    

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

email Conditional string janesmith@corporation.com  

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

 

This is mandatory when the Technical contact does not have an active or locked Equinix-registered username.

workPhoneCountryCode No string +1
      
 

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

 

E.g.: +571

 

This is mandatory for the Technical contact.

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 an active or locked Equinix-registered username.

workPhonePrefToCall Yes string MY_BUSINESS_HOURS

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

Availability of Technical contact person to take calls anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

This is mandatory for the Technical contact.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'workPhoneTimeZone' is mandatory.

workPhoneTimeZone Conditional string Pacific/Honolulu Click here for applicable values

This indicates the specific timezone of the Technical contact's business hours that follows a 'Region/City' 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, +1

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 anytime, during office hours, during their business hours, during the local IBX business hours, during general business hours, or never.

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'mobilePhoneTimeZone' is mandatory. Refer to 'workPhoneTimeZone' body parameter for the same applicable values. 

mobilePhoneTimeZone Conditional string   Click here for applicable values

This indicates the specific timezone of the Technical contact's business hours that follows a 'Region/City' format.

 

This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'mobilePhonePrefToCall'.

 

{
  "OrderNumber": "1-190400381600"
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
OrderNumber string 1-190400381600

The order number created after order is submitted. 

 

You will need to submit this number when requesting for Smart Hands Shipment Unpack.

 

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

 


body: 
How to schedule an outbound shipment?

 

 


body: 
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. 

 


body: 
Step 2: Get Shipment Details

 

To get shipment details, the user must have 'Shipments' 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 location information such as the ibx location code, cage ID, and cage account number.

 

Refer to Get Shipment 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.

 


body: 
Step 3: Schedule Outbound Shipment

Post Shipment Outbound

POST /shipment/outbound

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

 ibxLocation {ibx, cages [{cage, accountNumber}]}, customerReferenceNumber, purchaseOrder {purchaseOrderType, attachment {id, name}}, serviceDetails {estimatedDateTime, shipmentDetails {outboundType, noOfBoxes, declaredValue, carrierName, otherCarrierName, trackingNumber, description, insureShipment, pickUpFromCageSuite, labelExists, uploadedLabel {id, name}, shipToAddress {carrierAccountNumber, name, address, state, city, country, zipCode, phoneNumber}, outboundRequestDescription, attachments [{id, name}], contacts [{contactType, userName},{contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}, {contactType, userName}]

 

The Post shipment outbound API creates an outbound shipment order. This can only be done under a user with 'Shipments' 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 you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The requests indicates four scenarios: 

 

(A) An outbound shipment by the customer without additional information,  attachment, or contacts, but with added Smart Hands fee (delivery after business hours)

 

(B) An outbound shipment by the customer with added additional information,  attachment, contacts, and Smart Hands fee (delivery after business hours)

 

(C) An outbound shipment by a carrier without a shipment label, additional information, attachment, contacts, or Smart Hands request, but with added Smart Hands fee (delivery after business hours)

 

(D) An outbound shipment by a carrier with a shipment label, additional information, attachment, contacts, Smart Hands request, and added Smart Hands fee (delivery after business hours)

 

The response indicates that the order was successful and returns order information that includes the order number.

 

(A) An outbound shipment by the customer without additional information,  attachment, or contacts, but with added Smart Hands fee (shipment after business hours)

 

curl -X

POST "https://api.equinix.com/v1/orders/shipment/outbound"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

    "ibxLocation": {

    "ibx": "DC3",
    "cages": [
      {
        "cage": "DC3:01:005000",
        "accountNumber": "2983"
      }
    ]
  },
  "serviceDetails": {
    "estimatedDateTime": "2019-08-23T00:00:30.610Z",
    "shipmentDetails": {
      "outboundType": "CUSTOMER_CARRY"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "JaneSmith123"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "JaneSmith123"
    }

  ]
}'

 

(B) An outbound shipment by the customer with added additional information, attachment, contacts, and Smart Hands fee (shipment after business hours)

 

Before creating an order with attachment, call the Post Attachment File to attach a file.

 

curl -X

POST "https://api.equinix.com/v1/orders/shipment/outbound"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "DC3",
    "cages": [
      {
        "cage": "DC3:01:005000",
        "accountNumber": "2983"
      }
    ]
  },
  "customerReferenceNumber": "ISO082019-101",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "serviceDetails": {
    "estimatedDateTime": "2019-08-23T00:00:30.610Z",
    "shipmentDetails": {
      "outboundType": "CUSTOMER_CARRY"
    },
    "outboundRequestDescription": "See attachment for further details."
  },
  "attachments": [
    {
      "id": "f49891fc-d9a5-4b4b-bc65-150b1c5e6dff",
      "name": "AdditionalShipmentWorkDetails.docx "
    }
  ],
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "JaneSmith123"
    },
    {
      "contactType": "TECHNICAL",
      "name": "John Doe",
      "email": "johndoe@corporation.com",
      "workPhoneCountryCode": "+1",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Pacific/Honolulu",
      "mobilePhoneCountryCode": "+1",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "JaneSmith123"
    }
  ]
}'

 

(C) An outbound shipment by a carrier without a shipment label, additional information, attachment, contacts, or Smart Hands request, but with added Smart Hands fee (delivery after business hours)

 

curl -X

POST "https://api.equinix.com/v1/orders/shipment/outbound"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "DC3",
    "cages": [
      {
        "cage": "DC3:01:005000",
        "accountNumber": "2983"
      }
    ]
  },
  "serviceDetails": {
    "estimatedDateTime": "2019-08-23T00:00:30.610Z",
    "shipmentDetails": {
      "outboundType": "CARRIER",
      "noOfBoxes": 1,
      "declaredValue": "JPY1000000",
      "carrierName": "OTHER",
      "otherCarrierName": "YAMATO TRANSPORT",
      "trackingNumber": "1200-1111-1111",
      "description": "Fragile. Handle with care. Always place upright.",
      "insureShipment": true,
      "pickUpFromCageSuite": true,
      "labelExists": false,
      "shipToAddress": {
        "carrierAccountNumber": "90123-4567-890",
        "name": "John Doe Corp. Attn: Jane Smith, IT Dept.",
        "address": "1-2-3 Ginza",
        "state": "Tokyo",
        "city": "Chuo-ku",
        "country": "Japan",
        "zipCode": "123-9876",
        "phoneNumber": "+81-3-1234567890"
      }
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "JaneSmith123"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "JaneSmith123"
    }
  ]
}'

 

(D) Outbound shipment by a carrier with a shipment label and with additional Smart Hands requests, attachments, information, contacts

 

Before creating an order with attachment, call the Post Attachment File to attach a file.

 

curl -X

GET "https://api.equinix.com/v1/orders/shipment/outbound"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "DC3",
    "cages": [
      {
        "cage": "DC3:01:005000",
        "accountNumber": "2983"
      }
    ]
  },
  "customerReferenceNumber": "ISO082019-101",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "serviceDetails": {
    "estimatedDateTime": "2019-08-23T00:00:30.610Z",
    "shipmentDetails": {
      "outboundType": "CARRIER",
      "noOfBoxes": 1,
      "declaredValue": "JPY1000000",
      "carrierName": "OTHER",
      "otherCarrierName": "YAMATO TRANSPORT",
      "trackingNumber": "1200-1111-1111",
      "description": "Fragile. Handle with care. Always place upright.",
      "insureShipment": true,
      "pickUpFromCageSuite": true,
      "labelExists": false,
      "uploadedLabel": {
        "id": "86abc267-0c58-4173-94e9-49069977d9b5",
        "name": "ShipmentLabel.docx"
      }
    },
    "outboundRequestDescription": "See attachment for further details."
  },
  "attachments": [
    {
      "id": "f49891fc-d9a5-4b4b-bc65-150b1c5e6dff",
      "name": "AdditionalShipmentWorkDetails.docx "
    }
  ],
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "JaneSmith123"
    },
    {
      "contactType": "TECHNICAL",
      "name": "John Doe",
      "email": "johndoe@corporation.com",
      "workPhoneCountryCode": "+1",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Pacific/Honolulu",
      "mobilePhoneCountryCode": "+1",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "JaneSmith123"
    }
  ]
}'

 

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 the cages information and IBX. 

ibx Yes string DC3   The IBX location code. 
cages Yes array[objects]    

Cages information consists of ID of cage, ID of cabinet, and cage account number.

 

Only 1 cage per order is currently being supported. Provide information for only 1 cage.

cage Yes string DC3:01:005000  

ID of the cage.

accountNumber Yes string 2983  

The customer account number that is linked to the cage.

customerReferenceNumber No string ISO082019-101  

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

 

This can be a Purchase Order number or 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 No object    

Purchase order (PO) information details. 

 

This is mandatory for PO bearing accounts. 

 

If you do not know your account's PO bearing status, refer to Get Shipment Locations under the API Reference section.

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 being 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, and a purchase order number is not required. 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.

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

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.

 

Refer to Post Attachment File under the API Reference section for more information. 

serviceDetails Yes object  

 

Service details consist of the estimated date and time of inbound shipment, and shipment details information. Additional information such as additional Smart Hands request for Equinix to deliver the packages to the cage, and additional details are also included. 

estimatedDateTime Yes string 2019-08-23T00:00:30.610Z

 

Estimated shipment time. Dock hours are from 07:00 to 17:00. 

The selected departure date and time should be more than 24 hours from now.

 

Additional fees may be applied for deliveries during non-business hours (after hours or weekend deliveries) and require prior approval and will be billed to your account as an Equinix Smart Hands fee.

 

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.

shipmentDetails Yes object      Shipment details information consist of the type of outbound shipment, the number of boxes, the declared shipment value, carrier name, carrier tracking number, shipment description, Smart Hands request to insure shipment, Smart Hands request to pick up cage from suite, shipping address information, shipping label attachment, and any additional shipping request description.
outboundType Yes string CUSTOMER_CARRY

CARRIER, 

CUSTOMER_CARRY

Type of outbound shipment.

 

If 'CUSTOMER_CARRY',  a member of your company will be picking up your outbound shipment and