Skip to main content
Index

Retrieve Order History

Step 1: Authenticate

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

 

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

 

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

Step 2: Get Order History Details

Get Location Information

Retrieve your IBX location information.

 

Use this API to identity all available IBX locations where the user has permission to retrieve orders history.

 

Refer to Get Retrieve Orders 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: Retrieve Order History

POST /retrieve-orders

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

 {filters{orderStatus[],productTypes[],

ibxs[],dateRange,fromDate,toDate},sorts[{name,direction}],

source[],page{number,size},q}

 

The Post retrieve orders API returns orders history for IBX locations that the user has access to. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

 

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

 

The following screenshots show a sample curl request and JSON response for this API. An order history request was done for submitted Smart Hands orders linked to ordering or notification contact person with last name 'smith' in IBXs, DC3 and DC4. This was done with two different ways of defining a date range (A) defining the date range from the date this request is submitted, and (B) defining a date range between two specific dates.

 

Refer to (A) only if the preferred date range is one week, two weeks, one month, three months, six months, or one year from the date this request is submitted. If your preferred date range falls outside of this, refer to (B).

 

(A) Orders history request with a date range from the date this request is submitted 

 

curl -X

POST "https://api.equinix.com/v1/retrieve-orders"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "filters": {
    "orderStatus": [
      "SUBMITTED",

      "IN_PROGRESS"
    ],
    "productTypes": [
      "SMART_HANDS"
    ],
    "ibxs": [
      "DC3",

      "DC4"
    ],
    "dateRange": "PAST_YEAR"
  },
  "sorts": [
    {
      "name": "CREATED_ON",
      "direction": "DESC"
    }
  ],
  "source": [
    "CONTACT_LAST_NAME"
  ],
  "page": {
    "number": 0,
    "size": 1
  },
  "q": "smith"
}

 

(B) Orders history request with a date range between two specific dates

 

curl -X

POST "https://api.equinix.com/v1/retrieve-orders"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "filters": {
    "orderStatus": [

      "SUBMITTED",

      "IN_PROGRESS"

    ],
    "productTypes": [
      "SMART_HANDS"
    ],
    "ibxs": [
      "DC3",

      "DC4"
    ],
    "fromDate": "09/02/2019",
    "toDate": "09/15/2019"
  },
  "sorts": [
    {
      "name": "CREATED_ON",
      "direction": "DESC"
    }
  ],
  "source": [
    "CONTACT_LAST_NAME"
  ],
  "page": {
    "number": 0,
    "size": 1
  },
  "q": "smith"
}

 

The description of the body parameters is as follows:

 

Body parameter name Mandatory Type Example Applicable Values Description
filters No object     The filters that can be applied to this search. 

The order history can be filtered by order status, product type, IBXs, or date range.
orderStatus No array[strings]

SUBMITTED,

IN_PROGRESS

ENTERED,
BOOKED,
SUBMITTED,
IN_PROGRESS,
PENDING_QA,
PENDING_INFLIGHT,

PARTIAL_SUBMISSION,

CANCELLED,

PENDING_CANCELLATION,

CLOSED,

QUOTE_IN_PROGRESS,

QUOTE_IN_REVIEW,

QUOTE_ORDER_SUBMITTED,

QUOTE_CUSTOMER_ACCEPTED,

QUOTE_PENDING_CUSTOMER_ACCEPTANCE,

QUOTE_CANCELLED,

QUOTE_EXPIRED,

EXPEDITE_AWAITING_CUSTOMER_RESPONSE,

PENDING_CUSTOMER_INPUT,

PII_HOLD,

ON_HOLD

The status of the order. 

 

By specifying single or multiple sources (ex: ENTERED or CLOSED, CANCELLED), the constraint is placed on specific order status types.

 

By default, search will be performed in all fields.

 

For easier understanding, the specific order status types have been grouped into their general order status types below.

 

E.g. If you would like to call all orders that are Cancelled, you can call all orders with the following specific order status types: CANCELLED, QUOTE_CANCELLED, QUOTE_EXPIRED. 

 

General order status type

