---
title: Fetching Assets
slug: fetching-assets
docTags: 
createdAt: 2026-02-13T04:24:46.730Z
---

Retrieve asset data using the Nue Lifecycle Management API. Assets represent physical or tangible items created when orders are activated, tracking deployment and utilization throughout their lifecycle.

## Prerequisites

Before you begin, ensure you have:

- A valid Nue API key with asset read permissions
- Customer IDs or asset numbers for the assets you want to retrieve
- Basic understanding of REST APIs and JSON
- Familiarity with asset lifecycle and status management

## Authentication

All asset retrieval operations require authentication using your Nue API key in the `nue-api-key` header:

```javascript
const myHeaders = new Headers();
myHeaders.append("nue-api-key", "YOUR_API_KEY_HERE");
myHeaders.append("Content-Type", "application/json");
```

## REST Endpoints

The Nue API provides REST endpoints for flexible asset data access:

```javascript
// Global asset endpoints
GET https://api.nue.io/assets                // Get all assets with pagination
GET https://api.nue.io/assets/{assetNumber}  // Get a specific asset by asset number

// Customer-scoped asset endpoints  
GET https://api.nue.io/customers/{customerId}/assets                // Get assets for a customer
GET https://api.nue.io/customers/{customerId}/assets/{assetNumber}  // Get a specific asset for a customer
```

### Filtering

Asset endpoints support filtering using query parameters:

**Query Parameters**:

- `customerIds` - Array of customer IDs to filter by
- `assetNumber` - Specific asset number to search for
- `status` - Filter by asset status
- `history` - Include asset history (true/false)
- `includes` - Include related data (e.g., `product`)
- `page` - Page number for pagination
- `limit` - Number of results per page

**Status Values**: `shipped`, `installed`, `registered`, `obsolete`, `purchased`

## Basic Asset Retrieval

### Fetch All Assets for Customer

**Try it now:** [Fetch Assets →](https://api-docs.nue.io/fetch-assets)

```javascript
const myHeaders = new Headers();
myHeaders.append("nue-api-key", "YOUR_API_KEY_HERE");
myHeaders.append("Content-Type", "application/json");

// Fetch all assets for a customer
const customerIds = ["d2e04653-ae90-49df-a986-134cf64f6d03"];
const encodedCustomerIds = encodeURIComponent(JSON.stringify(customerIds));

fetch(`https://api.nue.io/assets?customerIds=${encodedCustomerIds}`, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS' && result.data) {
    console.log(`Found ${result.data.length} assets`);
    
    result.data.forEach(asset => {
      console.log(`${asset.assetNumber}: ${asset.status} - ${asset.quantity} units`);
      console.log(`Product: ${asset.productId}, Price: $${asset.price || 0}`);
    });
  }
})
.catch(error => console.log('Error:', error));
```

## Filtered Asset Retrieval

### Fetch Assets by Status

```javascript
const customerIds = ["d2e04653-ae90-49df-a986-134cf64f6d03"];
const encodedCustomerIds = encodeURIComponent(JSON.stringify(customerIds));

// Fetch only active assets
fetch(`https://api.nue.io/assets?customerIds=${encodedCustomerIds}&status=active`, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS' && result.data) {
    result.data.forEach(asset => {
      console.log(`${asset.assetNumber}: ${asset.status}`);
      console.log(`Product: ${asset.productId}, Quantity: ${asset.quantity}`);
    });
  }
})
.catch(error => console.log('Error:', error));
```

### Fetch Specific Asset by Asset Number

```javascript
const assetNumber = "AST-001234";

fetch(`https://api.nue.io/assets?assetNumber=${encodeURIComponent(assetNumber)}`, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS' && result.data.length > 0) {
    const asset = result.data[0];
    console.log(`Asset: ${asset.assetNumber}`);
    console.log(`Status: ${asset.status}, Product: ${asset.productId}`);
    console.log(`Quantity: ${asset.quantity}, Price: $${asset.price}`);
  }
})
.catch(error => console.log('Error:', error));
```

## Including Related Data

### Fetch Assets with Product Details

```javascript
const customerIds = ["d2e04653-ae90-49df-a986-134cf64f6d03"];
const encodedIds = encodeURIComponent(JSON.stringify(customerIds));

