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.

Schedule inbound shipment (V2)

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: Get Shipment Details

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

Get Location Information
Retrieve all your permitted location information.

Determine the exact cage ID and account number for your shipment.

These values will be passed in the request body in Step 4 for the following parameters: cageId, accountNumber.

Refer to GET Locations under the API Reference section for instructions on how to get your permitted location information. You may skip this step if you already know this information.

Step 3: Get Contact Information

If you are the only technical and notification contact for this order, skip this step and proceed to Step 4.

3a) Identify usernames
Identify the usernames you want to include as technical and notification contacts for this shipment.

To verify if the username belongs to your intended user, proceed to Step 3b.

When you are certain this is the correct username, proceed to Step 4, where this value will be passed in the request body for the following parameter in the contacts array: registeredUsers.

Refer to GET Users under the API Reference section for instructions on how to get all your users. You may skip this step if you know this username.

3b) Verify usernames
Ensure the user profile details match the details of your intended user.

Refer to GET Users {username} under the API Reference section for instructions on how to get your user profile. You may skip this step if you are certain this is the intended user.

Step 4: Schedule Inbound Shipment

POST /orders/shipments
Method POST
URL or End Point /colocations/v2/orders/shipments
Headers Authorization, Content-Type
Query Parameters Not applicable
Body type, requestedDateTime, cageId, accountNumber, details { carrier, carrierName, numberOfBoxes, carrierTrackingNumbers [...], cageDelivery}, description, attachments [{ id, name}], customerReferenceId, purchaseOrder { type, number, amount, startDate, endDate, attachmentId}, contacts [{ type. registeredUsers [...]}, { type, firstName, lastName, availability, timezone, details [{ type, value}]}]

This method creates either an inbound or outbound shipment order, but the use cases illustrated here are only applicable to inbound shipments. Only an authenticated user with Shipments ordering permission can schedule shipments. 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 would like to schedule an outbound shipment instead, refer to Schedule outbound shipment (V2) under the Getting Started section.

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

An inbound shipment request minimally requires the shipment type, shipment date, associated cage, carrier, and number of boxes to be included. The other necessary information you need to pass in the inbound shipment request body depends on the following:

  • If your inbound shipment is from a cage linked to multiple accounts.
  • If the carrier delivering the shipment is from your organization, a listed carrier or an unlisted carrier. If your carrier is not DHL, FedEx, UPS, your carrier is unlisted.

The following screenshots show sample curl requests for these different scenarios:

(A) An inbound shipment from a cage associated with a single account that will be delivered by someone from your organization. Only the minimum required body parameters are passed in this sample request payload.

(B) An inbound shipment from a cage associated with a single account that will be delivered by a listed carrier. Only the minimum required body parameters are passed in this sample request payload.

(C) An inbound shipment from a cage associated with multiple accounts that will be delivered by an unlisted carrier. Only the minimum required body parameters are passed in this sample request payload.

(D) An inbound shipment from a cage associated with multiple accounts that will be delivered by an unlisted carrier. All the other available and applicable body parameters are passed in this sample request payload.

(A) An inbound shipment from a cage associated with a single account that will be delivered by your organization (minimum required information)
For this scenario, your inbound shipment is delivered to your cage linked to only one account by someone from your organization. The minimum required information for this scenario is passed in this sample request.

Copy 
curl -X
POST "https://api.equinix.com/colocations/v2/orders/shipments"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
    "type": "INBOUND",
    "requestedDateTime": "2020-11-02T10:45:41Z",
    "cageId": "AM1:01:000111",
    "details": {
    "carrier": "CUSTOMER_CARRIER",
    "numberOfBoxes": 2
    }
}'

(B) An inbound shipment from a cage associated with a single account that will be delivered by a listed carrier (minimum required information)
In this scenario, your inbound shipment is delivered to your cage linked to only one account by a listed carrier. The minimum required information for this scenario is passed in this sample request.

Copy 
curl -X
POST "https://api.equinix.com/colocations/v2/orders/shipments"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
    "type": "INBOUND",
    "requestedDateTime": "2020-11-02T10:45:41Z",
    "cageId": "AM1:01:000111",
    "details": {
    "carrier": "DHL",
    "numberOfBoxes": 2,
    "carrierTrackingNumbers": [
        "t1Z294AK92654678989",
        "t1Z086DK96424456780"
    ]
    }
}'

(C An inbound shipment from a cage associated with multiple accounts that will be delivered by an unlisted carrier (minimum required information)
For this scenario, your inbound shipment is delivered to your cage linked to multiple accounts by an unlisted carrier. You will need to specify the account number for this shipment and the unlisted carrier's name.

Copy 
curl -X
POST "https://api.equinix.com/colocations/v2/orders/shipments"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
    "type": "INBOUND",
    "requestedDateTime": "2020-11-02T10:45:41Z",
    "cageId": "AM1:01:000111",
    "accountNumber": 901011,
    "details": {
    "carrier": "OTHER",
    "carrierName": "New Carrier",
    "numberOfBoxes": 2,
    "carrierTrackingNumbers": [
        "t1Z294AK92654678989",
        "t1Z086DK96424456780"
    ]
    }
}'

(D) An inbound shipment from a cage associated with multiple accounts that will be delivered by an unlisted carrier. Additional Smart Hands requests, information, contact details, and attachments are also included.
In this scenario, you have provided the minimum required information to facilitate an inbound shipment, and included additional body parameters which support the following:

  • additional Smart Hands request to deliver the shipment to your cage
  • additional description
  • supporting attachments
  • your own reference identifier
  • purchase order information
  • contact information for notification or technical contact persons