Specific order status type - Description

 

In Quote

QUOTE_ORDER_SUBMITTED - Quote orders are quotes done offline and submitted into the system for progress, review, and eventual customer acceptance.

QUOTE_IN_PROGRESS - Quote in development. 

QUOTE_IN_REVIEW - Quote in final negotiation stages between customer and Equinix.

QUOTE_PENDING_CUSTOMER_ACCEPTANCE - Quote is pending final acceptance from customer.

QUOTE_CUSTOMER_ACCEPTED - Quote has been accepted by customer. 

 

Order Received

ENTERED - Order created.
BOOKED - Order is received and confirmed in the system.
SUBMITTED - Order is submitted for workflow and assigned to Equinix OPS team.

 

In Progress
IN_PROGRESS - Order fulfillment is in progress without any current impediments.
PENDING_QA - Order requires manual intervention from Equinix end.
PENDING_INFLIGHT - Order was updated or modified by the customer. 

PARTIAL_SUBMISSION  - Order does not contain the complete required information from customer to be fulfilled. 

PENDING_CANCELLATION - Order needs to go through final clearing activities process before order can be canceled.

 

On Hold

ON_HOLD - Order is credit hold and unable to proceed.

 

Pending Action Required

PII_HOLD - Order is held as customer requires final pricing acceptance on their end before order can proceed.

PENDING_CUSTOMER_INPUT - Order that customer must respond to before Equinix OPS team may proceed

EXPEDITE_AWAITING_CUSTOMER_RESPONSE - Expedited order that customer must respond to before Equinix OPS team may proceed.

 

Completed

CLOSED - Order is completed and closed.

 

Cancelled

CANCELLED - Order is canceled.

QUOTE_CANCELLED - Quote is canceled. 

QUOTE_EXPIRED - Quote has expired and is no longer valid.

productTypes No array[strings]

SMART_HANDS

SMART_HANDS,

TROUBLE,

INBOUND_SHIPMENT,

OUTBOUND_SHIPMENT,

WORK_VISIT,

SECURITY_ACCESS,

CONFERENCE_ROOM,

TOUR_REQUESTS,

CROSS_CONNECT,

CLOUD_EXCHANGE_PORT,

INTERNET_EXCHANGE_PORT,

METRO_CONNECT,

POWER,

ACCESSORY,

CAGE,

CABINET,

PATCH_PANEL,

IBX_SMART_VIEW

 

The order or ticket type. 

 

By specifying single or multiple sources (ex: CAGE or CAGE, CABINET), the constraint is placed on specific product types.

 

By default, search will be performed in all fields.

 

For easier understanding, the specific product types have been grouped into their general product types below.

 

E.g. If you would like to call all orders for all site services, you can call all orders with the following specific product types: WORK_VISIT, SECURITY_ACCESS, CONFERENCE_ROOM, TOUR_REQUESTS.

 

General product type

Specific product type - Description

 

Tickets

SMART_HANDS - Tickets submitted for Smart Hands services.

TROUBLE - Trouble tickets submitted to resolve IBX issues.

INBOUND_SHIPMENT - Scheduled deliveries of inbound shipments.

OUTBOUND_SHIPMENT - Scheduled pickup of outbound shipments.

 

Site Services

WORK_VISIT - Scheduled work visits to IBXs. 

SECURITY_ACCESS - Requests or removals of security access to IBXs.

CONFERENCE_ROOM - Scheduled conference room reservations at IBXs.

TOUR_REQUESTS - Requested IBX tour for one or more visitors.

 

Interconnection

CROSS_CONNECT - Orders made for Standard, Intra-customer, Extended or Extended Fiber, and Fiber cross connects, as well as cross connect removals.

CLOUD_EXCHANGE_PORT - Ports ordered for ECX Fabric.

INTERNET_EXCHANGE_PORT - Ports ordered for Equinix Internet Exchange.

METRO_CONNECT - Orders made for Metro Connect. 

 

Co-location

POWER - Orders made for power circuits.

IBX_SMART_VIEW - Orders made for IBX SmartView and IBX SmartView Environment.

