Create Smart Hands Order

Equinix SmartHands® 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.

See Smart Hands for more information.

Order cage escort

Step 1: Authenticate

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

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

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

Step 2: 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 Getting Started for ECP use cases section for instructions on how to schedule a work visit, or refer to How to retrieve order history? under the Getting Started 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, number, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}]

This method 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 ordering 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 Getting Started 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 Getting Started 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 Access Token section.

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

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

Copy

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 Attachments File under the API Reference section.

Copy

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. For example, 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 Getting Started 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 Getting Started 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. Refer to POST Attachments File under the API Reference section for more information.
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.
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.
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. Refer to POST Attachments File under the API Reference section for more information.
id	Conditional	string	abc1fd2e-345f-67g4-hi89-01jk234l5m6n		ID of the attachment. You will obtain this value after attaching your file using the attachment API. This is mandatory when an attachment is included.
name	Conditional	string	PurchaseOrderExemptionForm123.docx		Name of the attachment. You will obtain this value after attaching your file using the attachment API, but you may change the name for your own reference when including this attachment in any order request. This is free text input. This is mandatory when an attachment is included.
contacts	Yes	array [objects]			Contact information consists of the Ordering contact details, Technical contact details, and Notification contact details.
contactType	Yes	string	ORDERING	ORDERING, TECHNICAL, NOTIFICATION	There are three types of contact persons: Ordering, Technical, and Notification. All three contacts are mandatory. - Ordering contact person: Person who created the order. 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. It is recommended to also include the work phone country code. Additional information such as mobile phone country code, mobile phone number, and their availability to take calls on their mobile phone may also be provided. With the exception of the mandatory contact information required for the Technical contact, any other additional contact information passed together with a 'userName' for Ordering, Technical, and Notification contacts will be ignored. For example, when 'email' and 'workPhone' are passed with 'userName' for Notification contact, these contact details will be ignored.
name	Conditional	string	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. Example: +571 It is recommended to include the work phone country code.
workPhone	Conditional	string	0148211111		Work phone number of contact person. This is free text input. This is mandatory when the Technical contact does not have 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. This is mandatory for the Technical contact. Call Preference - Description NEVER - Does not take calls. ANYTIME - Takes calls anytime. MY_BUSINESS_HOURS - Takes calls only during their business days from 9am to 5pm in their specified time zone. The body parameter 'workPhoneTimeZone' is mandatory to pass when this option is selected. IBX_BUSINESS_HOURS - Takes calls only during the business hours of the IBX. This would be in the IBX time zone from Mondays to Fridays, 9am to 5pm. Deprecated values BUSINESS_HOURS - This value will be removed in the near future.
workPhoneTimeZone	Conditional	string	Europe/London	Click here for applicable values.	This indicates the specific timezone of the Technical contact's business hours that follows the IANA time zone database names format. This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.
mobilePhoneCountryCode	No	string	+1		Country code for 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. For description of applicable values, refer to description of body parameter 'workPhonePrefToCall'.
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. 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.

Copy

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

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 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, number, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}]

This method orders equipment installation per customer specifications by an Equinix IBX Technician. This can only be done by a user with Smart Hands ordering 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 Access Token section.

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

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

Copy

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 Attachments File under the API Reference section.

Copy

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. For example, 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. Refer to POST Attachments File under the API Reference section for more information.
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.
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.
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. Refer to POST Attachments File under the API Reference section for more information.
id	Conditional	string	abc1fd2e-345f-67g4-hi89-01jk234l5m6n		ID of the attachment. You will obtain this value after attaching your file using the attachment API. This is mandatory when an attachment is included.
name	Conditional	string	PurchaseOrderExemptionForm123.docx		Name of the attachment. You will obtain this value after attaching your file using the attachment API, but you may change the name for your own reference when including this attachment in any order request. This is free text input. This is mandatory when an attachment is included.
contacts	Yes	array [objects]			Contact information consists of the Ordering contact details, Technical contact details, and Notification contact details.
contactType	Yes	string	ORDERING	ORDERING, TECHNICAL, NOTIFICATION	There are three types of contact persons: Ordering, Technical, and Notification. All three contacts are mandatory. - Ordering contact person: Person who created the order. 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. It is recommended to also include the work phone country code. Additional information such as mobile phone country code, mobile phone number, and their availability to take calls on their mobile phone may also be provided. With the exception of the mandatory contact information required for the Technical contact, any other additional contact information passed together with a 'userName' for Ordering, Technical, and Notification contacts will be ignored. For example, when 'email' and 'workPhone' are passed with 'userName' for Notification contact, these contact details will be ignored.
name	Conditional	string	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. Example: +571 It is recommended to include the work phone country code.
workPhone	Conditional	string	0148211111		Work phone number of contact person. This is free text input. This is mandatory when the Technical contact does not have 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. This is mandatory for the Technical contact. Call Preference - Description NEVER - Does not take calls. ANYTIME - Takes calls anytime. MY_BUSINESS_HOURS - Takes calls only during their business days from 9am to 5pm in their specified time zone. The body parameter 'workPhoneTimeZone' is mandatory to pass when this option is selected. IBX_BUSINESS_HOURS - Takes calls only during the business hours of the IBX. This would be in the IBX time zone from Mondays to Fridays, 9am to 5pm. Deprecated values BUSINESS_HOURS - This value will be removed in the near future.
workPhoneTimeZone	Conditional	string	Europe/London	Click here for applicable values.	This indicates the specific timezone of the Technical contact's business hours that follows the IANA time zone database names format. This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.
mobilePhoneCountryCode	No	string	+1		Country code for 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. For description of applicable values, refer to description of body parameter 'workPhonePrefToCall'.
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. 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.

