Skip to main content
Index

Schedule shipments

All shipments must be scheduled in advance by creating an inbound or outbound shipment order. Failure to do so may result in the shipment being rejected. Only an Equinix Customer Portal user with Shipments ordering permission can schedule these shipments. The types of shipments currently supported by Equinix Customer Portal APIs may be found here.

 

The following video shows how to create an inbound shipment order using Equinix Customer Portal APIs.

Click here to download the postman scripts shown in this demo. 

 

Schedule inbound shipment

Step 1: Authenticate

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

 

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

 

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

Step 2: Get Shipment Details

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

 

Get Location Information

Retrieve your IBX location information.

 

Use this API to get all available IBX location information such as the ibx location code, cage ID, and cage account number.

 

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

Step 3: Schedule Inbound Shipment

POST /shipment/inbound

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

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

 

The Post shipment inbound API creates an inbound shipment order for inbound shipment of equipment to any IBX that the user has access to. This can only be done under a user with 'Shipments' permission. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

 

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

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

 

The requests indicates four scenarios: 

 

(A) An inbound shipment by the customer without additional information,  attachment, or contacts, but with added Smart Hands fee (delivery after business hours)

 

(B) An inbound shipment by the customer with added additional information,  attachment, contacts, and Smart Hands fee (delivery after business hours)

 

(C) An inbound shipment by a carrier without additional information, attachment, contacts, or Smart Hands request, but with added Smart Hands fee (delivery after business hours)

 

(D) An inbound shipment by a carrier with additional information, attachment, contacts, Smart Hands request, and added Smart Hands fee (delivery after business hours)

 

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

 

(A) An inbound shipment by the customer without additional information,  attachment, or contacts, but with added Smart Hands fee (delivery after business hours)

 

curl -X

POST "https://api.equinix.com/v1/orders/shipment/inbound"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "DC3",
    "cages": [
      {
        "cage": "DC3:01:005000",
        "accountNumber": "2983"
      }
    ]
  },
  "serviceDetails": {
    "estimatedDateTime": "2019-08-23T00:00:30.610Z",
    "shipmentDetails": {
      "inboundType": "CUSTOMER_CARRY",
      "noOfBoxes": 2
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

 

(B) An inbound shipment by the customer with added additional information,  attachment, contacts, and Smart Hands fee (delivery after business hours)

 

Before creating an order with attachment, call the Post Attachment File to attach a file.

 

curl -X

POST "https://api.equinix.com/v1/orders/shipment/inbound"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "DC3",
    "cages": [
      {
        "cage": "DC3:01:005000",
        "accountNumber": "2983"
      }
    ]
  },
  "customerReferenceNumber": "ISO082019-101",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "serviceDetails": {
    "estimatedDateTime": "2019-08-23T00:00:30.610Z",
    "shipmentDetails": {
      "inboundType": "CUSTOMER_CARRY",
      "noOfBoxes": 2,
      "isOverSized": true,
      "trackingNumber": [
        "t1Z294AK92654678989",
        "t1Z086DK96424456780"
      ]
    },
    "inboundRequestDescription": "Place all boxes upright with labels facing upwards."
  },
  "attachments": [
    {
      "id": "26f40e6e-dd6e-48fa-a797-62c0d3157388",
      "name": "AdditionalShipmentWorkDetails.docx"
    }
  ],
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@corporation.com",
      "workPhoneCountryCode": "+1",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Pacific/Honolulu",
      "mobilePhoneCountryCode": "+1",
      "mobilePhone": "0123456789"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "jillsnow"
    }
  ]
}'

 

(C) An inbound shipment by a carrier without additional information, attachment, contacts, or Smart Hands request, but with added Smart Hands fee (delivery after business hours)

 

curl -X

POST "https://api.equinix.com/v1/orders/shipment/inbound"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "DC3",
    "cages": [
      {
        "cage": "DC3:01:005000",
        "accountNumber": "2983"
      }
    ]
  },
  "serviceDetails": {
    "estimatedDateTime": "2019-08-23T00:00:30.610Z",
    "shipmentDetails": {
      "inboundType": "CARRIER",
      "carrierName": "OTHER",   
      "otherCarrierName": "YAMATO", 
      "noOfBoxes": 2,    
      "isOverSized": true,
      "trackingNumber": [
        "t1Z294AK92654678989",
        "t1Z086DK96424456780"
      ]
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    }
  ]
}'

 