All available and applicable body parameters are passed in this sample request.

Before creating an order with attachment, call the POST Attachments File to attach a file.

Copy 
curl -X
POST "https://api.equinix.com/colocations/v2/orders/shipments"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
    "type": "INBOUND",
    "requestedDateTime": "2020-11-02T10:45:41Z",
    "cageId": "AM1:01:000111",
    "accountNumber": 901011,
    "details": {
        "carrier": "OTHER",
        "carrierName": "New Carrier",
        "numberOfBoxes": 2,
        "carrierTrackingNumbers": [
            "t1Z294AK92654678989",
            "t1Z086DK96424456780"
        ],
        "cageDelivery": true
    },
    "description": "Package is fragile and heavy. Handle with care. Additional description in attachment.",
    "attachments": [
        {
            "id": "85d9660a-f877-405a-b38e-8e61a4f77f44",
            "name": "OrderInstructions.docx"
        }
    ], 
    "customerReferenceId": "2020/16347",
        "purchaseOrder": {
        "type": "NEW",
        "number": "9654284",
        "amount": "10000",
        "startDate": "2020-10-01",
        "endDate": "2021-09-30",
        "attachmentId": "56d10de6-f2c0-4edd-ba29-b70736aa2093"
    },
    "contacts": [
    {
        "type": "NOTIFICATION",
        "registeredUsers": [
            "john_doe1",
            "jane_smith1"
        ]
    },
    {
        "type": "TECHNICAL",
        "firstName": "John",
        "lastName": "Doe",
        "availability": "WORK_HOURS",
        "timezone": "America/Los_Angeles",
        "details": [
            {
                "type": "EMAIL",
                "value": "johndoe@acme.com""
            },
            {
                "type": "PHONE",
                "value": "+1-987654321"
            },
            {
                "type": "MOBILE",
                "value": "+1-912345678"
            }
        ]
    }
  ]
}'

The description of the body parameters is as follows:

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

Body Parameter Name Mandatory Type Example Applicable Values Description
type Yes string INBOUND INBOUND,
OUTBOUND		 Type of shipment to be scheduled. This can be an incoming shipment to Equinix, or an outgoing shipment from Equinix.
requestedDateTime Yes string 2020-11-02T10:45:44Z Requested shipment date and time. Dock hours are from 07:00 to 17:00. The selected 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) require prior approval and will be billed to your account as an Equinix Smart Hands fee.

Provide a date and time (UTC time zone) in the following ISO 8601 format: yyyy-MM-dd'T'HH:mm:ssZ

cageId Yes string AM1:01:000111 ID of the cage that is associated with this shipment.
accountNumber Conditional string 901011 The customer account number that is linked to the cage. This is mandatory when the cage is linked to multiple accounts.
details Yes object Inbound shipment details. This inbound shipment object comprises the following parameters where applicable: numberOfBoxes, boxType, carrier, carrierName, carrierTrackingNumbers, cageDelivery.
carrier Yes string CUSTOMER_CARRIER CUSTOMER_CARRIER,
DHL,
FEDEX,
OTHER,
UPS

The name of the carrier service.

When your carrier is someone from your organization, select CUSTOMER_CARRIER.

When your carrier is not listed, select OTHER and provide the name of your carrier in the parameter 'carrierName'.
carrierName Conditional string New Carrier

The name of the unlisted carrier service. This is mandatory when your carrier is OTHERS.

This is free text input.

Limit: 1 to 50 characters.
numberOfBoxes Yes number 2

Total number of boxes in this shipment.

Limit: 1 to 100.
carrierTrackingNumbers Conditional array [strings] t1Z294AK92654678989, t1Z086DK96424456780

Tracking number(s). At least one tracking number must be included when a carrier service is delivering the shipment. Multiple tracking numbers should be comma-separated. This is mandatory when your carrier is not CUSTOMER_CARRIER.

This is free text input.

Limit per tracking number: 1 to 100 characters.

Limit: 1 to 10 tracking numbers.
cageDelivery No boolean true true, false

A Smart Hands request for Equinix to deliver the shipment to your 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
description No string Package is fragile and heavy. Handle with care. Additional description in attachment.

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

Limit: 10 to 4000 characters.
attachments No array [objects]

Attachments array comprising object(s) with attachment details. Each attachment object must contain the following parameters: id, name.

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.

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

id Conditional string 85d9660a-f877-405a-b38e-8e61a4f77f44

Attachment id. This is mandatory when an attachment is included.

You will obtain this value after attaching your file using the POST Attachments File API.

Limit: 36 characters.
name Conditional string OrderInstructions.docx

Name of the attachment. This is mandatory when an attachment is included.

You will obtain this value after using the POST Attachments File API, but you can change the name for your own reference when including this attachment in any order request.

This is free text input.

Limit: 5 to 100 characters.
customerReferenceId No string 2020/16347

Customer's own reference ID. This information can be searched for in Order History and will appear within Reports.

This is free text input.

Limit: 1 to 40 characters
purchaseOrder Conditional object

Purchase order (PO) information you want to associate with this order. This is mandatory when your account is PO bearing.

This object comprises the following parameters where applicable: type, number, amount, startDate, endDate, attachmentId.
type Conditional string NEW EXEMPTED,
EXISTING,
NEW