Copy

{
    "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

The following video shows how to create a cage clean-up smart hands order using Equinix Customer Portal APIs.
Click here to download the postman scripts shown in this demo.

Step 1: Authenticate

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

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, number, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}]}

This method orders trash removal or cage cleanup from a specific cage in the IBX where the user has Smart Hands ordering 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 Access Token section.

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

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

Copy

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 Attachments File under the API Reference section.

Copy

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. For example, 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. Refer to POST Attachments File under the API Reference section for more information.
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.
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.
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. Refer to POST Attachments File under the API Reference section for more information.
id	Conditional	string	abc1fd2e-345f-67g4-hi89-01jk234l5m6n		ID of the attachment. You will obtain this value after attaching your file using the attachment API. This is mandatory when an attachment is included.
name	Conditional	string	PurchaseOrderExemptionForm123.docx		Name of the attachment. You will obtain this value after attaching your file using the attachment API, but you may change the name for your own reference when including this attachment in any order request. This is free text input. This is mandatory when an attachment is included.
contacts	Yes	array [objects]			Contact information consists of the Ordering contact details, Technical contact details, and Notification contact details.
contactType	Yes	string	ORDERING	ORDERING, TECHNICAL, NOTIFICATION	There are three types of contact persons: Ordering, Technical, and Notification. All three contacts are mandatory. - Ordering contact person: Person who created the order. 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. It is recommended to also include the work phone country code. Additional information such as mobile phone country code, mobile phone number, and their availability to take calls on their mobile phone may also be provided. With the exception of the mandatory contact information required for the Technical contact, any other additional contact information passed together with a 'userName' for Ordering, Technical, and Notification contacts will be ignored. For example, when 'email' and 'workPhone' are passed with 'userName' for Notification contact, these contact details will be ignored.
name	Conditional	string	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. Example: +571 It is recommended to include the work phone country code.
workPhone	Conditional	string	0148211111		Work phone number of contact person. This is free text input. This is mandatory when the Technical contact does not have 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. This is mandatory for the Technical contact. Call Preference - Description NEVER - Does not take calls. ANYTIME - Takes calls anytime. MY_BUSINESS_HOURS - Takes calls only during their business days from 9am to 5pm in their specified time zone. The body parameter 'workPhoneTimeZone' is mandatory to pass when this option is selected. IBX_BUSINESS_HOURS - Takes calls only during the business hours of the IBX. This would be in the IBX time zone from Mondays to Fridays, 9am to 5pm. Deprecated values BUSINESS_HOURS - This value will be removed in the near future.
workPhoneTimeZone	Conditional	string	Europe/London	Click here for applicable values.	This indicates the specific timezone of the Technical contact's business hours that follows the IANA time zone database names format. This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.
mobilePhoneCountryCode	No	string	+1		Country code for 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. For description of applicable values, refer to description of body parameter 'workPhonePrefToCall'.
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. 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.

Copy

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

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 Getting Started for ECP use cases for instructions on how to schedule an inbound shipment, or refer to How to retrieve order history? under the Getting Started 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, cabinets[...], accountNumber}]}, serviceDetails {inboundShipmentOrderNumber, discardShipmentMaterial, copyOfPackingSlipNeeded, scopeOfWork, needSupportFromASubmarineCableStationEngineer}, attachments [{id, name}], schedule {scheduleType, requestedStartDate, requestedCompletionDate}, customerReferenceNumber, purchaseOrder {purchaseOrderType, number, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}]

This method requests inbound shipment unpacking and packaging disposal. This can only be done by a user with Smart Hands ordering 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 Getting Started 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 Getting Started 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 Access Token section.

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

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

Copy

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 Attachments File under the API Reference section.