(D) An inbound shipment by a carrier with additional information, attachment, contacts, Smart Hands request, and added Smart Hands fee (delivery after business hours)

 

Before creating an order with attachment, call the Post Attachment File to attach a file.

 

curl -X

POST "https://api.equinix.com/v1/orders/shipment/inbound"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "DC3",
    "cages": [
      {
        "cage": "DC3:01:005000",
        "accountNumber": "2983"
      }
    ]
  },
  "customerReferenceNumber": "ISO082019-101",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "serviceDetails": {
    "estimatedDateTime": "2019-08-23T00:00:30.610Z",
    "shipmentDetails": {
      "inboundType": "CARRIER",
      "carrierName": "OTHER",   
      "otherCarrierName": "YAMATO", 
      "noOfBoxes": 2,    
      "isOverSized": true,
      "trackingNumber": [
        "t1Z294AK92654678989",
        "t1Z086DK96424456780"
      ]
    },
    "deliverToCage": true,
    "inboundRequestDescription": "Place all boxes upright with labels facing upwards."
  },
  "attachments": [
    {
      "id": "26f40e6e-dd6e-48fa-a797-62c0d3157388",
      "name": "AdditionalShipmentWorkDetails.docx"
    }
  ],
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "johndoe"
    },
    {
      "contactType": "TECHNICAL",
      "name": "Jane Smith",
      "email": "janesmith@corporation.com",
      "workPhoneCountryCode": "+1",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Pacific/Honolulu",
      "mobilePhoneCountryCode": "+1",
      "mobilePhone": "0123456789"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "johndoe"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "jillsnow"
    }
  ]
}'

 

The description of the body parameters is as follows:

 

When 'Conditional' is indicated for a Body Parameter, refer to Description for further details. 

 

Body Parameter Name Mandatory Type Example Applicable Values Description
ibxLocation Yes object    

IBX location information consists of cages information and IBX. 

ibx Yes string DC3   The IBX location code. 
cages Yes array[objects]    

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

 

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

cage Yes string DC3:01:005000  

ID of the cage.

accountNumber Yes string 2983  

The customer account number that is linked to the cage.

customerReferenceNumber No string ISO082019-101  

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

 

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

 

This field can only be up to 50 characters long. 

purchaseOrder No object    

Purchase order (PO) information details. 

 

This is mandatory for PO bearing accounts. 

 

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

purchaseOrderType Conditional string EXEMPTED

EXEMPTED,

EXISTING

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

 

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

 

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

 

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

 

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

 

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

 

This is mandatory for PO bearing accounts. 

number Conditional string    

Blanket purchase order number. This is free text input.

 

This field can only be up to 20 characters long.

 

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

 

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

attachment No object     

An object containing the attachment details of the Purchase Order Exemption Form.

 

Use the document below as a template for your Purchase Order Exemption Form.

 

Download Purchase Order Exemption Form Template.

 

The attachment, not exceeding 5MB, can be provided in the following formats: bmp, jpg, jpeg, gif, png, tif, tiff, txt, doc, docx, xls, xlsx, ppt, pps, ppsx, pdf, and vsd.

 

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

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

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

 

This is mandatory when an attachment is included.

 

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

name Conditional string PurchaseOrderExemptionForm123.docx  

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

 

This is mandatory when an attachment is included. 

 

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

serviceDetails Yes object  

 

Service details consist of the estimated date and time of inbound shipment, and shipment details information. Additional information such as additional Smart Hands request for Equinix to deliver the packages to the cage, and additional details are also included. 

estimatedDateTime Yes string 2019-08-23T00:00:30.610Z

 

Estimated shipment time. Dock hours are from 07:00 to 17:00.

 

Additional fees may be applied for deliveries during non-business hours (after hours or weekend deliveries) and require prior approval and will be billed to your account as an Equinix Smart Hands fee.

 

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

 

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

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

shipmentDetails Yes object  

 

Shipment details information consists of tracking numbers, type of inbound shipment, total number of boxes in the shipment, size of box, and name of the carrier.

inboundType

Yes

string

CARRIER,

 

CUSTOMER_CARRY

CARRIER, 

CUSTOMER_CARRY

Type of inbound shipment.

 

If 'CARRIER', a carrier service is delivering the shipment. The additional parameters 'trackingNumber' and 'carrierName' must be provided.

 