Purchase order type can be categorized as exempted, existing, or new. This is mandatory when including purchase order information.

Type - Description
EXEMPTED - You are exempted from: a) including a purchase order in your request, or b) you are applying for exemption to include a purchase order in your request. If b), see body parameter 'attachmentId'.
EXISTING - You would like to use an existing blanket purchase order for this order. Body parameter 'number' is mandatory with this.
NEW - You would like to use a new blanket purchase order which has not yet been applied for any order. Body parameter 'number' is mandatory with this. You can also include the following parameters: amount, startDate, endDate, attachmentId.

Default value: EXEMPTED
number Conditional string 9654284

Purchase order number to associate with this order. This is mandatory when purchase order type is existing or new.

For existing purchase orders, if the blanket purchase order number submitted throws an error, select 'EXEMPTED' for purchase order type instead.

See GET PurchaseOrders under the API Reference section to retrieve your applicable blanket purchase order number.

amount No number 10000 Total value amount of the new purchase order. This is only applicable when purchase order type is new.
startDate No string 2020-10-01

Starting date of the new purchase order. This is only applicable when purchase order type is new.

Format: yyyy-MM-dd
endDate No string 2021-09-30

End date of the new purchase order. This is only applicable when purchase order type is new.

Format: yyyy-MM-dd
attachmentId No string 56d10de6-f2c0-4edd-ba29-b70736aa2093

Attachment ID. You can attach a new purchase order document, or the Purchase Order Exemption Form.

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

Download Purchase Order Exemption Form Template.

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

Limit: 36 characters.

This should be included when your purchase order type is new and you would like to attach the new blanket purchase order, or your purchase order type is exempted and you are submitting a Purchase Order Exemption form.

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

contacts No array [objects]

Contacts array consists of the technical contact and notification contact(s) information. Equinix will be able to communicate with these contacts based on their information provided. When any of the contacts are not provided, they default to the authenticated user who submitted this order (ordering contact).

Technical contact is the person who Equinix can reach out to for technical clarifications. Only one technical contact can be passed.

  • If they are a registered Equinix Customer Portal user, only their username needs to be passed. All their contact details will be referred from their user profile in the Equinix Customer Portal. Their work hours time zone will also be referred from the user profile, unless otherwise included in this request.
  • If they are a non-registered contact, their full name (first and last names) and contact details must be provided. To include more information such as the technical contact's availability or time zone, see parameter 'details'.

Notification contact is the person who will be notified of status updates. At least one notification contact must be provided.

  • They must be a registered Equinix Customer Portal user. Only their username needs to be passed.
  • N/A for a non-registered contact.

When providing the contact information for:

  • Registered contact object, the following body parameters are mandatory: registeredUsers, type. All other attributes passed in a registered contact object will be ignored.
  • Non-registered contact object, the following body parameters are mandatory: firstName, lastName, type, details.

For more information on technical contact's work hours time zone, see description of body parameter, 'timezone'.
type Conditional string NOTIFICATION NOTIFICATION,
TECHNICAL

Defines the contact type. This is mandatory for the registered and non-registered contacts.

Type - Description
TECHNICAL - Technical contact (applies to both registered and non-registered contacts).
NOTIFICATION - Notification contact (applies to registered contact only).
registeredUsers Conditional array [strings] john_doe1,
jane_smith1		 Equinix Customer Portal username of the registered user. This is mandatory for a registered contact.

Equinix Customer Portal user's status must be approved, active, or locked. If the user's status is not any of these, the request will fail. Refer to GET Users for more information.

Limit for technical contact: 1 string.

Limit for notification contact(s): 1 to 10 strings.
firstName Conditional string John

First name of the non-registered Technical contact. This is mandatory for a non-registered Technical contact.

This is free text input.
lastName Conditional string Doe

Last name of the non-registered Technical contact. This is mandatory for a non-registered Technical contact.

This is free text input.
availability Conditional string WORK_HOURS ANYTIME, WORK_HOURS

Defines the technical contact's availability to be contacted.

Availability - Description
ANYTIME - Technical contact is available 24/7.
WORK_HOURS - Technical contact is only available during work hours in their time zone. For a registered technical contact, their work hours is defaulted to the time zone in their user profile. If they would like to provide a different time zone, they should provide it in the body parameter 'timezone'. For a non-registered technical contact, if they select their work hours, the parameter 'timezone' is mandatory.

Default value: ANYTIME
timezone Conditional string America/Los_Angeles Click here for applicable values

Defines the time zone of the technical contact's work hours. This is mandatory when the non-registered technical contact selects their work hours as their availability.

For a registered technical contact, the time zone provided here will override the time zone in the user profile only for this order request, and does not replace the time zone in their user profile.

For example, selecting 'America/Los_Angeles' specifies the technical contact's work hours.
details Conditional array [objects]

Array of contact details for the non-registered technical contact consisting of the type of contact detail and its value. It is mandatory to provide two types of contacts:

  • always email address and
  • at least one type of number, either phone or mobile.

Limit: 2 to 3 objects.
type Conditional string EMAIL EMAIL,
MOBILE,
PHONE

Defines the contact detail type.

Type - Description
EMAIL - Email address.
MOBILE - Mobile phone number. This is the secondary contact number.
PHONE - Phone number. This is the primary contact number.
value Conditional string johndoe@acme.com

Value of the contact detail type.

Phone numbers must be prefixed by '+' country code.
For example, +1-987-654-3210 or +1 987 654 3210.