Copy

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. For example, 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 Getting Started 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 Getting Started 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. Refer to POST Attachments File under the API Reference section for more information.
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.
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.
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. Refer to POST Attachments File under the API Reference section for more information.
id	Conditional	string	abc1fd2e-345f-67g4-hi89-01jk234l5m6n		ID of the attachment. You will obtain this value after attaching your file using the attachment API. This is mandatory when an attachment is included.
name	Conditional	string	PurchaseOrderExemptionForm123.docx		Name of the attachment. You will obtain this value after attaching your file using the attachment API, but you may change the name for your own reference when including this attachment in any order request. This is free text input. This is mandatory when an attachment is included.
contacts	Yes	array [objects]			Contact information consists of the Ordering contact details, Technical contact details, and Notification contact details.
contactType	Yes	string	ORDERING	ORDERING, TECHNICAL, NOTIFICATION	There are three types of contact persons: Ordering, Technical, and Notification. All three contacts are mandatory. - Ordering contact person: Person who created the order. 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. It is recommended to also include the work phone country code. Additional information such as mobile phone country code, mobile phone number, and their availability to take calls on their mobile phone may also be provided. With the exception of the mandatory contact information required for the Technical contact, any other additional contact information passed together with a 'userName' for Ordering, Technical, and Notification contacts will be ignored. For example, when 'email' and 'workPhone' are passed with 'userName' for Notification contact, these contact details will be ignored.
name	Conditional	string	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. Example: +571 It is recommended to include the work phone country code.
workPhone	Conditional	string	0148211111		Work phone number of contact person. This is free text input. This is mandatory when the Technical contact does not have 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. This is mandatory for the Technical contact. Call Preference - Description NEVER - Does not take calls. ANYTIME - Takes calls anytime. MY_BUSINESS_HOURS - Takes calls only during their business days from 9am to 5pm in their specified time zone. The body parameter 'workPhoneTimeZone' is mandatory to pass when this option is selected. IBX_BUSINESS_HOURS - Takes calls only during the business hours of the IBX. This would be in the IBX time zone from Mondays to Fridays, 9am to 5pm. Deprecated values BUSINESS_HOURS - This value will be removed in the near future.
workPhoneTimeZone	Conditional	string	Europe/London	Click here for applicable values.	This indicates the specific timezone of the Technical contact's business hours that follows the IANA time zone database names format. This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.
mobilePhoneCountryCode	No	string	+1		Country code for 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. For description of applicable values, refer to description of body parameter 'workPhonePrefToCall'.
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. 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.

Copy

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

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, needSupportFromASubmarineCableStationEngineer}, attachments [{id, name}], schedule {scheduleType, requestedStartDate, requestedCompletionDate}, customerReferenceNumber, purchaseOrder {purchaseOrderType, number, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}]

This method orders cables per customer specifications. This can only be done under a user with Smart Hands ordering 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 Access Token section.

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

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

Copy

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 Attachments File under the API Reference section.

Copy

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

Copy

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 Attachments File under the API Reference section.

Copy

ccurl -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. For example, 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, 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. Refer to POST Attachments File under the API Reference section for more information.
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.
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.
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. Refer to POST Attachments File under the API Reference section for more information.
id	Conditional	string	abc1fd2e-345f-67g4-hi89-01jk234l5m6n		ID of the attachment. You will obtain this value after attaching your file using the attachment API. This is mandatory when an attachment is included.
name	Conditional	string	PurchaseOrderExemptionForm123.docx		Name of the attachment. You will obtain this value after attaching your file using the attachment API, but you may change the name for your own reference when including this attachment in any order request. This is free text input. This is mandatory when an attachment is included.
contacts	Yes	array [objects]			Contact information consists of the Ordering contact details, Technical contact details, and Notification contact details.
contactType	Yes	string	ORDERING	ORDERING, TECHNICAL, NOTIFICATION	There are three types of contact persons: Ordering, Technical, and Notification. All three contacts are mandatory. - Ordering contact person: Person who created the order. 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. It is recommended to also include the work phone country code. Additional information such as mobile phone country code, mobile phone number, and their availability to take calls on their mobile phone may also be provided. With the exception of the mandatory contact information required for the Technical contact, any other additional contact information passed together with a 'userName' for Ordering, Technical, and Notification contacts will be ignored. For example, when 'email' and 'workPhone' are passed with 'userName' for Notification contact, these contact details will be ignored.
name	Conditional	string	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. Example: +571 It is recommended to include the work phone country code.
workPhone	Conditional	string	0148211111		Work phone number of contact person. This is free text input. This is mandatory when the Technical contact does not have 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. This is mandatory for the Technical contact. Call Preference - Description NEVER - Does not take calls. ANYTIME - Takes calls anytime. MY_BUSINESS_HOURS - Takes calls only during their business days from 9am to 5pm in their specified time zone. The body parameter 'workPhoneTimeZone' is mandatory to pass when this option is selected. IBX_BUSINESS_HOURS - Takes calls only during the business hours of the IBX. This would be in the IBX time zone from Mondays to Fridays, 9am to 5pm. Deprecated values BUSINESS_HOURS - This value will be removed in the near future.
workPhoneTimeZone	Conditional	string	Europe/London	Click here for applicable values.	This indicates the specific timezone of the Technical contact's business hours that follows the IANA time zone database names format. This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.
mobilePhoneCountryCode	No	string	+1		Country code for 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. For description of applicable values, refer to description of body parameter 'workPhonePrefToCall'.
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. 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.

Copy

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

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.

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, number, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall, mobilePhoneTimeZone}]

This method requests the location of your packages at the IBX. This can only be done by a user with Smart Hands ordering 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 Getting Started 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 Getting Started 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 Access Token section.

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

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

Copy

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 Attachments File API under the API Reference section.

