Skip to main content
Index

Retrieve Assets

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: Retrieve Asset Data

To retrieve asset data, the user must have 'View Install Base' permission. If you are unaware of your user permissions, contact your Master Administrator. 

 

Post Assets Search

POST /assets/search

 Method  POST
 URL or End Point  /v1/assets/search
 Headers  Authorization, Content-Type
 Query Parameters  sorts, source, q, exactMatch, offset, limit
 Body  filter{ibxs,cages,productTypes,dateRange{fromDate,toDate}}

 

The Post assets search API returns the requested searched assets 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. The request indicates that a search for patch panels in IBX location, DA1; in the cage, DA1:01:009800; and installed within the dates 2003/07/17 to 2019/07/17 was done. The search results were sorted by ascending serial number, filtered for patch panels that only had asset numbers including '101', selected to start from index 0, and limited to 100 results per page. 

 

curl -X

POST "https://api.equinix.com/v1/assets/search?sorts=SERIAL_NUMBER&source=ASSET_NUMBER&q=101&exactMatch=false&offset=0&limit=100"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
    "filter": {
        "ibxs": [
            "DA1"
        ],
        "cages": [
            "DA1:01:009800"
        ],
        "productTypes": [
            "PATCH_PANEL"
        ],
        "dateRange": {
            "fromDate": "2003-07-17T03:31:20.455Z",
            "toDate": "2019-07-17T03:31:20.455Z"
        }
    }

 

The description of the query parameters is as follows:

 

Query Parameter Name

Mandatory Type Example Applicable Values Description
sorts No array[string] SERIAL_NUMBER

ACCOUNT_NUMBER,
ASSET_NUMBER,
CAGE,
IBX,
INSTALLED_DATE,
ORDER_NUMBER,
PRODUCT_DESCRIPTION,
PRODUCT_NAME,
PRODUCT_TYPE,
SERIAL_NUMBER,

-ACCOUNT_NUMBER,
-ASSET_NUMBER
-CAGE,
-IBX,
-INSTALLED_DATE,
-ORDER_NUMBER,
-PRODUCT_DESCRIPTION,
-PRODUCT_NAME, 
-PRODUCT_TYPE,
-SERIAL_NUMBER

Assets searched can be sorted by cage account number, asset number, cage ID, ibx ID, asset installation date, order number, product description, product name, product type, or serial number, in ascending or descending order.

 

To sort by descending order, the applicable value must start with a '-'. 

source No array[string] ASSET_NUMBER

LEGACY_CABINET,
LEGACY_CAGE,
LEGACY_PATCH_PANEL,
LEGACY_SALES_ORDER,
ACCOUNT_NUMBER,
ASSET_NUMBER,
BILLING_AGREEMENT,
CABINET,
CABLE_ID,
CAGE,
CARRIER_CIRCUIT_ID,
CUSTOMER_INTERNAL_REFERENCE,
EXTERNAL_REFERENCE_NUMBER,
PATCH_PANEL,
SALES_ORDER_NUMBER,
SERIAL_NUMBER.

Assets can be searched by legacy cabinet ID, legacy cage ID, legacy patch panel ID, legacy sales order number, cage account number, asset number, billing agreement number, cabinet ID, cable ID, cage ID, patch panel ID, carrier circuit ID, customer internal reference, external reference number, patch panel ID, sales order number, and serial number. 

 

By specifying single or multiple sources (ex: CAGE or CAGE, LEGACY_CAGE), the constraint is placed on specific source fields.

 

By default, search will be performed in all fields.

q No string 101  

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

 

A minimum of 3 characters is required for efficient search results.

exactMatch No boolean false

true

false

To strictly determine if 'q' should be an exact match or partial match.

 

If 'true', 'q' must be an exact match.

 

If 'false', 'q' can be a partial match.

 

Default value: false.

offset No integer 0

Any integer value within the total number of results.

The index of the first item you want results for.

 

If a start value is not provided, the default value is 0.

limit No integer 100 Any integer value from 1 to 100.

The maximum number of search results to be shown per page. 

 

If a limit is not provided, the default value is 10.

 

The description of the body parameters is as follows:

 

Body Parameter Name

Mandatory Type Example Applicable Values Description
filter No object    

Filter of assets by IBX location codes, ID of cage, asset type, and date range of asset installation. 

ibxs No array[strings] DA1

 

IBX location codes.

 

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

By default, search will be performed in all IBXs.

cages No array[strings] DA1:01:009800  

ID of cages.

 

By specifying single or multiple sources (ex: DA1:01:009800 or DA1:01:009800, DA1:01:009801), the constraint is placed on specific cages.

 

By default, search will be performed in all cages.

productTypes No array[strings] PATCH_PANEL ACCESSORIES,
CABINET,
CAGE,
CROSS_CONNECT,
EQUINIX_ETHERNET_EXCHANGE,
EQUINIX_CLOUD_EXCHANGE,
PATCH_PANEL,
POWER,
IBX_SMARTVIEW,
OTHERS,
VIRTUAL_CIRCUIT,
BCTR_BCS_ROOM,
EQUINIX_CONNECT

The asset type.

 

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

 

If there is no value for 'productTypes', instead of leaving the value empty, do not include the body parameter.

 

For a full list of product types, product names, and product descriptions, click here

dateRange No object     Range of dates that asset was installed. 
fromDate No string 2003-07-17T03:31:20.455Z  

Date and time from which to start the search. 

 

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

 

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

 

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

 