Email addresses must follow a valid email format.

Order is successfully created when an HTTP code of 201 is returned and the following response header is returned. There is no response body.

HTTP Response Header Name Description
Location

Location of the newly created order.

Example: /orders/{orderId}

'orderId' is the order identifier. This is important if you want to update, add notes to, retrieve and reply negotiations for, or cancel the order. It is also known as the order number in the Equinix Customer Portal.

If you would like to update this order, see Shipments (V2) in the API Reference section for more information.

If you would like to add notes to this order, retrieve and reply negotiations for this order, or cancel this order, see Orders (V2 Beta) in the API Reference Section for more information.

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

Schedule outbound shipment (V2)

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: Get Shipment Details

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

Get Location Information
Retrieve all your permitted location information.

Determine the exact cage ID and account number for your shipment.

These values will be passed in the request body in Step 4 for the following parameters: cageId, accountNumber.

Refer to GET Locations under the API Reference section for instructions on how to get your permitted location information. You may skip this step if you already know this information.

Step 3: Get Contact Information

If you are the only technical and notification contact for this order, skip this step and proceed to Step 4.

3a) Identify usernames
Identify the usernames you want to include as technical and notification contacts for this shipment.

To verify if the username belongs to your intended user, proceed to Step 3b.

When you are certain this is the correct username, proceed to Step 4, where this value will be passed in the request body for the following parameter in the contacts array: registeredUsers.

Refer to GET Users under the API Reference section for instructions on how to get all your users. You may skip this step if you know this username.

3b) Verify usernames
Ensure the user profile details match the details of your intended user.

Refer to GET Users {username} under the API Reference section for instructions on how to get your user profile. You may skip this step if you are certain this is the intended user.

Step 4: Schedule Outbound Shipment

POST /orders/shipments
Method POST
URL or End Point /colocations/v2/orders/shipments
Headers Authorization, Content-Type
Query Parameters Not applicable
Body type, requestedDateTime, cageId, accountNumber, details { carrier, carrierName, numberOfBoxes, declaredValue, declaredValueCurrency, carrierTrackingNumbers [...], shipmentLabelRequired, shipmentAddress { carrierAccountNumber, shipToName, addressLine1, addressLine2, city, state, countryCode, zipCode, phoneNumber}, shipmentAttachmentId, requirePickup, insureShipment, description, attachments [{ id, name}], customerReferenceId, purchaseOrder { type, number, amount, startDate, endDate, attachmentId}, contacts [{ type. registeredUsers [...]}, { type, firstName, lastName, availability, timezone, details [{ type, value}]}]

This method creates either an inbound or outbound shipment order, but the use cases illustrated here are only applicable to outbound shipments. Only an authenticated user with Shipments ordering permission can schedule shipments. 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 would like to schedule an inbound shipment instead, refer to Schedule inbound shipment (V2) under the Getting Started section.

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

An outbound shipment request minimally requires the shipment type, shipment date, associated cage, and carrier to be included. The other necessary information you need to pass in the outbound shipment request body depends on the following:

  • If your outbound shipment is from a cage linked to multiple accounts.
  • If the carrier delivering the shipment is from your organization, a listed carrier or an unlisted carrier. If your carrier is not DHL, FedEx, UPS, your carrier is unlisted.
  • If you require a shipping label to be printed by Equinix.

The following screenshots show sample curl requests for these different scenarios:

(A) An outbound shipment from a cage associated with a single account that will be delivered by someone from your organization. Only the minimum required body parameters are passed in this sample request payload.

(B) An outbound shipment from a cage associated with a single account that will be delivered by a listed carrier without a shipping label printed by Equinix. Only the minimum required body parameters are passed in this sample request payload.

(C) An outbound shipment from a cage associated with multiple accounts that will be delivered by an unlisted carrier, and requires Equinix to print the shipping label. The relevant shipping label details are provided within the request. Only the minimum required body parameters are passed in this sample request payload.

(D) An outbound shipment from a cage associated with multiple accounts that will be delivered by an unlisted carrier, and requires Equinix to print the shipping label. The relevant shipping label details are provided as an attachment. All the other available and applicable body parameters are passed in this sample request payload.

(A) An outbound shipment from a cage associated with a single account that will be delivered by your organization (minimum required information)
For this scenario, your outbound shipment is delivered to your cage linked to only one account by someone from your organization. The minimum required information for this scenario is passed in this sample request.

Copy 
curl -X
POST "https://api.equinix.com/colocations/v2/orders/shipments"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
    "type": "OUTBOUND",
    "requestedDateTime": "2020-11-02T10:45:41Z",
    "cageId": "AM1:01:000111",
    "details": {
    "carrier": "CUSTOMER_CARRIER"
    ]
    }
}'

(B) An outbound shipment from a cage associated with a single account that will be delivered by a listed carrier without a shipping label printed by Equinix. (minimum required information)
In this scenario, your outbound shipment is delivered from your cage linked to only one account by a listed carrier. As your outbound shipment already has its own shipment label affixed, you do not need Equinix to print a label for you.

The minimum required information for this scenario is passed in this sample request.

Copy 
curl -X
POST "https://api.equinix.com/colocations/v2/orders/shipments"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
    "type": "OUTBOUND",
    "requestedDateTime": "2020-11-02T10:45:41Z",
    "cageId": "AM1:01:000111",
    "details": {
    "carrier": "DHL",
    "numberOfBoxes": 2,
    "declaredValue": 1000,
    "carrierTrackingNumbers": [
        "t1Z294AK92654678989",
        "t1Z086DK96424456780"
    ],
    "shipmentLabelRequired": false
    }
}'

