Skip to main content
Index

Create Smart Hands Order

Smart Hands is an around-the-clock, on-site, operational support service for remote management, installation and troubleshooting of your data center equipment. Only an Equinix Customer Portal user with Smart Hands ordering permission may order Smart Hands. The types of Smart Hands currently supported by Equinix Customer Portal APIs may be found here.

Order cage escort

Step 1: Authenticate

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

 

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

 

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

Step 2: 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.

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.

Step 4: Order a 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. 

Order equipment installation

Step 1: Authenticate

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

 

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

 

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

Step 2: Get Smart Hands Details

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.

Step 3: Order Equipment Installation

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. 

Order cage clean-up

Step 1: Authenticate

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

 

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

 

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

Step 2: Get 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.

Step 3: Order a Cage Clean-Up

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. 

Order inbound shipment unpacking and packaging disposal

Step 1: Authenticate

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

 

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

 

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

Step 2: 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.

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.

Step 4: Order inbound shipment unpacking and packaging disposal

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. 

Order more cables

Step 1: Authenticate

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

 

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

 

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

Step 2: Get 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.

Step 3: Order Cables

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. 

Order packages location

Step 1: Authenticate

 

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

 

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

 

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

Step 2: 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.

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.

Step 4: Order packages location

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. 

Order patch cable installation

Step 1: Authenticate

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

 

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

 

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

Step 2: Get 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.

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.

Step 4: Order Patch Cable Installation

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. 

Order patch cable removal

Step 1: Authenticate

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

 

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

 

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

Step 2: Get 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.

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.

Step 4: Order 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. 

Order photos or documentation of your cage

Step 1: Authenticate

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

 

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

 

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

Step 2: Get 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.

Order to move patch cables

Step 1: Authenticate

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

 

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

 

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

Step 2: Get 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.

Step 3: Order Move Patch Cables

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. 

Order to run jumper cables

Step 1: Authenticate

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

 

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

 

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

Step 2: Get 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.

Step 3: Order Run Jumper Cables

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.

 

 
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. 

Order unlisted smart hands

Step 1: Authenticate

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

 

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

 

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

Step 2: Get 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.

Step 3: Order Smart Hands: Others

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.