If 'CUSTOMER_CARRY', a member from the customer's company will be delivering this shipment to the IBX.

carrierName Conditional string OTHER

FEDEX,
DHL,
UPS,
OTHER

The name of the carrier service.


This is mandatory when the type of inbound shipment is 'CARRIER'.

otherCarrierName No string YAMATO  

The name of the unlisted carrier service. This is free text input. 

 

This field can only be up to 50 characters long.

 

It is recommended to include this. If this is excluded, the order will be created, but there will be a delay in fulfillment. 

noOfBoxes Yes integer 2   Total number of boxes that the IBX should expect to receive in the shipment.

Maximum number of boxes allowed is 10000000000000000000. 
isOverSized No boolean true

true, 

false

Indicates if the shipment is oversized. 

 

As shipment size allowance varies by IBX, contact the receiving IBX for their acceptable shipment sizes.

 

If 'true', shipment is oversized.

 

If 'false', shipment is normal-sized. 

 

Default value: true

trackingNumber Conditional array[strings] t1Z294AK92654678989,
t1Z086DK96424456780
 

Tracking number(s). This is free text input.

 

At least one tracking number must be included when a carrier service is delivering the shipment.

Multiple tracking numbers should be comma-separated.

 

The maximum number of characters allowed per tracking number is 100, and the maximum number of tracking numbers that can be included is 10.

 

This is mandatory when the type of inbound shipment is 'CARRIER'.

deliverToCage No boolean true

true, 

false

A Smart Hands request for Equinix to deliver the shipment to the customer cage or suite.

 

If 'true', shipment will be delivered to customer cage by Equinix. Smart Hands fees will apply.

 

Additional Smart Hands fees may be applied to your account at your contracted rate after the package delivery has been completed. There is no need to create a separate Smart Hands order.

 

If 'false', the customer will pick up the shipment from the IBX shipping dock. Shipments must be picked up within 5 days of delivery. After 5 days, if all attempts to contact the customer results in no response, further action will be taken. Refer to Global IBX Policies for additional details.

 

Default value: false

inboundRequestDescription No string Place all boxes upright with labels facing upwards.  

Additional shipment work details from the customer. This is free text input.

 

This field can only be up to 4000 characters long. 

attachments No array[objects]    

An array containing the attachment details.

 

Up to 5 attachments, each not exceeding 5MB, can be provided in the following formats: bmp, jpg, jpeg, gif, png, tif, tiff, txt, doc, docx, xls, xlsx, ppt, pps, ppsx, pdf, and vsd.

 

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

id Conditional string

fcb2k8763-2947-456e-

8d68-f280753d60ba

 

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

 

This is mandatory when an attachment is included.

 

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

name Conditional string AdditionalShipmentWorkDetails.docx  

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

 

This is mandatory when an attachment is included.

 

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

contacts Yes array[objects]    

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

contactType Yes string

ORDERING

ORDERING, 

TECHNICAL, 
NOTIFICATION

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

 

Mandatory contacts

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

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

 

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

 

Additional contacts

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

- Notification contact person(s)

userName Yes string johndoe
      
 

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

 

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

 

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

 

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

name Conditional string Jane Smith    

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

 

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

email Conditional string janesmith@corporation.com  

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

 

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

workPhoneCountryCode No string +1
      
 

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

 

E.g.: +571

 

This is mandatory for the Technical contact.

workPhone Conditional string 0148211111  

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

 

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

workPhonePrefToCall Yes string MY_BUSINESS_HOURS

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

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

 

This is mandatory for the Technical contact.

 

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

workPhoneTimeZone Conditional string Pacific/Honolulu Click here for applicable values

This indicates the specific timezone of the Technical contact's business hours that follows a 'Region/City' format.

 

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

mobilePhoneCountryCode No string  +1  

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

 

Example: +571, +1

mobilePhone No string 0123456789  

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

mobilePhonePrefToCall No string ANYTIME

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

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

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'mobilePhoneTimeZone' is mandatory. Refer to 'workPhoneTimeZone' body parameter for the same applicable values. 

mobilePhoneTimeZone Conditional string   Click here for applicable values

This indicates the specific timezone of the Technical contact's business hours that follows a 'Region/City' format.

 

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

 

