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.
