---
title: Getting Started with Customer Management
slug: getting-started-with-customer-management
docTags: 
createdAt: 2026-02-13T04:24:48.596Z
---

This guide walks you through the essential customer management operations in the Nue Self-Service API. You'll learn how to create, retrieve, and update customers with practical examples.

## Prerequisites

Before you begin, ensure you have:

- A valid Nue API key
- Access to the Nue Lifecycle Manager API
- Please make sure you understand JSON and RESTful API's

## Authentication

All customer 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");
```

## Creating Your First Customer

Let's start with creating a basic customer record. This is typically the first step in any customer onboarding flow.

### Basic Customer Creation

**Try it now:** [Create customers API →](https://api-docs.nue.io/create-customers)

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

// Create a basic customer record
const customerData = JSON.stringify([
  {
    "name": "Digital Innovations LLC",
    "recordType": "Business",
    "email": "contact@digitalinnovations.com",
    "phone": "+1-555-0100",
    "billingStreet": "123 Tech Avenue",
    "billingCity": "San Francisco",
    "billingState": "CA",
    "billingPostalCode": "94105",
    "billingCountry": "United States"
  }
]);

const requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: customerData,
  redirect: 'follow'
};

fetch("https://api.nue.io/customers", requestOptions)
  .then(response => response.json())
  .then(result => {
    console.log('Customer created successfully:', result);
    // Save the customer ID for future operations
    const customerId = result.data[0].id;
    localStorage.setItem('customerId', customerId);
  })
  .catch(error => console.log('error', error));
```

### Required vs Optional Fields

When creating a customer, only two fields are absolutely required:

- `name` (required): The customer's display name
- `recordType` (required): Either "Business" or "Consumer"

However, for practical implementations, you'll typically want to include:

- **Billing address fields**: Required for payment processing
- **Shipping address fields**: Required for tax calculations

## Retrieving Customer Information

Once you have customers in your system, you'll need to retrieve their information for various operations.

### Basic Customer Retrieval

**Try it now:** [Fetch customers API →](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");

// Retrieve specific customers by ID
const customerIds = ['cust-digital-001'];
const encodedIds = encodeURIComponent(JSON.stringify(customerIds));

const requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch(`https://api.nue.io/customers?customerIds=${encodedIds}`, requestOptions)
  .then(response => response.json())
  .then(result => {
    console.log('Customer information:', result);
    
    // Display customer details
    result.data.forEach(customer => {
      console.log(`Customer: ${customer.name}`);
      console.log(`Email: ${customer.email}`);
      console.log(`ARR: $${customer.todayARR || 0}`);
    });
  })
  .catch(error => console.log('error', error));
```

### Including Contact Information

You can also retrieve customers with their associated contacts in a single call:

**Try it now:** [Fetch customers API →](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");

// Retrieve customer with contacts in one call
const customerIds = ['cust-digital-001'];
const encodedIds = encodeURIComponent(JSON.stringify(customerIds));

const requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch(`https://api.nue.io/customers?customerIds=${encodedIds}&includes=contacts`, requestOptions)
  .then(response => response.json())
  .then(result => {
    console.log('Customer with contacts:', result);
    
    result.data.forEach(customer => {
      console.log(`Customer: ${customer.name}`);
      
      // Display contacts if available
      if (customer.contacts && customer.contacts.length > 0) {
        console.log('Contacts:');
        customer.contacts.forEach(contact => {
          console.log(`  - ${contact.firstName} ${contact.lastName} (${contact.email})`);
        });
      } else {
        console.log('No contacts found');
      }
    });
  })
  .catch(error => console.log('error', error));
```

## Updating Customer Information

As customer information changes, you'll need to update their records. Use the PATCH endpoint to modify specific fields while preserving others.

### Basic Customer Update

**Try it now:** [Update customer API →](https://api-docs.nue.io/update-customer)

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

// Update customer contact information
const updateData = JSON.stringify({
  "email": "newemail@digitalinnovations.com",
  "phone": "+1-555-0199",
  "website": "https://digitalinnovations.com"
});

const customerId = 'cust-digital-001';

const requestOptions = {
  method: 'PATCH',
  headers: myHeaders,
  body: updateData,
  redirect: 'follow'
};

fetch(`https://api.nue.io/customers/${customerId}`, requestOptions)
  .then(response => response.json())
  .then(result => {
    console.log('Customer updated:', result);
  })
  .catch(error => console.log('error', error));
```

## Common Patterns and Best Practices

### 1. Error Handling

Always implement proper error handling for your customer operations:

```javascript
fetch(apiUrl, requestOptions)
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(result => {
    // Handle success
  })
  .catch(error => {
    console.error('API Error:', error);
    // Handle error appropriately
  });
```

### 2. Data Validation

Before sending requests, validate required fields:

```javascript
function validateCustomer(customer) {
  if (!customer.name || !customer.recordType) {
    throw new Error('Name and recordType are required');
  }
  
  if (!['Business', 'Consumer'].includes(customer.recordType)) {
    throw new Error('recordType must be Business or Consumer');
  }
  
  return true;
}
```

### 3. Storing Customer IDs

Always store the customer ID returned from creation for future operations:

```javascript
// After successful customer creation
const customerId = result.data[0].id;
localStorage.setItem('currentCustomerId', customerId);

// Later retrieval
const storedCustomerId = localStorage.getItem('currentCustomerId');
```

## Next Steps

Now that you understand basic customer management, you can:

- **Add contacts** to your customers using the contacts API
- **Create orders** for your customers to start the sales process
- **Explore advanced workflows** for complex business scenarios
- **Learn about customer data validation** and all available fields

Move on to **Advanced Customer Workflows** to learn about complex scenarios like bulk operations, integration monitoring, and sophisticated onboarding flows.