ACCESSORY - Orders made for accessories including cage, cabinet, and power accessories. 

CAGE - Orders made for cages. 

CABINET - Orders made for cabinets.

PATCH_PANEL - Orders made for patch panels.

 

 

Deprecated values

IBX_SMARTVIEW_SENSOR - This value is no longer applicable, and will be removed in the near future.

OTHER - This value is no longer applicable, and will be removed in the near future.

ibxs No array[strings]

DC3,
DC4

 

The IBX location code(s).

 

By specifying single or multiple sources (ex: DC3 or DC3, DC4), the constraint is placed on specific IBXs.

 

By default, search will be performed in all IBXs user has access to.

dateRange No string PAST_YEAR PAST_7_DAYS,
PAST_14_DAYS,
PAST_30_DAYS,
PAST_3_MONTHS,
PAST_6_MONTHS,
PAST_YEAR

Specified date ranges for the order history ending with the date this request is submitted.

 

E.g. PAST_7_DAYS - all orders from the past 7 days up to the date this request is submitted

 

If the preferred date range falls outside the 'dateRange' values, it is recommended to define the date range with 'fromDate' and 'toDate'. 

This cannot be used with 'fromDate' and 'toDate'. 'dateRange' will override 'fromDate' and 'toDate' if used together. 

fromDate No string 09/02/2019  

The preferred starting date of order history.

 

The date should follow the format of MM/DD/YYYY (month/day/year).

 

The preferred dates cannot include future dates, and the preferred date range cannot exceed one year.


This is not applicable when 'dateRange' is provided. 

toDate No string 09/15/2019  

The preferred end date of order history. 

 

The date should follow the format of MM/DD/YYYY (month/day/year).

 

The preferred dates cannot include future dates, and the preferred date range cannot exceed one year.

 

This is not applicable when 'dateRange' is provided. 

sorts No array[object]     Arrangement criteria of the order history.
name No string CREATED_ON SOURCE,
ORDERING_CONTACT,
ACCOUNT_NUMBER,
ACCOUNT_NAME,
STATUS,
CREATED_ON,
 

The order history can be arranged according to the following sorting names.

 

Name - Description

SOURCE - Indicates the source of the order creation. This can be via the portal, offline, or quote.

ORDERING_CONTACT - The name of the ordering contact person linked to the order.
ACCOUNT_NUMBER - The cage account number linked to the order.
ACCOUNT_NAME - The cage account name linked to the order.
STATUS - The status of the order. 
CREATED_ON - The order creation date.

 

 

Deprecated values

SR_NUMBER - This value is no longer applicable, and will be removed in the near future.

direction No string DESC ASC,
DESC

The arrangement of the order history by ascending or descending order in relation to the sorting name. 

 

Direction - Description

ASC - Ascending order.

DESC - Descending order.

source No array[string] CONTACT_LAST_NAME ORDER_NUMBER,
PO_NUMBER,
CUSTOMER_REFERENCE_NUMBER,
CONTACT_LAST_NAME,
TROUBLE_TICKET_NUMBER,
WORK_ACTIVITY_NUMBER

The source defines the free text search that will help narrow down the order history returned. It is recommended to define a source when using the free text query search.

 

By default, search will be performed in all fields.

 

Source - Description
ORDER_NUMBER - Order number.
PO_NUMBER - Purchase order number linked to the order.
CUSTOMER_REFERENCE_NUMBER - Customer reference number linked to the order.
CONTACT_LAST_NAME - Ordering or notification contacts last name.
TROUBLE_TICKET_NUMBER - Trouble ticket number linked to the order.
WORK_ACTIVITY_NUMBER - Work activity number linked to the order.

 

 

Deprecated values

SR_NUMBER - This value is no longer applicable, and will be removed in the near future.

page No object     The page information of the order history to be displayed.
number No integer 0  

The page number index of the order history to be returned.

 

E.g. If '0', the first page of the order history will be returned.

       If '1', the second page of the order history will be returned.

 

Default value: 0. The value should be equal to or greater than 0.

size No integer 1  

