Fetching Customers

18 min

This guide provides comprehensive instructions for retrieving customer data using the Nue Lifecycle Management API. Learn how to fetch single or multiple customers, include related data, and implement efficient customer data retrieval workflows.

Prerequisites

Before you begin, ensure you have:

A valid Nue API key with customer read permissions

Customer IDs (either Salesforce IDs or Nue UUIDs)

Basic understanding of REST APIs and JSON

Familiarity with customer data structures

Authentication

All customer 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 customer data access:

// Customer endpoints
GET https://api.nue.io/customers              // Get all customers with pagination
GET https://api.nue.io/customers/{customerId} // Get a specific customer by ID

Filtering

Customer endpoints support filtering using query parameters:

Query Parameters:

customerIds - Array of customer IDs to filter by

includes - Include related data

page - Page number for pagination

limit - Number of results per page

Basic Customer Retrieval

Fetch Single Customer

Try it now: Fetch Customers →

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

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

fetch(`https://api.nue.io/customers?customerIds=${encodedCustomerIds}`, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  console.log('Customer retrieved successfully:', result);
  
  if (result.status === 'SUCCESS' && result.data.length > 0) {
    const customer = result.data[0];
    console.log(`\nCustomer: ${customer.name}`);
    console.log(`Customer ID: ${customer.id}`);
    console.log(`Account Number: ${customer.externalId}`);
    console.log(`Record Type: ${customer.recordType}`);
    console.log(`Status: ${customer.status}`);
    console.log(`Created: ${customer.createdDate}`);
  }
})
.catch(error => console.log('Error:', error));

Fetch Multiple Customers

Retrieve multiple customers in a single API call:

// Fetch multiple customers
const customerIds = [
  "d2e04653-ae90-49df-a986-134cf64f6d03",
  "cc5e1f0f-5e14-48cc-ab98-9e5b191aa46f",
  "f1b2c3d4-e5f6-7890-abcd-ef1234567890"
];

const encodedCustomerIds = encodeURIComponent(JSON.stringify(customerIds));

fetch(`https://api.nue.io/customers?customerIds=${encodedCustomerIds}`, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS') {
    console.log(`Retrieved ${result.data.length} customers`);
    
    result.data.forEach((customer, index) => {
      console.log(`\n${index + 1}. ${customer.name}`);
      console.log(`   ID: ${customer.id}`);
      console.log(`   Type: ${customer.recordType}`);
      console.log(`   Status: ${customer.status}`);
      console.log(`   Account: ${customer.externalId}`);
    });
  }
})
.catch(error => console.log('Error:', error));

Fetch Customers with Contact Information

Include customer contacts in the response:

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

// Include contacts in the response
const urlWithContacts = `https://api.nue.io/customers?customerIds=${encodedIds}&includes=contacts`;

fetch(urlWithContacts, {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  if (result.status === 'SUCCESS' && result.data) {
    result.data.forEach(customer => {
      console.log(`\n🏢 Customer: ${customer.name}`);
      console.log(`   Account: ${customer.accountNumber}`);
      console.log(`   Email: ${customer.email || 'Not provided'}`);
      
      // Display contacts if included
      if (customer.contacts && customer.contacts.length > 0) {
        console.log(`\n   👥 Contacts (${customer.contacts.length}):`);
        customer.contacts.forEach(contact => {
          console.log(`     • ${contact.firstName} ${contact.lastName}`);
          console.log(`       Email: ${contact.email || 'Not provided'}`);
          console.log(`       Phone: ${contact.phone || 'Not provided'}`);
          console.log(`       Role: ${contact.title || 'Not specified'}`);
        });
      } else {
        console.log('   No contacts available');
      }
    });
  }
})
.catch(error => console.log('Error:', error));

Pagination Support

The customers endpoint supports pagination for retrieving large datasets efficiently:

Paginated Customer Retrieval

// Fetch first page of customers with default page size (100)
fetch('https://api.nue.io/customers?page=1&limit=50', {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  console.log(`Page ${result.pagination.page} of ${result.pagination.totalPages}`);
  console.log(`Showing ${result.data.length} of ${result.pagination.total} customers`);
  
  result.data.forEach(customer => {
    console.log(`- ${customer.name} (${customer.id})`);
  });
  
  // Check if more pages are available
  if (result.pagination.hasNext) {
    console.log('More customers available on next page');
  }
})
.catch(error => console.log('Error:', error));

Pagination with Filtering

Combine pagination with filtering for targeted results:

// Fetch customers with pagination
fetch('https://api.nue.io/customers?page=1&limit=25', {
  method: 'GET',
  headers: myHeaders
})
.then(response => response.json())
.then(result => {
  console.log(`Customers - Page ${result.pagination.page}`);
  console.log(`Total: ${result.pagination.total} customers`);

  result.data.forEach(customer => {
    console.log(`${customer.name} (${customer.id})`);
  });
});

Query Parameters Reference

Parameter	Type	Required	Description	Options
customerIds	Array[String]	No*	JSON-encoded array of customer IDs	["customer-uuid-1", "customer-uuid-2"]
includes	String	No	Related data to include	"contacts", "orders", "assets"
page	Integer	No	Page number for pagination	1 (default), 2, 3, etc.
limit	Integer	No	Records per page	100 (default), max 500
recordType	String	No	Filter by customer type	"Business", "Consumer"

*When using pagination (page/limit), customerIds becomes optional. Without customerIds, returns all customers with pagination.

Response Structure

Success Response (200 OK)

Paginated Response Structure

{
    "status": "SUCCESS",
    "data": [
        {
            "accountNumber": "Z100293",
            "accountSource": "Web",
            "annualRevenue": 5000000.00,
            "autoRenew": "Yes",
            "billCycleDay": "7th of Month",
            "billCycleStartMonth": "03",
            "billingCity": "San Francisco",
            "billingCountry": "US",
            "billingPeriod": "Annual",
            "billingPostalCode": "94005",
            "billingProrationEnabled": "Yes",
            "billingState": "CA",
            "billingStreet": "123 Main Street",
            "createdById": "3865c4c7-f233-4d7f-8426-2eb882856e5c",
            "createdDate": "2025-06-27T23:23:53.002+00:00",
            "description": "Some customer description",
            "email": "[email protected]",
            "fax": "+1-650-383-2838",
            "funding": "500000",
            "id": "c5786254-06a2-44fe-88d5-3dd5dad66e78",
            "imageSignedUrl": "https://signedurl.io",
            "industry": "Agriculture",
            "lastModifiedById": "3865c4c7-f233-4d7f-8426-2eb882856e5c",
            "lastModifiedDate": "2025-06-27T23:23:53.002+00:00",
            "legalEntityName": "EntityName",
            "name": "jadiceguyu",
            "phone": "393-393-2939",
            "recordType": "Consumer",
            "shippingCity": "San Francisco",
            "shippingCountry": "US",
            "shippingPostalCode": "94005",
            "shippingState": "CA",
            "shippingStreet": "123 Main Street",
            "site": "Website",
            "timezone": "Pacific/Kiritimati",
            "type": "Prospect",
            "website": "https://url.com"
        }
    ],
    "warnings": [],
    "pagination": {
        "page": 1,
        "limit": 100,
        "total": 247,
        "totalPages": 3,
        "hasNext": true,
        "hasPrevious": false
    }
}

Error Handling

Common Retrieval Errors

Error	Description	Resolution
INVALID_CUSTOMER_ID	Customer ID format invalid	Verify customer ID format
CUSTOMER_NOT_FOUND	Customer does not exist	Check customer ID exists
INVALID_RECORD_TYPE	Invalid record type filter	Use "business" or "consumer"
INVALID_INCLUDES	Invalid include parameter	Check available include options

Robust Customer Fetching

async function safeCustomerFetch(customerIds, options = {}) {
  try {
    // Validate inputs
    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/customers?customerIds=${encodedIds}`;
    
    // Add optional parameters
    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 {
      customers: result.data || [],
      found: result.data?.length || 0,
      requested: customerIds.length
    };
    
  } catch (error) {
    console.error('Customer fetch error:', error);
    return {
      customers: [],
      found: 0,
      requested: customerIds.length,
      error: error.message
    };
  }
}

Best Practices

Data Retrieval

Use specific filters to reduce data transfer

Include related data only when needed to optimize performance

Batch customer queries efficiently

Cache frequently accessed customer data

Performance Optimization

Limit includes to required data only

Use appropriate timeout settings for API calls

Monitor API usage and respect rate limits

Implement proper error handling for network issues

Business Intelligence

Analyze customer profiles for segmentation insights

Track customer engagement through contact completeness

Monitor commercial activity and order patterns

Generate actionable insights from customer data

This comprehensive guide enables you to efficiently retrieve and analyze customer data using the Nue Lifecycle Management API, supporting everything from simple customer lookups to complex portfolio analysis and business intelligence operations.