{
  "OrderNumber": "1-190400381600"
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
OrderNumber string 1-190400381600

The order number created after order is submitted. 

 

You will need to submit this number when requesting for Smart Hands Shipment Unpack.

 

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

Schedule outbound shipment

Step 1: Authenticate

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

 

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

 

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

Step 2: Get Shipment Details

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

 

Get Location Information

Retrieve your IBX location information.

 

Use this API to get all available IBX location information such as the ibx location code, cage ID, and cage account number.

 

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

Step 3: Schedule Outbound Shipment

POST /shipment/outbound

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

 ibxLocation {ibx, cages [{cage, accountNumber}]}, customerReferenceNumber, purchaseOrder {purchaseOrderType, attachment {id, name}}, serviceDetails {estimatedDateTime, shipmentDetails {outboundType, noOfBoxes, declaredValue, carrierName, otherCarrierName, trackingNumber, description, insureShipment, pickUpFromCageSuite, labelExists, uploadedLabel {id, name}, shipToAddress {carrierAccountNumber, name, address, state, city, country, zipCode, phoneNumber}, outboundRequestDescription, attachments [{id, name}], contacts [{contactType, userName},{contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}, {contactType, userName}]

 

The Post shipment outbound API creates an outbound shipment order. This can only be done under a user with 'Shipments' permission. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

 

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The requests indicates four scenarios: 

 

(A) An outbound shipment by the customer without additional information,  attachment, or contacts, but with added Smart Hands fee (delivery after business hours)

 

(B) An outbound shipment by the customer with added additional information,  attachment, contacts, and Smart Hands fee (delivery after business hours)

 

(C) An outbound shipment by a carrier without a shipment label, additional information, attachment, contacts, or Smart Hands request, but with added Smart Hands fee (delivery after business hours)

 

(D) An outbound shipment by a carrier with a shipment label, additional information, attachment, contacts, Smart Hands request, and added Smart Hands fee (delivery after business hours)

 

The response indicates that the order was successful and returns order information that includes the order number.

 

(A) An outbound shipment by the customer without additional information,  attachment, or contacts, but with added Smart Hands fee (shipment after business hours)

 

curl -X

POST "https://api.equinix.com/v1/orders/shipment/outbound"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

    "ibxLocation": {

    "ibx": "DC3",
    "cages": [
      {
        "cage": "DC3:01:005000",
        "accountNumber": "2983"
      }
    ]
  },
  "serviceDetails": {
    "estimatedDateTime": "2019-08-23T00:00:30.610Z",
    "shipmentDetails": {
      "outboundType": "CUSTOMER_CARRY"
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "JaneSmith123"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "JaneSmith123"
    }

  ]
}'

 

(B) An outbound shipment by the customer with added additional information, attachment, contacts, and Smart Hands fee (shipment after business hours)

 

Before creating an order with attachment, call the Post Attachment File to attach a file.

 

curl -X

POST "https://api.equinix.com/v1/orders/shipment/outbound"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "DC3",
    "cages": [
      {
        "cage": "DC3:01:005000",
        "accountNumber": "2983"
      }
    ]
  },
  "customerReferenceNumber": "ISO082019-101",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "serviceDetails": {
    "estimatedDateTime": "2019-08-23T00:00:30.610Z",
    "shipmentDetails": {
      "outboundType": "CUSTOMER_CARRY"
    },
    "outboundRequestDescription": "See attachment for further details."
  },
  "attachments": [
    {
      "id": "f49891fc-d9a5-4b4b-bc65-150b1c5e6dff",
      "name": "AdditionalShipmentWorkDetails.docx "
    }
  ],
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "JaneSmith123"
    },
    {
      "contactType": "TECHNICAL",
      "name": "John Doe",
      "email": "johndoe@corporation.com",
      "workPhoneCountryCode": "+1",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Pacific/Honolulu",
      "mobilePhoneCountryCode": "+1",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "JaneSmith123"
    }
  ]
}'

 

(C) An outbound shipment by a carrier without a shipment label, additional information, attachment, contacts, or Smart Hands request, but with added Smart Hands fee (delivery after business hours)

 

curl -X

