Getting Started with Customer Management

13 min

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:

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 →

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": "[email protected]",
    "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 →

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 →

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 →

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": "[email protected]",
  "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:

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:

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:

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