Copy

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. For example, 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.
shipmentOrderNumber	Yes	string	1-1234567890		The order number for the 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 Getting Started 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 Getting Started 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. For example, 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. Refer to POST Attachments File under the API Reference section for more information.
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.
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.
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. Refer to POST Attachments File under the API Reference section for more information.
id	Conditional	string	abc1fd2e-345f-67g4-hi89-01jk234l5m6n		ID of the attachment. You will obtain this value after attaching your file using the attachment API. This is mandatory when an attachment is included.
name	Conditional	string	PurchaseOrderExemptionForm123.docx		Name of the attachment. You will obtain this value after attaching your file using the attachment API, but you may change the name for your own reference when including this attachment in any order request. This is free text input. This is mandatory when an attachment is included.
contacts	Yes	array [objects]			Contact information consists of the Ordering contact details, Technical contact details, and Notification contact details.
contactType	Yes	string	ORDERING	ORDERING, TECHNICAL, NOTIFICATION	There are three types of contact persons: Ordering, Technical, and Notification. All three contacts are mandatory. - Ordering contact person: Person who created the order. 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. It is recommended to also include the work phone country code. Additional information such as mobile phone country code, mobile phone number, and their availability to take calls on their mobile phone may also be provided. With the exception of the mandatory contact information required for the Technical contact, any other additional contact information passed together with a 'userName' for Ordering, Technical, and Notification contacts will be ignored. For example, when 'email' and 'workPhone' are passed with 'userName' for Notification contact, these contact details will be ignored.
name	Conditional	string	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. Example: +571 It is recommended to include the work phone country code.
workPhone	Conditional	string	0148211111		Work phone number of contact person. This is free text input. This is mandatory when the Technical contact does not have 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. This is mandatory for the Technical contact. Call Preference - Description NEVER - Does not take calls. ANYTIME - Takes calls anytime. MY_BUSINESS_HOURS - Takes calls only during their business days from 9am to 5pm in their specified time zone. The body parameter 'workPhoneTimeZone' is mandatory to pass when this option is selected. IBX_BUSINESS_HOURS - Takes calls only during the business hours of the IBX. This would be in the IBX time zone from Mondays to Fridays, 9am to 5pm. Deprecated values BUSINESS_HOURS - This value will be removed in the near future.
workPhoneTimeZone	Conditional	string	Europe/London	Click here for applicable values.	This indicates the specific timezone of the Technical contact's business hours that follows the IANA time zone database names format. This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.
mobilePhoneCountryCode	No	string	+1		Country code for 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. For description of applicable values, refer to description of body parameter 'workPhonePrefToCall'.
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. 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.

Copy

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

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 Getting Started 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, number, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}]

This method orders patch cable installations per customer specifications by an Equinix IBX Technician. This can only be done by a user with Smart Hands ordering 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 Access Token section.

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

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

Copy

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 Attachments File under the API Reference section.

Copy

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. For example, 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 Getting Started 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, 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. Refer to POST Attachments File under the API Reference section for more information.
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.
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.
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. Refer to POST Attachments File under the API Reference section for more information.
id	Conditional	string	abc1fd2e-345f-67g4-hi89-01jk234l5m6n		ID of the attachment. You will obtain this value after attaching your file using the attachment API. This is mandatory when an attachment is included.
name	Conditional	string	PurchaseOrderExemptionForm123.docx		Name of the attachment. You will obtain this value after attaching your file using the attachment API, but you may change the name for your own reference when including this attachment in any order request. This is free text input. This is mandatory when an attachment is included.
contacts	Yes	array [objects]			Contact information consists of the Ordering contact details, Technical contact details, and Notification contact details.
contactType	Yes	string	ORDERING	ORDERING, TECHNICAL, NOTIFICATION	There are three types of contact persons: Ordering, Technical, and Notification. All three contacts are mandatory. - Ordering contact person: Person who created the order. 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. It is recommended to also include the work phone country code. Additional information such as mobile phone country code, mobile phone number, and their availability to take calls on their mobile phone may also be provided. With the exception of the mandatory contact information required for the Technical contact, any other additional contact information passed together with a 'userName' for Ordering, Technical, and Notification contacts will be ignored. For example, when 'email' and 'workPhone' are passed with 'userName' for Notification contact, these contact details will be ignored.
name	Conditional	string	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. Example: +571 It is recommended to include the work phone country code.
workPhone	Conditional	string	0148211111		Work phone number of contact person. This is free text input. This is mandatory when the Technical contact does not have 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. This is mandatory for the Technical contact. Call Preference - Description NEVER - Does not take calls. ANYTIME - Takes calls anytime. MY_BUSINESS_HOURS - Takes calls only during their business days from 9am to 5pm in their specified time zone. The body parameter 'workPhoneTimeZone' is mandatory to pass when this option is selected. IBX_BUSINESS_HOURS - Takes calls only during the business hours of the IBX. This would be in the IBX time zone from Mondays to Fridays, 9am to 5pm. Deprecated values BUSINESS_HOURS - This value will be removed in the near future.
workPhoneTimeZone	Conditional	string	Europe/London	Click here for applicable values.	This indicates the specific timezone of the Technical contact's business hours that follows the IANA time zone database names format. This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.
mobilePhoneCountryCode	No	string	+1		Country code for 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. For description of applicable values, refer to description of body parameter 'workPhonePrefToCall'.
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. 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.

