---
title: Contact Overview
slug: contact-overview
createdAt: 2026-02-13T04:24:46.989Z
---

In the Nue Self-Service API, a **Contact** represents an individual person associated with a Customer organization. While the Customer object represents an organization or account, Contacts represent the people within that organization who interact with your services, make decisions, and manage relationships.

## Core Contact Concepts

A Contact record serves as the bridge between your platform and the individuals within customer organizations, enabling:

- **Individual Identity Management** - Unique profiles for each person
- **Role-Based Access Control** - Different permissions based on contact roles
- **Personalized Communications** - Targeted messaging to specific individuals
- **Order and Billing Management** - Designated contacts for different business functions
- **Authentication and Portal Access** - Individual login credentials for self-service portals

The Contact object is designed to support complex organizational structures while maintaining individual accountability and personalization.

## Contact ID Management and External System Integration

### Nue UUIDs vs External System IDs

Like Customers, Nue uses **UUIDs (Universally Unique Identifiers)** as the primary identifier for all Contact records. These UUIDs ensure global uniqueness and are the primary key used throughout the Nue platform.

**Example Nue Contact ID**: `e96ebe1b-7fe1-4bd3-8f2e-81f4a4883f97`

### The externalId Field for Contacts

Contacts also have an `externalId` field that stores the corresponding identifier from external systems, particularly Salesforce Contact IDs. This enables seamless integration and data synchronization.

**Key characteristics of Contact externalId:**

- **Initially null** when contacts are created through the Self-Service API
- **Populated automatically** when the contact synchronizes with Salesforce
- **Contains the Salesforce Contact ID** (typically 15 or 18 characters)
- **Enables bidirectional synchronization** between Nue and Salesforce
- **Used for maintaining relationships** across integrated systems

**Example Salesforce Contact ID**: `003Ot00001mx7PzIAI`

### Contact-Customer Relationship

Every Contact must be associated with a Customer through the `customerId` field, creating a clear organizational hierarchy:

```javascript
// Contact belongs to Customer
{
  "id": "e96ebe1b-7fe1-4bd3-8f2e-81f4a4883f97",
  "name": "John Smith",
  "email": "john.smith@company.com",
  "customerId": "cc5e1f0f-5e14-48cc-ab98-9e5b191aa46f",
  "externalId": null  // Not yet synced to Salesforce
}
```

## Contact Lifecycle Stages

Understanding the contact lifecycle helps you implement the right workflows:

### 1. Contact Creation Stage

- Contact record created for a Customer
- `externalId` field is null (no Salesforce synchronization yet)
- Available for self-service portal access and basic operations
- Email serves as unique identifier within the organization

### 2. Contact Activation Stage

- Contact begins using self-service features
- Profile information gets enriched with usage data
- May be designated for specific roles (billing contact, technical contact, etc.)
- Ready for order placement and customer interactions

### 3. Contact Synchronization Stage

- When customer places first order, contact data syncs to Salesforce
- `externalId` field populated with Salesforce Contact ID
- Full CRM integration becomes available
- Bidirectional sync maintains data consistency

## Contact-Salesforce Integration

For organizations using Nue with Salesforce integration, understanding how Contact records synchronize is crucial for maintaining data integrity.

### Synchronization Behavior

**Selective Synchronization (Default):**

- Contacts created via Self-Service API don't immediately sync to Salesforce
- Synchronization occurs when the associated customer places their first order
- Prevents Salesforce Contact pollution from prospect organizations
- Maintains clean CRM data focused on active customers

## Contact Data Architecture

### Core Relationships

Contacts in Nue connect to several key objects:

- **Customer**: Parent organization (required relationship)
- **Orders**: Contacts can be designated as order contacts for billing or shipping
- **User Authentication**: Email addresses can serve as login identifiers
- **Communications**: Target for personalized messaging and notifications

### Contact Roles and Permissions

While not explicitly defined in the API, contacts often serve different roles within organizations:

- **Primary Contact**: Main point of contact for the customer relationship
- **Billing Contact**: Handles invoicing and payment-related communications
- **Technical Contact**: Manages technical aspects and integrations
- **Administrative Contact**: Handles user management and account administration
- **Order Contact**: Authorized to place and approve orders

### Data Integration Points

Contact data flows through multiple systems:

- **Salesforce**: Master contact relationship management
- **Authentication Systems**: User login and access control
- **Communication Platforms**: Email marketing and transactional messaging
- **Analytics Platforms**: Usage tracking and engagement metrics

## Next Steps

Now that you understand the core contact concepts, you can move on to:

- **Getting Started with Contact Management** - Learn basic CRUD operations for contacts
- **Advanced Contact Workflows** - Implement complex contact scenarios and bulk operations
- **Contact Data Reference** - Understand all available fields and validation rules

You can also explore the Customer documentation to understand the parent-child relationship between customers and contacts.