(C) An outbound shipment from a cage associated with multiple accounts that will be delivered by an unlisted carrier, and requires Equinix to print the shipping label. The relevant shipping label details are provided within the request. (minimum required information)
For this scenario, your outbound shipment is delivered from your cage linked to multiple accounts by an unlisted carrier. Therefore, you will need to specify the account number for this shipment and the unlisted carrier's name.

When you require Equinix to print a shipment label for you, you will need to include the required shipment label details either within the request or as an attachment.

For the latter, refer to Scenario D.

For the former, refer to this sample request which includes the minimum required information for this scenario.

Copy 
curl -X
POST "https://api.equinix.com/colocations/v2/orders/shipments"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
    "type": "OUTBOUND",
    "requestedDateTime": "2020-11-02T10:45:41Z",
    "cageId": "AM1:01:000111",
    "accountNumber": 901011,
    "details": {
        "carrier": "OTHER",
        "carrierName": "New Carrier",
        "numberOfBoxes": 2,
        "declaredValue": 1000,
        "carrierTrackingNumbers": [
            "t1Z294AK92654678989",
            "t1Z086DK96424456780"
        ],
        "shipmentLabelRequired": true,
        "shipmentAddress": {
            "carrierAccountNumber": "90123-4567-890",
            "shipToName": "John Doe Corp. Attn: Jane Smith, IT Dept.",
            "addressLine1": "1122 Main Street",
            "city": "New City",
            "state": "CA",
            "countryCode": "US",
            "zipCode": "12345",
            "phoneNumber": "+1 123-456-7890"
        }
    }
}'

(D) An outbound shipment from a cage associated with multiple accounts that will be delivered by an unlisted carrier, and requires Equinix to print the shipping label. The relevant shipping label details are provided as an attachment. Additional Smart Hands requests, information, contact details, and attachments are also included.
In this scenario, you have provided the minimum required information to facilitate an outbound shipment request, and included additional body parameters which support the following:

  • declared shipment value in a currency other than USD
  • additional Smart Hands requests to pick up your shipment from your cage or to insure it
  • additional description
  • supporting attachments
  • your own reference identifier
  • purchase order information
  • contact information for notification or technical contact persons

All available and applicable body parameters are passed in this sample request.

Before creating an order with attachment, call the POST Attachments File to attach a file.

Copy 
curl -X
POST "https://api.equinix.com/colocations/v2/orders/shipments"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
    "type": "OUTBOUND",
    "requestedDateTime": "2020-11-02T10:45:41Z",
    "cageId": "AM1:01:000111",
    "accountNumber": 901011,
    "details": {
    "carrier": "OTHER",
    "carrierName": "New Carrier",
    "numberOfBoxes": 2,
    "declaredValue": 1000,
    "declaredValueCurrency": "EUR",
    "carrierTrackingNumbers": [
        "t1Z294AK92654678989",
        "t1Z086DK96424456780"
    ],
        "shipmentLabelRequired": true,
        "shipmentAttachmentId": "f49891fc-d9a5-4b4b-bc65-150b1c5e6dff",
        "requirePickup": true,
        "insureShipment": true
    },
    "description": "Package is fragile and heavy. Handle with care. Additional description in attachment.",
    "attachments": [
    {
        "id": "85d9660a-f877-405a-b38e-8e61a4f77f44",
        "name": "OrderInstructions.docx"
    }
    ],
    "customerReferenceId": "2020/16347",
    "purchaseOrder": {
        "type": "NEW",
        "number": "9654284",
        "amount": "10000",
        "startDate": "2020-10-01",
        "endDate": "2021-09-30",
        "attachmentId": "56d10de6-f2c0-4edd-ba29-b70736aa2093"
    },
    "contacts": [
    {
        "type": "NOTIFICATION",
        "registeredUsers": [
            "john_doe1",
            "jane_smith1"
        ]
    },
    {
        "type": "TECHNICAL",
        "firstName": "John",
        "lastName": "Doe",
        "availability": "WORK_HOURS",
        "timezone": "America/Los_Angeles",
        "details": [
            {
                "type": "EMAIL",
                "value": "johndoe@acme.com"
            },
            {
                "type": "PHONE",
                "value": "+1-987654321"
            },
            {
                "type": "MOBILE",
                "value": "+1-912345678"
            }
        ]
    }
  ]
}'

The description of the body parameters is as follows:

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

Body Parameter Name Mandatory Type Example Applicable Values Description
type Yes string OUTBOUND INBOUND,
OUTBOUND		 Type of shipment to be scheduled. This can be an incoming shipment to Equinix, or an outgoing shipment from Equinix.

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.

requestedDateTime Yes string 2020-11-02T10:45:44Z Requested shipment date and time. Dock hours are from 07:00 to 17:00. The selected 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) require prior approval and will be billed to your account as an Equinix Smart Hands fee.

Provide a date and time (UTC time zone) in the following ISO 8601 format: yyyy-MM-dd'T'HH:mm:ssZ

cageId Yes

string

 AM1:01:000111 ID of the cage that is associated with this shipment.