Copy

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

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.

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, number, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}]

This method orders patch cable removal per customer specifications by an Equinix IBX Technician. This can only be done by a user with Smart Hands ordering 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 Access Token section.

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

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

Copy

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 Attachments File under the API Reference section.

Copy

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. For example, 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 Getting Started 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. Refer to POST Attachments File under the API Reference section for more information.
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.
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.
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. Refer to POST Attachments File under the API Reference section for more information.
id	Conditional	string	abc1fd2e-345f-67g4-hi89-01jk234l5m6n		ID of the attachment. You will obtain this value after attaching your file using the attachment API. This is mandatory when an attachment is included.
name	Conditional	string	PurchaseOrderExemptionForm123.docx		Name of the attachment. You will obtain this value after attaching your file using the attachment API, but you may change the name for your own reference when including this attachment in any order request. This is free text input. This is mandatory when an attachment is included.
contacts	Yes	array [objects]			Contact information consists of the Ordering contact details, Technical contact details, and Notification contact details.
contactType	Yes	string	ORDERING	ORDERING, TECHNICAL, NOTIFICATION	There are three types of contact persons: Ordering, Technical, and Notification. All three contacts are mandatory. - Ordering contact person: Person who created the order. 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. It is recommended to also include the work phone country code. Additional information such as mobile phone country code, mobile phone number, and their availability to take calls on their mobile phone may also be provided. With the exception of the mandatory contact information required for the Technical contact, any other additional contact information passed together with a 'userName' for Ordering, Technical, and Notification contacts will be ignored. For example, when 'email' and 'workPhone' are passed with 'userName' for Notification contact, these contact details will be ignored.
name	Conditional	string	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. Example: +571 It is recommended to include the work phone country code.
workPhone	Conditional	string	0148211111		Work phone number of contact person. This is free text input. This is mandatory when the Technical contact does not have 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. This is mandatory for the Technical contact. Call Preference - Description NEVER - Does not take calls. ANYTIME - Takes calls anytime. MY_BUSINESS_HOURS - Takes calls only during their business days from 9am to 5pm in their specified time zone. The body parameter 'workPhoneTimeZone' is mandatory to pass when this option is selected. IBX_BUSINESS_HOURS - Takes calls only during the business hours of the IBX. This would be in the IBX time zone from Mondays to Fridays, 9am to 5pm. Deprecated values BUSINESS_HOURS - This value will be removed in the near future.
workPhoneTimeZone	Conditional	string	Europe/London	Click here for applicable values.	This indicates the specific timezone of the Technical contact's business hours that follows the IANA time zone database names format. This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.
mobilePhoneCountryCode	No	string	+1		Country code for 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. For description of applicable values, refer to description of body parameter 'workPhonePrefToCall'.
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. 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.

Copy

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

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.

	POST /smarthands/picturesDocument
Method	POST
URL or End Point	/v1/orders/smarthands/picturesDocument
Headers	Authorization, Content-Type
Query Parameters	Not applicable
Body	ibxLocation {ibx, cages [{cage, cabinets[...], accountNumber}]}, serviceDetails {documentOnly, cameraProvidedBy, specificDateAndTime, description, scopeOfWork, needSupportFromASubmarineCableStationEngineer}, attachments [{id, name}], schedule {scheduleType, requestedStartDate, requestedCompletionDate}, customerReferenceNumber, purchaseOrder {purchaseOrderType, number, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}]

This method requests an IBX technician to provide cage-related pictures or documentation at cages where the user has Smart Hands ordering 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 Access Token section.

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

The request indicates two scenarios: An order for cage-related photos without additional information, attachments, or contacts; and order for cage-related photos with additional information, attachments, and contacts.

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

Order cage-related photos without additional information, attachments, or contacts

Copy