// Include product details in the response
fetch(`https://api.nue.io/assets?customerIds=${encodedIds}&includes=product`, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS' && result.data) {
    result.data.forEach(asset => {
      console.log(`Asset: ${asset.assetNumber}`);
      console.log(`Status: ${asset.status}, Quantity: ${asset.quantity}`);
      
      if (asset.product) {
        console.log(`Product: ${asset.product.name} (${asset.product.sku})`);
      }
    });
  }
})
.catch(error => console.log('Error:', error));
```

## Asset History and Version Tracking

```javascript
async function fetchAssetHistory(assetNumber) {
  const response = await fetch(
    `https://api.nue.io/assets?assetNumber=${encodeURIComponent(assetNumber)}&history=true`,
    { method: 'GET', headers: myHeaders }
  );
  
  const result = await response.json();
  
  if (result.status === 'SUCCESS' && result.data.length > 0) {
    console.log(`Asset History for ${assetNumber}:`);
    
    result.data.forEach(version => {
      console.log(`Version ${version.assetVersion}: ${version.status}`);
      console.log(`Quantity: ${version.quantity}, Price: $${version.price || 0}`);
    });
    
    return result.data;
  }
  
  return [];
}

// Usage
fetchAssetHistory("AST-001234");
```

## Query Parameters Reference

| Parameter     | Type           | Required | Description                        |
| ------------- | -------------- | -------- | ---------------------------------- |
| `customerIds` | Array\[String] | \*       | JSON-encoded array of customer IDs |
| `assetNumber` | String         | \*       | Specific asset number to fetch     |
| `status`      | String         | No       | Filter by asset status             |
| `includes`    | String         | No       | Related data to include            |

\*Either `customerIds` or `assetNumber` is required

## Response Structure

### Success Response (200 OK)

```json
{
  "status": "SUCCESS",
  "data": [
    {
      "id": "asset-uuid",
      "assetNumber": "AST-001234",
      "name": "Enterprise Software License",
      "status": "Active",
      "customerId": "customer-uuid",
      "productId": "product-uuid",
      "orderProductId": "order-product-uuid",
      "quantity": 5,
      "installDate": "2024-01-15",
      "purchaseDate": "2024-01-10",
      "price": 2500.00,
      "assetVersion": 1,
      "billingAccountId": "billing-account-uuid",
      "createdDate": "2024-01-10T10:00:00Z",
      "lastModifiedDate": "2024-01-15T14:30:00Z",
      "product": {
        "id": "product-uuid",
        "name": "Enterprise Software",
        "sku": "ESW-001",
        "description": "Enterprise software license"
      }
    }
  ],
  "warnings": []
}
```

## Error Handling

```javascript
async function safeAssetFetch(customerIds, options = {}) {
  try {
    if (!Array.isArray(customerIds) || customerIds.length === 0) {
      throw new Error('CustomerIds must be a non-empty array');
    }
    
    const encodedIds = encodeURIComponent(JSON.stringify(customerIds));
    let url = `https://api.nue.io/assets?customerIds=${encodedIds}`;
    
    if (options.status) url += `&status=${options.status}`;
    if (options.includes) url += `&includes=${options.includes}`;
    
    const response = await fetch(url, {
      method: 'GET',
      headers: myHeaders
    });
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    
    const result = await response.json();
    
    if (result.status !== 'SUCCESS') {
      throw new Error(`API Error: ${result.message || 'Unknown error'}`);
    }
    
    return {
      assets: result.data || [],
      found: result.data?.length || 0,
      warnings: result.warnings || []
    };
    
  } catch (error) {
    console.error('Asset fetch error:', error);
    return {
      assets: [],
      found: 0,
      error: error.message
    };
  }
}
```