Size defines the number of orders returned per page in the order history. 

 

E.g. If '1', the number of orders returned on each page of the order history returned is 1 order.

 

Default value: 10

Minimum value: 1

Maximum value: 200

q No string smith  

Query search by keyword or free text within 'source' fields. 

 

Supports partial text search.

 

There is no character limit for this.

 

{
  "links": [
    {
      "rel": "self",
      "href": "https://api.equinix.com/v1/orders-history/"
    },
    {
      "rel": "next",
      "href": "https://api.equinix.com/v1/orders-history/?page=1"
    }
  ],
  "content": [
    {
      "orderNumber": "1-190123456789",
      "createdAt": "2019-09-17T22:49:34Z",
      "orderStatus": "SUBMITTED",
      "orderSource": "Portal",
      "account": {
        "accountName": "John Doe Corp",
        "accountNumber": "12345"
      },
      "uiMetaData": {
        "pricingEnforcementFlag": "false"
      },
      "orderingContacts": {
        "firstName": "James",
        "lastName": "Smith",
        "workPhone": "(972) 123-4567",
        "contactUCId": "234432",
        "username": "JSmith123",
        "emailAddress": "jsmith@johndoecorp.com"
      },
      "notificationContacts": [
        {
          "phone": "972-890-1234",
          "workPhone": "972-123-4567",
          "lastName": "Smith",
          "firstName": "James",
          "contactUCId": "234432",
          "emailAddress": "jsmith@johndoecorp.com",
          "username": "JSmith123"
        }
      ],
      "ibx": [
        "PAA"
      ],
      "type": [
        "Smart Hands"
      ],
      "customerReferenceNumber": "RQT12345",
      "poNumbers": [
        "1-1007"
      ],
      "piiHoldFlag": false,
      "technicalContacts": [
        {
          "firstName": "James",
          "lastName": "Smith",
          "workPhone": "(972) 123-4567",
          "contactUCId": "234432",
          "username": "JSmith123",
          "emailAddress": "jsmith@johndoecorp.com"
        }
      ],
      "pendingCustomerInputFlag": false,
      "awaitingCustomerResponse": false,
      "srNumber": "9-191234567890",
      "cancellable": true,
      "modifiable": true,
      "links": [
        {
          "rel": "orderFullDetails",
          "href": "https://api.equinix.com/v1/orders-history/1-190123456789"
        }
      ]
    }
  ],
  "page": {
    "size": 1,
    "totalElements": 19,
    "totalPages": 19,
    "number": 0
  }
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
links array[objects]  

Hateoas information with self, previous and next links.

 

These display the previous, current, or next pages for the order history.

rel string self

Reference to the page link.

 

Page reference - Description

prev - indicates the previous page

self - indicates the current page (self-reference)

next - indicates the next page

href string

https://api.equinix.com/

v1/orders-history/

The link to the page that is before, current, or next.

content array[object]   Order content contains the order objects.
orderNumber string 1-190123456789 The order number. 
createdAt string 2019-09-17T22:49:34Z

The date and time the order was created. 


This follows the date and time (UTC timezone) in the ISO 8601 format.

orderStatus string SUBMITTED

The current status of the order.

 

Refer to description of body parameter "orderStatus".

orderSource string Portal

The source where the order was created. 

 

Order source types - Description

Portal - Order came via the customer portal.

Offline - Order came via offline methods.

Quote - Order came via quotation. 

Mobile - Order came via Equinix Mobile. 

account object   Account information that includes account name and account number.
accountName string John Doe Corp Cage account name linked to the customer. 
accountNumber string 12345 Cage account number linked to the customer. 
uiMetaData object  

This is an Equinix reference. 

 

You may ignore this. 

pricingEnforcementFlag string false

This is an Equinix reference. 

 

You may ignore this. 

orderingContacts object    Contact information of the Ordering contact person that includes their first name, last name, work phone number, username, and email address. 
firstName string James First name of the Ordering contact.
lastName string Smith Last name of the Ordering contact.
workPhone string (972) 123-4567 Work phone number of the Ordering contact.
contactUCId string 234432

Equinix reference of the Ordering contact. 

You may ignore this. 

username string JSmith123 Equinix-registered username of the Ordering contact.
emailAddress string jsmith@johndoecorp.com Email address of the Ordering contact person. 
notificationContacts array[object]   Contact information of the Notification contact person(s) that includes their phone number, work phone number, first name, last name, work phone number, username, and email address. 
phone string 972-890-1234 Mobil phone number of the Notification contact.
workPhone string 972-123-4567  Work phone number of the Notification contact.
lastName string Smith Last name of the Notification contact.
firstName string James First name of the Notification contact.
contactUCId string 278787

Equinix reference of the Notificaiton contact. 

You may ignore this. 

emailAddress string jsmith@johndoecorp.com Email address of the Notification contact person. 
username string JSmith123 Equinix-registered username of the Notification contact person. 
ibx array[strings] PAA

IBX location code(s) of the IBX data center linked to this order. 


E.g. PAA represents an IBX in Paris, France.

type array[strings] Smart Hands

The product types linked to this order. There may be more than one product type in an order.

 

Refer to description of body parameter "productTypes".

 

customerReferenceNumber string RQT12345 Customer reference number that was provided by the customer when the order was created. 
poNumbers array[strings] 1-1007 Purchase order numbers that are linked to this order. There may be more than one purchase order number linked to an order.
piiHoldFlag boolean false

Indicates if this order was flagged for a PII hold.

 

If 'true', the order will be held and will not proceed.

 

If 'false', the order will not be held and will proceed.

technicalContacts

array[objects]

  Contact information of the Technical contact person that includes their phone number, work phone number, first name, last name, work phone number, username, and email address. 
firstName string James First name of the Technical contact.
firstName string Smith Last name of the Technical contact.
workPhone string (972) 123-4567 Work phone number of the Technical contact.
contactUCId string 278787 Equinix reference of the Technical contact. 

You may ignore this. 
username string JSmith123 Equinix-registered username of the Technical contact person. 
emailAddress string jsmith@johndoecorp.com Email address of the Technical contact person. 
pendingCustomerInputFlag boolean false

Indicates if this order was flagged for additional customer input.

 

If 'true', the order will be held until the customer provides the required information.

 

If 'false', the order will not be held and will proceed.

awaitingCustomerResponse boolean false

Indicates if this order is pending customer response.

 

If true, the order will be held until the customer responds.

If false, the order will not be held and will proceed.

srNumber string 9-191234567890 The Equinix service request number linked to the order. 
cancellable boolean true

Indicates if the order can still be canceled.

 

If 'true', order can be canceled.

 

If 'false', order cannot be canceled. 

modifiable boolean true

Indicates if the order can still be modified.

 

If 'true', order can be modified.

 

If 'fasle', order cannot be modified.

links array[object]   Link to full details of the order. 
rel string orderFullDetails Reference to the page link to view order's full details. 
href string

https://api.equinix.com/

v1/orders-history/1-190123456789

Page link to view order's full details.  
page object   Page information that includes the requested size of the information displayed, the total number of elements in the order history, the total number of pages in the order history, and the page index number.
size integer 1

Size of the information displayed per page.


In this case, it is the number of orders displayed per page, and this tallies with body parameter 'size' in the submitted request.

 

The minimum value is 1 and the maximum value is 200. 

totalElements integer 19

Total elements or total number of orders for the requested order history.

totalPages integer 19

Total number of full pages for the requested order history, including the starting page '0'.

 

I.e. If total elements divided by the size gives you a whole number, the total pages includes the final page.
        E.g. If size is 1 and totalElements is 19, totalPages is 19 (there are a total of 19 pages ranging from 0-18).
 

I.e. If total elements divided by the size gives you a fraction/ decimal, the total pages does not include the final page. 
        E.g. If size is 2 and totalElements is 19, totalPages is 9 (but there are a total of 10 pages ranging from 0-9).

number integer 0

The page number index of the order history to be returned. 

 

This tallies with body parameter 'number' in the submitted request. The starting number is 0, and it represents the first page. 

 

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