Retrieve Order History

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 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 Access Token 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 Equinix 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.