Retrieve Assets

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

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

This method returns assets for an authenticated user with 'View Install Base' permissions. 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. 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, CROSS_CONNECT_Z_SIDE 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",
      "relatedAccountNumber": null,
      "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,
        "productBundle": null,
        "patchPanelNumber": "PP:0210:73281"
      }
    },
    {
      "assetNumber": "10147789",
      "serialNumber": "VP:0101:74679",
      "orderNumber": null,
      "productName": "PATCH_PANEL",
      "ibx": "DA1",
      "cage": "DA1:R1:V000170-1-294",
      "productDescription": "Patch Panel",
      "accountNumber": "987",
      "relatedAccountNumber": null,
      "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,
        "productBundle": null,
        "patchPanelNumber": "VP:0101:74679"
      }
    }
  ],
  "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.
relatedAccountNumber	string	null	Related 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.
productBundle	string	null	The boundle of the asset type.
patchPanelNumber	string	PP:0210:73281	Patch panel number of the asset.
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.