POST "https://api.equinix.com/v1/orders/shipment/outbound"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "DC3",
    "cages": [
      {
        "cage": "DC3:01:005000",
        "accountNumber": "2983"
      }
    ]
  },
  "serviceDetails": {
    "estimatedDateTime": "2019-08-23T00:00:30.610Z",
    "shipmentDetails": {
      "outboundType": "CARRIER",
      "noOfBoxes": 1,
      "declaredValue": "JPY1000000",
      "carrierName": "OTHER",
      "otherCarrierName": "YAMATO TRANSPORT",
      "trackingNumber": "1200-1111-1111",
      "description": "Fragile. Handle with care. Always place upright.",
      "insureShipment": true,
      "pickUpFromCageSuite": true,
      "labelExists": false,
      "shipToAddress": {
        "carrierAccountNumber": "90123-4567-890",
        "name": "John Doe Corp. Attn: Jane Smith, IT Dept.",
        "address": "1-2-3 Ginza",
        "state": "Tokyo",
        "city": "Chuo-ku",
        "country": "Japan",
        "zipCode": "123-9876",
        "phoneNumber": "+81-3-1234567890"
      }
    }
  },
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "JaneSmith123"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "JaneSmith123"
    }
  ]
}'

 

(D) Outbound shipment by a carrier with a shipment label and with additional Smart Hands requests, attachments, information, contacts

 

Before creating an order with attachment, call the Post Attachment File to attach a file.

 

curl -X

GET "https://api.equinix.com/v1/orders/shipment/outbound"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "ibxLocation": {
    "ibx": "DC3",
    "cages": [
      {
        "cage": "DC3:01:005000",
        "accountNumber": "2983"
      }
    ]
  },
  "customerReferenceNumber": "ISO082019-101",
  "purchaseOrder": {
    "purchaseOrderType": "EXEMPTED",
    "attachment": {
      "id": "abc1fd2e-345f-67g4-hi89-01jk234l5m6n",
      "name": "PurchaseOrderExemptionForm123.docx"
    }
  },
  "serviceDetails": {
    "estimatedDateTime": "2019-08-23T00:00:30.610Z",
    "shipmentDetails": {
      "outboundType": "CARRIER",
      "noOfBoxes": 1,
      "declaredValue": "JPY1000000",
      "carrierName": "OTHER",
      "otherCarrierName": "YAMATO TRANSPORT",
      "trackingNumber": "1200-1111-1111",
      "description": "Fragile. Handle with care. Always place upright.",
      "insureShipment": true,
      "pickUpFromCageSuite": true,
      "labelExists": true,
      "uploadedLabel": {
        "id": "86abc267-0c58-4173-94e9-49069977d9b5",
        "name": "ShipmentLabel.docx"
      }
    },
    "outboundRequestDescription": "See attachment for further details."
  },
  "attachments": [
    {
      "id": "f49891fc-d9a5-4b4b-bc65-150b1c5e6dff",
      "name": "AdditionalShipmentWorkDetails.docx "
    }
  ],
  "contacts": [
    {
      "contactType": "ORDERING",
      "userName": "JaneSmith123"
    },
    {
      "contactType": "TECHNICAL",
      "name": "John Doe",
      "email": "johndoe@corporation.com",
      "workPhoneCountryCode": "+1",
      "workPhone": "0148211111",
      "workPhonePrefToCall": "MY_BUSINESS_HOURS",
      "workPhoneTimeZone": "Pacific/Honolulu",
      "mobilePhoneCountryCode": "+1",
      "mobilePhone": "0123456789",
      "mobilePhonePrefToCall": "ANYTIME"
    },
    {
      "contactType": "NOTIFICATION",
      "userName": "JaneSmith123"
    }
  ]
}'

 

The description of the body parameters is as follows:

 

When 'Conditional' is indicated for a Body Parameter, refer to Description for further details. 

 

Body Parameter Name Mandatory Type Example Applicable Values Description
ibxLocation Yes object    

IBX location information consists of the cages information and IBX. 

ibx Yes string DC3   The IBX location code. 
cages Yes array[objects]    

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

 

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

cage Yes string DC3:01:005000  

ID of the cage.

accountNumber Yes string 2983  

The customer account number that is linked to the cage.

customerReferenceNumber No string ISO082019-101  

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

 

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

 

This field can only be up to 50 characters long. 

purchaseOrder No object    

Purchase order (PO) information details. 

 

This is mandatory for PO bearing accounts. 

 

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

purchaseOrderType Conditional string EXEMPTED

EXEMPTED,

EXISTING

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

 

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

 

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

 

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

 

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

 

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

 

This is mandatory for PO bearing accounts. 

number Conditional string    

Blanket purchase order number. This is free text input.

 