curl -X
POST "https://api.equinix.com/v1/orders/smarthands/picturesDocument"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
    "ibxLocation": {
    "ibx": "AM1",
    "cages": [
      {
        "cage": "AM1:0J:00JD11",
        "accountNumber": "126854"
      }
    ]
  },
  "serviceDetails": {
    "documentOnly": false,
    "cameraProvidedBy": "Equinix",
    "specificDateAndTime": true,
    "description": "Take a photo of the patch panel cable arrangement, to include all labels clearly.",
    "scopeOfWork": "Indicate what camera was used, and provide the photos in print size 3.6 x 3.007 inches.",
  },
  "schedule": {
    "scheduleType": "SCHEDULED_MAINTENANCE",
    "requestedStartDate": "2019-08-30T22:00:49.776Z",
    "requestedCompletionDate": "2019-08-31T22:00:49.776Z"
  },
  "purchaseOrder": {
    "purchaseOrderType": "NEW",
    "number": "1037503648"
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "userName": "johndoe",
      "workPhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

Order cage-related pictures with additional information, attachments, and contacts

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

Copy

curl -X
POST "https://api.equinix.com/v1/orders/smarthands/picturesDocument"
-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": {
    "documentOnly": false,
    "cameraProvidedBy": "Equinix",
    "specificDateAndTime": true,
    "description": "Take a photo of the patch panel cable arrangement, to include all labels clearly.",
    "scopeOfWork": "Indicate what camera was used, and provide the photos in print size 3.6 x 3.007 inches.",
    "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": "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. For example, 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.
documentOnly	Yes	boolean	false	true, false	Defines if cage-related photos or documentation is required. If 'true', only documentation is required, and the only other mandatory field to pass is "scopeOfWork". Indicate the nature of the desired documentation in "scopeOfWork". If 'false', photos are required, and the other mandatory fields to pass are: "cameraProvidedBy", "specificDateAndTime", "description", and "scopeOfWork".
cameraProvidedBy	Conditional	string	Equinix	Equinix, Customer	Indicates who would be providing the camera to take pictures with. Camera Provided By - Description Equinix - Equinix's camera will be used. Customer - Customer's camera will be used. This is mandatory when "documentOnly" is 'false'.
specificDateAndTime	Conditional	boolean	true	true, false	Indicates if a specific date and time are required to carry out this task. If 'true', the task must be carried out in a specific timeframe, and only 'SCHEDULED_MAINTENANCE' can be passed for the parameter, "scheduleType". If 'false', the timeframe for this task is flexible, and all 3 schedule types can be passed for the parameter, "scheduleType". This is mandatory when "documentOnly" is 'false'.
description	Conditional	string	Take a photo of the patch panel cable arrangement, to include all labels clearly.		Description of the photo that customer would like to include. This is free text. This is mandatory when "documentOnly" is 'false'.
scopeOfWork	Yes	string	Indicate what camera was used, and provide the photos in print size 3.6 x 3.007 inches.		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. Refer to POST Attachments File under the API Reference section for more information.
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.
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.
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	Yes	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	Yes	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. Refer to POST Attachments File under the API Reference section for more information.
id	Conditional	string	abc1fd2e-345f-67g4-hi89-01jk234l5m6n		ID of the attachment. You will obtain this value after attaching your file using the attachment API. This is mandatory when an attachment is included.
name	Conditional	string	PurchaseOrderExemptionForm123.docx		Name of the attachment. You will obtain this value after attaching your file using the attachment API, but you may change the name for your own reference when including this attachment in any order request. This is free text input. This is mandatory when an attachment is included.
contacts	Yes	array [objects]			Contact information consists of the Ordering contact details, Technical contact details, and Notification contact details.
contactType	Yes	string	ORDERING	ORDERING, TECHNICAL, NOTIFICATION	There are three types of contact persons: Ordering, Technical, and Notification. All three contacts are mandatory. - Ordering contact person: Person who created the order. 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. It is recommended to also include the work phone country code. Additional information such as mobile phone country code, mobile phone number, and their availability to take calls on their mobile phone may also be provided. With the exception of the mandatory contact information required for the Technical contact, any other additional contact information passed together with a 'userName' for Ordering, Technical, and Notification contacts will be ignored. For example, when 'email' and 'workPhone' are passed with 'userName' for Notification contact, these contact details will be ignored.
name	Conditional	string	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. Example: +571 It is recommended to include the work phone country code.
workPhone	Conditional	string	0148211111		Work phone number of contact person. This is free text input. This is mandatory when the Technical contact does not have 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. This is mandatory for the Technical contact. Call Preference - Description NEVER - Does not take calls. ANYTIME - Takes calls anytime. MY_BUSINESS_HOURS - Takes calls only during their business days from 9am to 5pm in their specified time zone. The body parameter 'workPhoneTimeZone' is mandatory to pass when this option is selected. IBX_BUSINESS_HOURS - Takes calls only during the business hours of the IBX. This would be in the IBX time zone from Mondays to Fridays, 9am to 5pm. Deprecated values BUSINESS_HOURS - This value will be removed in the near future.
workPhoneTimeZone	Conditional	string	Europe/London	Click here for applicable values.	This indicates the specific timezone of the Technical contact's business hours that follows the IANA time zone database names format. This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.
mobilePhoneCountryCode	No	string	+1		Country code for 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. For description of applicable values, refer to description of body parameter 'workPhonePrefToCall'.
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. 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.

Copy

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

Order to move patch cables

Step 1: Authenticate

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

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, number, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}]

This method orders patch cables to be moved between devices by an Equinix IBX Technician. This can only be done by a user with Smart Hands ordering 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 Access Token section.

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

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

Copy

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 Attachments File under the API Reference section.

Copy

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

Copy

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 Attachments File under the API Reference section.