accountNumber Conditional string 901011 The customer account number that is linked to the cage. This is mandatory when the cage is linked to multiple accounts.
details Yes object Outbound shipment details. This outbound shipment object comprises the following parameters where applicable: carrier, carrierName, numberOfBoxes, declaredValue, declaredValueCurrency, carrierTrackingNumbers, shipmentLabelRequired, shipmentAddress, shipmentAttachmentId, requirePickup, insureShipment.
carrier Yes string CUSTOMER_CARRIER CUSTOMER_CARRIER,
DHL,
FEDEX,
OTHER,
UPS

The name of the carrier service.

When your carrier is someone from your organization, select CUSTOMER_CARRIER.

When your carrier is not listed, select OTHER and provide the name of your carrier in the parameter carrierName.
carrierName Conditional string New Carrier

The name of the unlisted carrier service. This is mandatory when your carrier is OTHERS.

This is free text input.

Limit: 1 to 50 characters.
numberOfBoxes Conditional number 2

Total number of boxes in this shipment. This is mandatory when your carrier is not CUSTOMER_CARRIER.

Limit: 1 to 100.
declaredValue Conditional number 1000 Total declared shipment value. This is mandatory when your carrier is not CUSTOMER_CARRIER.
declaredValueCurrency No string EUR Click here for applicable values.

Associated currency of the declared shipment value.

Default value: USD.
carrierTrackingNumbers Conditional array [strings] t1Z294AK92654678989, t1Z086DK96424456780

Tracking number(s). At least one tracking number must be included when a carrier service is delivering the shipment. Multiple tracking numbers should be comma-separated. This is mandatory when your carrier is not CUSTOMER_CARRIER.

This is free text input.

Limit per tracking number: 1 to 100 characters.

Limit: 1 to 10 tracking numbers.
shipmentLabelRequired No boolean false true, false

Requirement for Equinix to print a shipping label for you. This is applicable when your carrier is not CUSTOMER_CARRIER.

If 'true', you require Equinix to print a shipping label for your shipment, so you must provide the necessary shipping label details in either of the following parameters: shipmentAddress, or shipmentAttachmentId.

If 'false', Equinix is not required to print a shipping label for you.

Default value: true
shipmentAddress Conditional object

Shipment destination address and carrier account information that are necessary for the shipping label. This is mandatory when you require an Equinix-printed shipping label, and you are not providing the required details in shipmentAttachmentId.

This object comprises the following parameters: carrierAccountNumber, shipToName, addressLine1, addressLine2, city, state, countryCode, zipCode, phoneNumber.
carrierAccountNumber Conditional string 90123-4567-890

Your selected carrier account number. This is mandatory when including shipmentAddress.

Limit: 1 to 100 characters.
shipToName Conditional string John Doe Corp. Attn: Jane Smith, IT Dept.

Shipment recipient name.This is mandatory when including shipmentAddress.

Limit: 1 to 100 characters.
addressLine1 Conditional string 1122 Main Street

Line 1 of the destination address. This is mandatory when including shipmentAddress.

Limit: 1 to 50 characters.
addressLine2 No string

Line 2 of the destination address.

Limit: 1 to 50 characters.
city Conditional string New City

City of the destination address. This is mandatory when including shipmentAddress.

Limit: 1 to 100 characters.
state Conditional string CA

State of the destination address. This is mandatory when including shipmentAddress.

Limit: 1 to 100 characters.
countryCode Conditional string US Click here for applicable values.

Country code of the destination address. This is mandatory when including shipmentAddress.

Format: ISO-3166 ALPHA-2 code.
zipCode Conditional string 12345

Postal code or zip code of the destination address. This is mandatory when including shipmentAddress.

Limit: 1 to 100 characters.
phoneNumber Conditional string +1 123-456-7890

Contact number of the shipment recipient. This is mandatory when including shipmentAddress.

Phone numbers should be prefixed by '+' country code. For example, +1-987-654-3210 or +1 987 654 3210.

Limit: 1 to 20 characters.
shipmentAttachmentId Conditional string f49891fc-d9a5-4b4b-bc65-150b1c5e6dff

Attachment for shipping label details. This is mandatory when you require an Equinix-printed shipping label, and you are not providing the required details in shipmentAddress.

You may also include this when you want to attach a copy of your own shipping label.

The attachment, 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.

Limit: 36 characters.

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

requirePickup No boolean true true, false

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', you will move your shipments from your cage to the shipping area.

Default value: false

DEPRECATION

insureShipment

 No boolean true true, false

DEPRECATION: We no longer insure outbound shipments. This field will be retired on 30 September 2022.

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 is completed. There is no need to create a separate Smart Hands order.

If 'false', insurance is not required.

Default value: false
description No string Package is fragile and heavy. Handle with care. Additional description in attachment.

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

Limit: 10 to 4000 characters.
attachments No array [objects]

Attachments array comprising object(s) with attachment details. Each attachment object must contain the following parameters: id, name.

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.

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

id Conditional string 85d9660a-f877-405a-b38e-8e61a4f77f44

Attachment id. This is mandatory when an attachment is included.

You will obtain this value after attaching your file using the POST Attachments File API.

Limit: 36 characters.
name Conditional string OrderInstructions.docx

Name of the attachment. This is mandatory when an attachment is included.

You will obtain this value after using the POST Attachments File API, but you can change the name for your own reference when including this attachment in any order request.

This is free text input.

Limit: 5 to 100 characters.
customerReferenceId No string 2020/16347

Customer's own reference ID. This information can be searched for in Order History and will appear within Reports.

This is free text input.