This field can only be up to 20 characters long.

 

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

 

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

attachment No object    

An object containing the attachment details of the Purchase Order Exemption Form.

 

Use the document below as a template for your Purchase Order Exemption Form.

 

Download Purchase Order Exemption Form Template.

 

The attachment, not exceeding 5MB, can be provided in the following formats: bmp, jpg, jpeg, gif, png, tif, tiff, txt, doc, docx, xls, xlsx, ppt, pps, ppsx, pdf, and vsd.

 

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

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

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

 

This is mandatory when an attachment is included.

 

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

name Conditional string PurchaseOrderExemptionForm123.docx  

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

 

This is mandatory when an attachment is included.

 

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

serviceDetails Yes object  

 

Service details consist of the estimated date and time of inbound shipment, and shipment details information. Additional information such as additional Smart Hands request for Equinix to deliver the packages to the cage, and additional details are also included. 

estimatedDateTime Yes string 2019-08-23T00:00:30.610Z

 

Estimated shipment time. Dock hours are from 07:00 to 17:00. 


The selected departure date and time should be more than 24 hours from now.

 

Additional fees may be applied for deliveries during non-business hours (after hours or weekend deliveries) and require prior approval and will be billed to your account as an Equinix Smart Hands fee.

 

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

 

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

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

shipmentDetails Yes object      Shipment details information consist of the type of outbound shipment, the number of boxes, the declared shipment value, carrier name, carrier tracking number, shipment description, Smart Hands request to insure shipment, Smart Hands request to pick up cage from suite, shipping address information, shipping label attachment, and any additional shipping request description.
outboundType Yes string CUSTOMER_CARRY

CARRIER, 

CUSTOMER_CARRY

Type of outbound shipment.

 

If 'CUSTOMER_CARRY',  a member of your company will be picking up your outbound shipment and taking it out of the IBX.

 

If 'CARRIER', a carrier service is picking up your outbound shipment. 

 

For international shipments, all customs paperwork must be provided.

 

Equinix will not act as the importer of goods and is not responsible for working with local customs.

noOfBoxes Conditional integer 1  

Total number of boxes that are outbound.

 

Minimum number of boxes allowed is 1. 
Maximum number of boxes allowed is 99999.

 

This is mandatory when the type of outbound shipment is 'CARRIER'.

declaredValue Conditional string JPY1000000

 

The declared shipment value. This is free text input.

 

This field can only be up to 20 characters long.

 

This is mandatory when the type of outbound shipment is 'CARRIER'.

carrierName Conditional string OTHER

DHL,

FEDEX,
UPS,
OTHER

The name of the carrier service. 

 

This is mandatory when the type of outbound shipment is 'CARRIER'.

otherCarrierName Conditional string YAMATO TRANSPORT  

The name of the 'Other' carrier service. This is free text input.

 

This field can only be up to 50 characters long. 

 

This is mandatory when the type of outbound shipment is 'CARRIER' and the carrier name is 'OTHER'.

trackingNumber Conditional string 1200-1111-1111  

Tracking number. This is free text input.

 

This field can only be up to 100 characters long. 

 

This is mandatory when the type of outbound shipment is 'CARRIER'.

description No string Fragile. Handle with care. Always place upright.

 

This is an optional description about the shipment that you may include. This is free text input.

 

This field can only be up to 100 characters long. 

insureShipment No boolean true

true, 

false

A Smart Hands request to insure the shipment. 

 

If 'true', Equinix will provide insurance for the shipment. Smart Hands fees will apply.

 

Additional Smart Hands fees may be applied to your account at your contracted rate after the insurance service has been completed. There is no need to create a separate Smart Hands order.

 

If 'false', insurance is not required.

 

Default value: false

pickUpFromCageSuite No boolean true

true, 

false

A Smart Hands request to pick up boxes from cage or suite. 

 

If 'true', Equinix will pick up boxes from cage or suite to be shipped out. Smart Hands fees will apply.

 

Additional Smart Hands fees may be applied to your account at your contracted rate after the package pick up has been completed. There is no need to create a separate Smart Hands order.

 

If 'false', boxes do not need to be picked up from cage or suite.

 

Default value: false

labelExists Yes boolean true

true, 

false

This indicates if there is a shipping label for this shipment.

 

If 'true', there is a shipping label for this shipment, and a shipping address need not be provided. The shipping label can be included as an attachment.

 

