Customer Overview
In the Nue Self-Service API, a Customer represents an organization that purchases your products or services. This concept is equivalent to an Account in Salesforce, and the terms are often used interchangeably when discussing Nue's integration with Salesforce.
Core Customer Concepts
A Customer record serves as the foundation for all commercial relationships in Nue, storing essential information such as:
- Basic identification (name, account number)
- Contact information (addresses, phone, email)
- Billing details (payment methods, terms)
- Classification data (industry, type, size)
- Financial metrics (ARR, revenue, contract values)
The Customer object is designed to support both B2B and B2C business models, with flexible record types that can be configured to match your specific business needs.
Customer ID Management and External System Integration
Nue UUIDs vs External System IDs
Nue uses UUIDs (Universally Unique Identifiers) as the primary identifier for all Customer records. These UUIDs ensure global uniqueness and are the primary key used throughout the Nue platform.
Example Nue Customer ID: 20aa111d-b3e6-446b-8e94-1d9b3d39e9dd
The externalId Field
The externalId field is a critical component for integration with external systems, particularly Salesforce. This field stores the corresponding identifier from the external system, creating a mapping between Nue's internal UUID and the external system's ID format.
Key characteristics of externalId:
- Initially null when customers are created through the Self-Service API
- Populated automatically when the customer synchronizes with Salesforce
- Contains the Salesforce Account ID (typically 15 or 18 characters)
- Enables bidirectional synchronization between Nue and Salesforce
- Used for data consistency and integration workflows
Example Salesforce Account ID: 001Ot00000mx5KzIAI
ID Lifecycle Example
// 1. Customer created in Nue Self-Service
{
"id": "20aa111d-b3e6-446b-8e94-1d9b3d39e9dd",
"name": "Digital Innovations LLC",
"externalId": null, // No Salesforce sync yet
"type": "Prospect"
}
// 2. After first order activation and Salesforce sync
{
"id": "20aa111d-b3e6-446b-8e94-1d9b3d39e9dd",
"name": "Digital Innovations LLC",
"externalId": "001Ot00000mx5KzIAI", // Now contains Salesforce Account ID
"type": "Direct Customer"
}Integration Benefits
This dual-ID system provides several advantages:
- System Independence: Nue can operate independently while maintaining external system relationships
- Data Migration: Enables smooth migration between systems without losing relationships
- API Flexibility: Both Nue UUIDs and external IDs can be used for lookups and operations
- Audit Trail: Clear tracking of which records have been synchronized across systems
- Conflict Resolution: Helps resolve data discrepancies between integrated systems
Customer Lifecycle Stages
Understanding the customer lifecycle in Nue helps you implement the right workflows:
1. Prospect Stage
- Customer record exists in Nue only
- externalId field is null (no Salesforce synchronization yet)
- Limited billing/payment information
- Customer type typically set to "Prospect"
2. Active Customer Stage
- First order has been activated
- Automatic synchronization to Salesforce occurs
- externalId field populated with Salesforce Account ID
- Full billing and subscription management available
- Complete customer relationship established
3. Customer Management Stage
- Ongoing updates and maintenance
- Order modifications and renewals
- Full integration with external systems
- Comprehensive reporting and analytics
Customer-Salesforce Account Relationship
For organizations using Nue with Salesforce integration, understanding how Customer records in Nue relate to Account records in Salesforce is crucial for maintaining data integrity and optimizing your sales operations.
Data Source and Authority
When your Nue instance is connected to Salesforce, Customer records are designed to work seamlessly with your existing Salesforce infrastructure.
Synchronization Strategies
Nue supports two distinct synchronization approaches, allowing you to choose the strategy that best fits your business model:
Selective Synchronization (Default Behavior)
By default, Customer records created through the Self-Service API don't immediately sync to Salesforce. Instead, synchronization is triggered only when meaningful business activity occurs—specifically when the first order is activated for that customer.
This selective approach provides several strategic advantages:
- Prevents Salesforce data pollution by avoiding the creation of Account records for prospects who haven't yet made a purchase commitment
- Maintains a clear distinction between marketing leads/prospects and actual paying customers in your Salesforce org
- Optimizes your Salesforce environment by ensuring that only customers with real business value appear in your sales and customer management workflows
- Reduces CRM clutter and helps your sales teams focus on genuine customer relationships
Continuous Bidirectional Sync (Optional Configuration)
Organizations requiring real-time data synchronization can enable immediate bidirectional synchronization through a specialized configuration setting. When this option is activated:
- Customer records created via the Self-Service API instantly synchronize with Salesforce, automatically generating corresponding Account records
- Account modifications in Salesforce immediately sync back to the Nue customer record, ensuring both systems remain perfectly aligned
- Real-time data consistency is maintained across both platforms, ideal for organizations with complex sales processes or multiple customer touchpoints
This approach is particularly valuable for businesses that need immediate visibility into self-service customer creation within their existing Salesforce workflows and reporting structures.
More details can be found here.
Customer Data Architecture
Core Relationships
Customers in Nue connect to several other key objects:
- Contacts: Individual people associated with the customer organization
- Orders: Purchase transactions and configurations
- Invoices: Generated based on selected billing cycle
- Subscriptions: Ongoing service agreements
- Physica Assets: Physical or virtual products delivered
- Entitlements: Access rights and usage permissions
Data Integration Points
Customer data flows through multiple systems:
- Salesforce: Master customer relationship management
- Payment Systems: Payment processing
- Analytics Platforms: Business intelligence and reporting
Understanding these relationships helps you design effective customer management workflows and troubleshoot integration issues.
Next Steps
Now that you understand the core customer concepts, you can move on to:
- Getting Started with Customer Management - Learn basic CRUD operations
- Advanced Customer Workflows - Implement complex business scenarios
- Customer Data Reference - Understand all available fields and validation rules