---
title: Fetching Customers
slug: fetching-customers
docTags: 
createdAt: 2026-02-13T04:24:46.989Z
---

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:

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

```javascript
// 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 →](https://api-docs.nue.io/fetch-customers)

```javascript
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:

```javascript
// 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));
```

## Including Related Data

### Fetch Customers with Contact Information

Include customer contacts in the response:

```javascript
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

```javascript
// 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:

```javascript
// 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

```json
{
    "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": "company@email.com",
            "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

```javascript
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

1. **Use specific filters** to reduce data transfer
2. **Include related data** only when needed to optimize performance
3. **Batch customer queries** efficiently
4. **Cache frequently accessed** customer data

### Performance Optimization

1. **Limit includes** to required data only
2. **Use appropriate timeout** settings for API calls
3. **Monitor API usage** and respect rate limits
4. **Implement proper error handling** for network issues

### Business Intelligence

1. **Analyze customer profiles** for segmentation insights
2. **Track customer engagement** through contact completeness
3. **Monitor commercial activity** and order patterns
4. **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.