Copy

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. For example, 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. Refer to POST Attachments File under the API Reference section for more information.
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.
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.
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. Refer to POST Attachments File under the API Reference section for more information.
id	Conditional	string	abc1fd2e-345f-67g4-hi89-01jk234l5m6n		ID of the attachment. You will obtain this value after attaching your file using the attachment API. This is mandatory when an attachment is included.
name	Conditional	string	PurchaseOrderExemptionForm123.docx		Name of the attachment. You will obtain this value after attaching your file using the attachment API, but you may change the name for your own reference when including this attachment in any order request. This is free text input. This is mandatory when an attachment is included.
contacts	Yes	array [objects]			Contact information consists of the Ordering contact details, Technical contact details, and Notification contact details.
contactType	Yes	string	ORDERING	ORDERING, TECHNICAL, NOTIFICATION	There are three types of contact persons: Ordering, Technical, and Notification. All three contacts are mandatory. - Ordering contact person: Person who created the order. 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. It is recommended to also include the work phone country code. Additional information such as mobile phone country code, mobile phone number, and their availability to take calls on their mobile phone may also be provided. With the exception of the mandatory contact information required for the Technical contact, any other additional contact information passed together with a 'userName' for Ordering, Technical, and Notification contacts will be ignored. For example, when 'email' and 'workPhone' are passed with 'userName' for Notification contact, these contact details will be ignored.
name	Conditional	string	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. Example: +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 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. This is mandatory for the Technical contact. Call Preference - Description NEVER - Does not take calls. ANYTIME - Takes calls anytime. MY_BUSINESS_HOURS - Takes calls only during their business days from 9am to 5pm in their specified time zone. The body parameter 'workPhoneTimeZone' is mandatory to pass when this option is selected. IBX_BUSINESS_HOURS - Takes calls only during the business hours of the IBX. This would be in the IBX time zone from Mondays to Fridays, 9am to 5pm. Deprecated values BUSINESS_HOURS - This value will be removed in the near future.
workPhoneTimeZone	Conditional	string	Europe/London	Click here for applicable values.	This indicates the specific timezone of the Technical contact's business hours that follows the IANA time zone database names format. This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.
mobilePhoneCountryCode	No	string	+1		Country code for 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. For description of applicable values, refer to description of body parameter 'workPhonePrefToCall'.
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. 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.

Copy

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

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}], scopeOfWork, needSupportFromASubmarineCableStationEngineer}, attachments [{id, name}], schedule {scheduleType, requestedStartDate, requestedCompletionDate}, customerReferenceNumber, purchaseOrder {purchaseOrderType, number, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}]

This method orders jumper cables to be run between devices by an Equinix IBX Technician. This can only be done by a user with Smart Hands ordering 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 Access Token section.

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

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

Copy

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 Attachments File under the API Reference section.

Copy

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

Copy

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 Attachments File under the API Reference section.

Copy

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. For example, 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: Jumper Type Media Type Connector Type Cable ID (optional) Should Equinix provide you Tx/Rx light levels, Yes Or No? Devices to Connect Device #1: Name/Panel: Device Slot: Device Ports: Device #2(Optional): Name/Panel: Device Slot: Device Ports: If any device is being shipped to Equinix, 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. 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: Jumper Type Media Type Connector Type Cable ID (optional) Should Equinix provide you Tx/Rx light levels, Yes Or No? Devices to Connect: Device #1: Name/Panel: Device Slot: Device Ports: Device #2(Optional): Name/Panel: Device Slot: Device Ports: If any device is being shipped to Equinix, 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. 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. Refer to POST Attachments File under the API Reference section for more information.
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.
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.
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. Refer to POST Attachments File under the API Reference section for more information.
id	Conditional	string	abc1fd2e-345f-67g4-hi89-01jk234l5m6n		ID of the attachment. You will obtain this value after attaching your file using the attachment API. This is mandatory when an attachment is included.
name	Conditional	string	PurchaseOrderExemptionForm123.docx		Name of the attachment. You will obtain this value after attaching your file using the attachment API, but you may change the name for your own reference when including this attachment in any order request. This is free text input. This is mandatory when an attachment is included.
contacts	Yes	array [objects]			Contact information consists of the Ordering contact details, Technical contact details, and Notification contact details.
contactType	Yes	string	ORDERING	ORDERING, TECHNICAL, NOTIFICATION	There are three types of contact persons: Ordering, Technical, and Notification. All three contacts are mandatory. - Ordering contact person: Person who created the order. 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. It is recommended to also include the work phone country code. Additional information such as mobile phone country code, mobile phone number, and their availability to take calls on their mobile phone may also be provided. With the exception of the mandatory contact information required for the Technical contact, any other additional contact information passed together with a 'userName' for Ordering, Technical, and Notification contacts will be ignored. For example, when 'email' and 'workPhone' are passed with 'userName' for Notification contact, these contact details will be ignored.
name	Conditional	string	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. Example: +571 It is recommended to include the work phone country code.
workPhone	Conditional	string	0148211111		Work phone number of contact person. This is free text input. This is mandatory when the Technical contact does not have 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. This is mandatory for the Technical contact. Call Preference - Description NEVER - Does not take calls. ANYTIME - Takes calls anytime. MY_BUSINESS_HOURS - Takes calls only during their business days from 9am to 5pm in their specified time zone. The body parameter 'workPhoneTimeZone' is mandatory to pass when this option is selected. IBX_BUSINESS_HOURS - Takes calls only during the business hours of the IBX. This would be in the IBX time zone from Mondays to Fridays, 9am to 5pm. Deprecated values BUSINESS_HOURS - This value will be removed in the near future.
workPhoneTimeZone	Conditional	string	Europe/London	Click here for applicable values.	This indicates the specific timezone of the Technical contact's business hours that follows the IANA time zone database names format. This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.
mobilePhoneCountryCode	No	string	+1		Country code for 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. For description of applicable values, refer to description of body parameter 'workPhonePrefToCall'.
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. 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.

