Getting Started with Contact Management

11 min

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

Prerequisites

Before you begin, ensure you have:

A valid Nue API key

Access to the Nue Lifecycle Manager API

Basic understanding of REST APIs and JSON

At least one Customer record in your system (contacts must be associated with customers)

Authentication

All contact 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 Contact

Contacts must always be created under a specific Customer. This establishes the organizational relationship and ensures proper data hierarchy.

Basic Contact Creation

Try it now: Create Contact for Customer

Required vs Optional Fields

When creating a contact, several fields are required:

firstName (required): The contact's first name

lastName (required): The contact's last name

name (required): The contact's full name

email (required): Unique email address for the contact

Optional but commonly used fields include:

title: Job title or position

phone: Primary phone number

mobilePhone: Mobile phone number

Address fields: For shipping and billing purposes

Retrieving Contact Information

You can retrieve contacts using their email addresses, which is particularly useful for authentication and lookup scenarios.

Retrieve Contacts by Email

Try it now: Fetch Contact by Emails

Retrieve Contacts with Customer Information

You can also retrieve customers with their associated contacts using the includes=contacts parameter on the customer endpoint:

// Retrieve customer with all contacts
const customerIds = ['cc5e1f0f-5e14-48cc-ab98-9e5b191aa46f'];
const encodedIds = encodeURIComponent(JSON.stringify(customerIds));

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

Updating Contact Information

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

Basic Contact Update

Try it now: Update Contact

Common Patterns and Best Practices

1. Error Handling

Always implement proper error handling for your contact operations:

fetch(apiUrl, requestOptions)
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(result => {
    if (result.status === 'SUCCESS') {
      // Handle success
      console.log('Operation successful:', result.data);
    } else {
      // Handle API-level errors
      console.error('API Error:', result.message);
    }
  })
  .catch(error => {
    console.error('Network Error:', error);
  });

2. Email Validation

Before creating contacts, validate email addresses:

function validateEmail(email) {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return emailRegex.test(email);
}

function validateContact(contact) {
  if (!contact.firstName || !contact.lastName || !contact.name || !contact.email) {
    throw new Error('firstName, lastName, name, and email are required');
  }
  
  if (!validateEmail(contact.email)) {
    throw new Error('Invalid email format');
  }
  
  return true;
}

3. Storing Contact IDs

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

// After successful contact creation
const contactId = result.data[0].id;
localStorage.setItem('currentContactId', contactId);

// Later retrieval
const storedContactId = localStorage.getItem('currentContactId');

Next Steps

Now that you understand basic contact management, you can:

Explore customer-contact relationships to understand organizational hierarchies

Learn about contact roles and permissions for self-service portals

Implement advanced contact workflows for complex business scenarios

Study contact data validation and all available fields

Move on to Advanced Contact Workflows to learn about complex scenarios like bulk operations, contact role management, and integration patterns.