If there is no value for 'fromDate', instead of leaving the value empty, do not include the entire dateRange body parameter.

toDate No string 2019-07-17T03:31:20.455Z  

Date and time at which to end the search. 

 

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

 

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

 

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

 

If there is no value for 'toDate', instead of leaving the value empty, do not include the entire dateRange body parameter.

 

{
  "data": [
    {
      "assetNumber": "10139297",
      "serialNumber": "PP:0210:73281",
      "orderNumber": 1-126273059,
      "productName": "PATCH_PANEL",
      "ibx": "DA1",
      "cage": "DA1:01:009800",
      "productDescription": "Patch Panel",
      "accountNumber": "987",
      "accountName": "JOHN-DOE-CORP",
      "installationDate": "2009-05-14T00:00:00Z",
      "customerReferenceNumber": DAY-98278,
      "billingAgreementNumber": CAB-93678,
      "status": "ACTIVE",
      "additionalDetails": {
        "cabinetNumber": "DA1:01:009800:0210",
        "customerOrCarrierCircuitID": null,
        "finalzSideSystemName": null

      }
    },
    {
      "assetNumber": "10147789",
      "serialNumber": "VP:0101:74679",
      "orderNumber": null,
      "productName": "PATCH_PANEL",
      "ibx": "DA1",
      "cage": "DA1:R1:V000170-1-294",
      "productDescription": "Patch Panel",
      "accountNumber": "987",
      "accountName": "JOHN-DOE-CORP",
      "installationDate": "2009-07-09T00:00:00Z",
      "customerReferenceNumber": null,
      "billingAgreementNumber": null,
      "status": "ACTIVE",
      "additionalDetails": {
        "cabinetNumber": "DA1:R1:V000170-1-294:V1801",
        "customerOrCarrierCircuitID": null,
        "finalzSideSystemName": null

      }
    }
  ],
  "page": {
    "limit": 100,
    "offset": 0,
    "total": 2,
    "sorts": [
      "SERIAL_NUMBER"
    ]
  },
  "_links": {
    "next": {
      "href": "/assets/search?q=101&exactMatch=false&offset=0&limit=100&source=ASSET_NUMBER&sorts=SERIAL_NUMBER"
    },
    "previous": {
      "href": "/assets/search?q=101&exactMatch=false&offset=0&limit=100&source=ASSET_NUMBER&sorts=SERIAL_NUMBER"
    },
    "self": {
      "href": "/assets/search?q=101&exactMatch=false&offset=0&limit=100&source=ASSET_NUMBER&sorts=SERIAL_NUMBER"
    }
  }
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
data array[objects]   Returned search results based on query parameters.
assetNumber string 10139297 Asset ID number.
serialNumber string PP:0210:73281 Asset serial number.
orderNumber string 1-126273059

Sales order number for the related asset.

 

If there is no number, the value 'null' is returned.

productName string PATCH_PANEL

The asset type.

 

For a full list of product types, product names, and product descriptions, refer to the request body parameter name, 'productTypes'.

ibx string DA1 The IBX location code.
cage string DA1:01:009800 Cage or suite ID number.
productDescription string Patch Panel

A description that corresponds with the asset type.

 

For a full list of product types, product names, and product descriptions, refer to the request body parameter name, 'productTypes'.

accountNumber string 987 Customer account number linked to the asset.
accountName string JOHN-DOE-CORP Customer account name linked to the asset.
installationDate string 2009-05-14T00:00:00Z

Date and time of installation of the asset.

 

The date and time (UTC timezone) are represented in ISO 8601 format, yyyy-MM-dd'T'HH:mm:ssZ.

customerReferenceNumber integer DAY-98278

Customer's own reference number.

 

If there is no number, the value 'null' is returned.

billingAgreementNumber integer CAB-93678

Billing Agreement Number.

 

If there is no number, the value 'null' is returned.

status string ACTIVE Present activity status of the asset.
additionalDetails object   Additional details relating to the asset.
cabinetNumber string DA1:01:009800:0210 Cabinet ID number.
customerOrCarrierCircuitID string null

Customer or Carrier Circuit ID for Cross Connect.

 

For assets that are not Cross Connect, the value 'null' is returned. 

finalzSideSystemName string null

Z-side for Cross Connect. 

 

For assets that are not Cross Connect, the value 'null' is returned. 

page object   The total number of pages showing results for the search.
limit integer 100 The maximum number of results shown per page. 
offset integer 0 The start index from which the search results list is created.
total integer 2 The total number of search results.
sorts array[string] SERIAL_NUMBER

Selected sorting order. 

 

If the value begins with a '-', it is in descending order.

 

This value should match the sorts field in the query parameter.

_links object   Links that show the previous page, current page, and next page of search results.
next object   Next search results page.
href string

/assets/search?q=101&exactMatch=false&
offset=0&limit=100&source=
ASSET_NUMBER&sorts=SERIAL_NUMBER

Link to the next page of search results.
previous object

 

Previous search results page.
href string

/assets/search?q=101&exactMatch=false&
offset=0&limit=100&source=
ASSET_NUMBER&sorts=SERIAL_NUMBER

Link to the previous page of search results.
self object   Current search results page.
href string

/assets/search?q=101&exactMatch=false&
offset=0&limit=100&source=
ASSET_NUMBER&sorts=SERIAL_NUMBER

Link to the current page of search results.

 

If you would like to know more detailed information about the individual asset, refer to GET Assets {assetId} under the API Reference section.

 

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