Copy

{
  "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

The following video shows how to create an unlisted smart hands order using Equinix Customer Portal APIs.
Click here to download the postman scripts shown in this demo.

Step 1: Authenticate

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

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, number, attachment {id, name}}, contacts [{contactType, userName}, {contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}]

This method requests an unlisted Smart Hands order at an IBX location where the user has Smart Hands ordering 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 Access Token section.

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

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

Copy

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 Attachments File under the API Reference section.

Copy

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. For example, 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. Refer to POST Attachments File under the API Reference section for more information.
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.
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.
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. Refer to POST Attachments File under the API Reference section for more information.
id	Conditional	string	abc1fd2e-345f-67g4-hi89-01jk234l5m6n		ID of the attachment. You will obtain this value after attaching your file using the attachment API. This is mandatory when an attachment is included.
name	Conditional	string	PurchaseOrderExemptionForm123.docx		Name of the attachment. You will obtain this value after attaching your file using the attachment API, but you may change the name for your own reference when including this attachment in any order request. This is free text input. This is mandatory when an attachment is included.
contacts	Yes	array [objects]			Contact information consists of the Ordering contact details, Technical contact details, and Notification contact details.
contactType	Yes	string	ORDERING	ORDERING, TECHNICAL, NOTIFICATION	There are three types of contact persons: Ordering, Technical, and Notification. All three contacts are mandatory. - Ordering contact person: Person who created the order. 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. It is recommended to also include the work phone country code. Additional information such as mobile phone country code, mobile phone number, and their availability to take calls on their mobile phone may also be provided. With the exception of the mandatory contact information required for the Technical contact, any other additional contact information passed together with a 'userName' for Ordering, Technical, and Notification contacts will be ignored. For example, when 'email' and 'workPhone' are passed with 'userName' for Notification contact, these contact details will be ignored.
name	Conditional	string	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. Example: +571 It is recommended to include the work phone country code.
workPhone	Conditional	string	0148211111		Work phone number of contact person. This is free text input. This is mandatory when the Technical contact does not have 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. This is mandatory for the Technical contact. Call Preference - Description NEVER - Does not take calls. ANYTIME - Takes calls anytime. MY_BUSINESS_HOURS - Takes calls only during their business days from 9am to 5pm in their specified time zone. The body parameter 'workPhoneTimeZone' is mandatory to pass when this option is selected. IBX_BUSINESS_HOURS - Takes calls only during the business hours of the IBX. This would be in the IBX time zone from Mondays to Fridays, 9am to 5pm. Deprecated values BUSINESS_HOURS - This value will be removed in the near future.
workPhoneTimeZone	Conditional	string	Europe/London	Click here for applicable values.	This indicates the specific timezone of the Technical contact's business hours that follows the IANA time zone database names format. This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.
mobilePhoneCountryCode	No	string	+1		Country code for 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. For description of applicable values, refer to description of body parameter 'workPhonePrefToCall'.
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. 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.

Copy

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

Order cage escort

Step 1: Authenticate

Step 2: Schedule a work visit

Step 3: Get Smart Hands Details

Step 4: Order a Cage Escort

Order equipment installation

Step 1: Authenticate

Step 2: Get Smart Hands Details

Step 3: Order Equipment Installation

Order cage clean-up

Step 1: Authenticate

Step 2: Get Smart Hands Details

Step 3: Order a Cage Clean-Up

Order inbound shipment unpacking and packaging disposal

Step 1: Authenticate

Step 2: Schedule an inbound shipment

Step 3: Get Smart Hands Details

Step 4: Order inbound shipment unpacking and packaging disposal

Order more cables

Step 1: Authenticate

Step 2: Get Smart Hands Details

Step 3: Order Cables

Order packages location

Step 1: Authenticate

Step 2: Schedule an inbound shipment

Step 3: Get Smart Hands Details

Step 4: Order packages location

Order patch cable installation

Step 1: Authenticate

Step 2: Get Smart Hands Details

Step 3: Get Connection Details

Step 4: Order Patch Cable Installation

Order patch cable removal

Step 1: Authenticate

Step 2: Get Smart Hands Details

Step 3: Get Connection Details

Step 4: Order Patch Cable Removal

Order photos or documentation of your cage

Step 1: Authenticate

Step 2: Get Smart Hands Details

Step 3: Order Cage- related Photos or Documentation

Order to move patch cables

Step 1: Authenticate

Step 2: Get Smart Hands Details

Step 3: Order Move Patch Cables

Order to run jumper cables

Step 1: Authenticate

Step 2: Get Smart Hands Details\

Step 3: Order Run Jumper Cables

Order unlisted smart hands

Step 1: Authenticate

Step 2: Get Smart Hands Details

Step 3: Order Smart Hands: Others

Was this documentation helpful?