Limit: 1 to 40 characters
purchaseOrder Conditional object

Purchase order (PO) information you want to associate with this order. This is mandatory when your account is PO bearing.

This object comprises the following parameters where applicable: type, number, amount, startDate, endDate, attachmentId.
type Conditional string NEW EXEMPTED,
EXISTING,
NEW

Purchase order type can be categorized as exempted, existing, or new. This is mandatory when including purchase order information.

Type - Description
EXEMPTED - You are exempted from: a) including a purchase order in your request, or b) you are applying for exemption to include a purchase order in your request. If b), see body parameter 'attachmentId'.
EXISTING - You would like to use an existing blanket purchase order for this order. Body parameter 'number' is mandatory with this.
NEW - You would like to use a new blanket purchase order which has not yet been applied for any order. Body parameter 'number' is mandatory with this. You can also include the following parameters: amount, startDate, endDate, attachmentId.

Default value: EXEMPTED
number Conditional string 9654284

Purchase order number to associate with this order. This is mandatory when purchase order type is existing or new.

For existing purchase orders, if the blanket purchase order number submitted throws an error, select 'EXEMPTED' for purchase order type instead.

See GET PurchaseOrders under the API Reference section to retrieve your applicable blanket purchase order number.

amount No number 10000 Total value amount of the new purchase order. This is only applicable when purchase order type is new.
startDate No string 2020-10-01

Starting date of the new purchase order. This is only applicable when purchase order type is new.

Format: yyyy-MM-dd
endDate No string 2021-09-30

End date of the new purchase order. This is only applicable when purchase order type is new.

Format: yyyy-MM-dd
attachmentId No string 56d10de6-f2c0-4edd-ba29-b70736aa2093

Attachment ID. You can attach a new purchase order document, or the Purchase Order Exemption Form.

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

Download Purchase Order Exemption Form Template.

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

Limit: 36 characters.

This should be included when your purchase order type is new and you would like to attach the new blanket purchase order, or your purchase order type is exempted and you are submitting a Purchase Order Exemption form.

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

contacts No array [objects]

Contacts array consists of the technical contact and notification contact(s) information. Equinix will be able to communicate with these contacts based on their information provided. When any of the contacts are not provided, they default to the authenticated user who submitted this order (ordering contact).

Technical contact is the person who Equinix can reach out to for technical clarifications. Only one technical contact can be passed.

  • If they are a registered Equinix Customer Portal user, only their username needs to be passed. All their contact details will be referred from their user profile in the Equinix Customer Portal. Their work hours time zone will also be referred from the user profile, unless otherwise included in this request.
  • If they are a non-registered contact, their full name (first and last names) and contact details must be provided. To include more information such as the technical contact's availability or time zone, see parameter 'details'.

Notification contact is the person who will be notified of status updates. At least one notification contact must be provided.

  • They must be a registered Equinix Customer Portal user. Only their username needs to be passed.
  • N/A for a non-registered contact.

When providing the contact information for:

  • Registered contact object, the following body parameters are mandatory: registeredUsers, type. All other attributes passed in a registered contact object will be ignored.
  • Non-registered contact object, the following body parameters are mandatory: firstName, lastName, type, details.

For more information on technical contact's work hours time zone, see description of body parameter, 'timezone'.
type Conditional string NOTIFICATION NOTIFICATION,
TECHNICAL

Defines the contact type. This is mandatory for the registered and non-registered contacts.

Type - Description
TECHNICAL - Technical contact (applies to both registered and non-registered contacts).
NOTIFICATION - Notification contact (applies to registered contact only).
registeredUsers Conditional array [strings] john_doe1,
jane_smith1		 Equinix Customer Portal username of the registered user. This is mandatory for a registered contact.

Equinix Customer Portal user's status must be approved, active, or locked. If the user's status is not any of these, the request will fail. Refer to GET Users for more information.

Limit for technical contact: 1 string.

Limit for notification contact(s): 1 to 10 strings.
firstName Conditional string John

First name of the non-registered Technical contact. This is mandatory for a non-registered Technical contact.

This is free text input.
lastName Conditional string Doe

Last name of the non-registered Technical contact. This is mandatory for a non-registered Technical contact.

This is free text input.
availability Conditional string WORK_HOURS ANYTIME, WORK_HOURS

Defines the technical contact's availability to be contacted.

Availability - Description
ANYTIME - Technical contact is available 24/7.
WORK_HOURS - Technical contact is only available during work hours in their time zone. For a registered technical contact, their work hours is defaulted to the time zone in their user profile. If they would like to provide a different time zone, they should provide it in the body parameter 'timezone'. For a non-registered technical contact, if they select their work hours, the parameter 'timezone' is mandatory.

Default value: ANYTIME
timezone Conditional string America/Los_Angeles Click here for applicable values

Defines the time zone of the technical contact's work hours. This is mandatory when the non-registered technical contact selects their work hours as their availability.

For a registered technical contact, the time zone provided here will override the time zone in the user profile only for this order request, and does not replace the time zone in their user profile.

For example, selecting 'America/Los_Angeles' specifies the technical contact's work hours.
details Conditional array [objects]

Array of contact details for the non-registered technical contact consisting of the type of contact detail and its value. It is mandatory to provide two types of contacts:

  • always email address and
  • at least one type of number, either phone or mobile.

Limit: 2 to 3 objects.
type Conditional string EMAIL EMAIL,
MOBILE,
PHONE

Defines the contact detail type.