If 'false', there is no shipping label for this shipment, and "shipToAddress" must be provided.

uploadedLabel No object    

An object containing the shipping label attachment details.

 

Up to 1 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.

id Conditional string 86abc267-0c58-4173-
94e9-49069977d9b5
 

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

 

This is mandatory when an attachment is included.

 

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

name Conditional string ShipmentLabel.docx  

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

 

This is mandatory when an attachment is included.

 

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

shipToAddress Conditional object    

The destination shipping address information.

 

This is mandatory when there is no shipping label for this shipment.

carrierAccountNumber Conditional string 90123-4567-890  

The customer's account number with the carrier that should be associated with this shipment. This is free text input.

 

This field can only be up to 100 characters long. 

 

This is mandatory when there is no shipping label for this shipment.

name Conditional string John Doe Corp. Attn: Jane Smith, IT Dept.  

The full name of the addressee. This is free text input.

 

This field can only be up to 100 characters long. 

 

This is mandatory when there is no shipping label for this shipment.

address Conditional string 1-2-3 Ginza  

The destination address of the shipment. This is free text input.

 

This field can only be up to 100 characters long. 

 

This is mandatory when there is no shipping label for this shipment.

state Conditional string Tokyo  

The state of the destination address. This is free text input.

 

This field can only be up to 100 characters long. 

 

This is mandatory when there is no shipping label for this shipment.

city Conditional string Chuo-ku  

The city of the destination address. This is free text input.

 

This field can only be up to 100 characters long.

 

This is mandatory when there is no shipping label for this shipment.

country Conditional string Japan  

The country of the destination address. This is free text input.

 

This field can only be up to 100 characters long.

 

This is mandatory when there is no shipping label for this shipment.

zipCode Conditional string 123-9876  

The postal code or zipcode of the destination address. This is free text input.

 

This field can only be up to 100 characters long.

 

This is mandatory when there is no shipping label for this shipment.

phoneNumber Conditional string +81-3-1234567890  

The phone number of the addressee, which should comprise of the country code and contact number. This is free text input.

 

This field can only be up to 4000 characters long.

 

This is mandatory when there is no shipping label for this shipment.

outboundRequestDescription No string

See attachment for further details.

 

Additional shipment work details from the customer. This is free text input.

 

This field can only be up to 4000 characters long. 

attachments No array[objects]    

An array containing the attachment details.

 

Up to 5 attachments, each not exceeding 5MB, can be provided in the following formats: bmp, jpg, jpeg, gif, png, tif, tiff, txt, doc, docx, xls, xlsx, ppt, pps, ppsx, pdf, and vsd.

 

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

id Conditional string

fcb2k8763-2947-456e-

8d68-f280753d60ba

 

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

 

This is mandatory when an attachment is included.

 

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

name Conditional string AdditionalShipmentWorkDetails.docx  

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

 

This is mandatory when an attachment is included.

 

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

contacts Yes array[objects]    

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

contactType Yes string

ORDERING

ORDERING, 

TECHNICAL, 
NOTIFICATION

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

 

Mandatory contacts

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

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

 

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

 

Additional contacts

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

- Notification contact person(s)

userName Yes string JaneSmith123
      
 

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

 

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

 

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

 

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

name Conditional string John Doe    

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 johndoe@corporation.com  

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

 

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

workPhoneCountryCode No string +1
      
 

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

 

E.g.: +571

 

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 MY_BUSINESS_HOURS

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

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

 

This is mandatory for the Technical contact.

 

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

workPhoneTimeZone Conditional string Pacific/Honolulu Click here for applicable values

This indicates the specific timezone of the Technical contact's business hours that follows a 'Region/City' format.

 

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

mobilePhoneCountryCode No string  +1  

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

 

Example: +571, +1

mobilePhone No string 0123456789  

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

mobilePhonePrefToCall No string ANYTIME

NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

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

 

If 'MY_BUSINESS_HOURS', the additional body parameter 'mobilePhoneTimeZone' is mandatory. Refer to 'workPhoneTimeZone' body parameter for the same applicable values. 

mobilePhoneTimeZone Conditional string   Click here for applicable values

This indicates the specific timezone of the Technical contact's business hours that follows a 'Region/City' format.

 

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

 

{
  "OrderNumber": "1-190400381600"
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
OrderNumber string 1-190400381600

The order number created after order is submitted. 

 

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