---
title: Getting Started with Contact Management
slug: getting-started-with-contact-management
docTags: 
createdAt: 2026-02-13T04:24:48.079Z
---

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:

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

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

## Common Patterns and Best Practices

### 1. Error Handling

Always implement proper error handling for your contact operations:

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

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

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