Type - Description
EMAIL - Email address.
MOBILE - Mobile phone number. This is the secondary contact number.
PHONE - Phone number. This is the primary contact number.
value Conditional string johndoe@acme.com

Value of the contact detail type.

Phone numbers must be prefixed by '+' country code.
For example, +1-987-654-3210 or +1 987 654 3210.

Email addresses must follow a valid email format.

Order is successfully created when an HTTP code of 201 is returned and the following response header is returned. There is no response body.

HTTP Response Header Name Description
Location

Location of the newly created order.

Example: /orders/{orderId}

'orderId' is the order identifier. This is important if you want to update, add notes to, retrieve and reply negotiations for, or cancel the order. It is also known as the order number in the Equinix Customer Portal.

If you would like to update this order, see Shipments (V2) in the API Reference section for more information.

If you would like to add notes, retrieve and reply negotiations, or cancel this order, see Orders (V2 Beta) in the API Reference Section for more information.

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

Schedule inbound shipment (V1)

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

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: Get Shipment Details

To get shipment details, the user must have Shipments ordering 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 /orders/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, number, attachment {id, name}}, serviceDetails {estimatedDateTime, shipmentDetails {trackingNumber [...], inboundType, noOfBoxes, isOverSized, carrierName, otherCarrierName}, deliverToCage, inboundRequestDescription, attachments [{id, name}], contacts [{contactType, userName},{contactType, name, email, workPhoneCountryCode, workPhone, workPhonePrefToCall, workPhoneTimeZone, mobilePhoneCountryCode, mobilePhone, mobilePhonePrefToCall}]

This method creates an inbound shipment order. This can only be done by a user with Shipments 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 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)

Copy 
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 Attachments File to attach a file.

Copy 
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)

Copy 
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 Attachments File to attach a file.

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

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

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.

This is mandatory when an attachment is included.
contacts Yes array [objects] Contact information consists of the Ordering contact details, Technical contact details, and Notification contact details.
contactType Yes string ORDERING ORDERING,
TECHNICAL,
NOTIFICATION

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

Mandatory contacts
- Ordering contact person: Person who created the order. Only one Ordering contact can be passed.
- Notification contact person: Person who will be notified of status updates. At least one notification contact must be provided. If notification contact is not available to pass, use ordering contact as notification contact.

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

Additional contacts
- Technical contact person: Person who Equinix can reach out to for technical clarifications. Only one Technical contact can be passed
- Notification contact person(s)
userName Yes string 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 +1

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 MY_BUSINESS_HOURS NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

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

Call Preference - Description
NEVER - Does not take calls.
ANYTIME - Takes calls anytime.
MY_BUSINESS_HOURS - Takes calls only during their business days from 9am to 5pm in their specified time zone. The body parameter 'workPhoneTimeZone' is mandatory to pass when this option is selected.
IBX_BUSINESS_HOURS - Takes calls only during the business hours of the IBX. 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 Pacific/Honolulu Click here for applicable values

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

This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.
mobilePhoneCountryCode No string +1

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

Example: +571, +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.

For description of applicable values, refer to description of body parameter 'workPhonePrefToCall'.
mobilePhoneTimeZone Conditional string Click here for applicable values

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

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-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 (V1)

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

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: Get Shipment Details

To get shipment details, the user must have Shipments ordering 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 /orders/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, number, 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}]

This method creates an outbound shipment order. This can only be done by a user with Shipments 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 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)

Copy 
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 Attachments File to attach a file.

Copy 
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)

Copy 
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 Attachments File to attach a file.

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

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

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

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

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.
contacts Yes array [objects] Contact information consists of the Ordering contact details, Technical contact details, and Notification contact details.
contactType Yes string

ORDERING

 ORDERING,
TECHNICAL,
NOTIFICATION

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

Mandatory contacts
- Ordering contact person: Person who created the order. Only one Ordering contact can be passed.
- Notification contact person: Person who will be notified of status updates. At least one notification contact must be provided. If notification contact is not available to pass, use ordering contact as notification contact.

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

Additional contacts
- Technical contact person: Person who Equinix can reach out to for technical clarifications. Only one Technical contact can be passed
- Notification contact person(s)
userName Yes string 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. It is recommended to also include the work phone country code. Additional information such as mobile phone country code, mobile phone number, and their availability to take calls on their mobile phone may also be provided.

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

For example, when 'email' and 'workPhone' are passed with 'userName' for Notification contact, these contact details will be ignored.
name Conditional string John 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.

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 MY_BUSINESS_HOURS NEVER,
ANYTIME,
MY_BUSINESS_HOURS,
IBX_BUSINESS_HOURS,
BUSINESS_HOURS

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

Call Preference - Description
NEVER - Does not take calls.
ANYTIME - Takes calls anytime.
MY_BUSINESS_HOURS - Takes calls only during their business days from 9am to 5pm in their specified time zone. The body parameter 'workPhoneTimeZone' is mandatory to pass when this option is selected.
IBX_BUSINESS_HOURS - Takes calls only during the business hours of the IBX. 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 Pacific/Honolulu Click here for applicable values

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

This is mandatory when 'MY_BUSINESS_HOURS' is selected for 'workPhonePrefToCall'.
mobilePhoneCountryCode No string +1

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

Example: +571, +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.

For description of applicable values, refer to description of body parameter 'workPhonePrefToCall'.
mobilePhoneTimeZone Conditional string Click here for applicable values

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

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