Fetching Assets

14 min

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:

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:

// 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 →

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

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

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));

Fetch Assets with Product Details

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

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)

{
  "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

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