Customer Data Reference

31 min

This comprehensive reference covers all customer fields, validation rules, data types, and constraints. Use this guide when implementing customer data collection, validation, and management features.

Core Identification Fields

These fields uniquely identify and classify your customer records:

Required Fields

Field	Type	Description	Example	Notes
name	String	The display name of the customer organization or individual	"Digital Innovations LLC"	Required for all customers
recordType	String	Customer classification	"Business" or "Consumer"	Must be one of two values

System-Generated Fields

Field	Type	Description	Example	Notes
id	String (UUID)	System-generated unique identifier	"74ef82c9-a9d7-4262-8331-ba7ac33d1f76"	Auto-generated, read-only
accountNumber	String	Auto-generated unique account identifier	"ACC-2024-001"	Auto-generated, human-readable
createdDate	DateTime (ISO 8601)	Record creation timestamp	"2024-12-21T10:30:00Z"	System-managed
modifiedDate	DateTime (ISO 8601)	Last modification timestamp	"2024-12-21T11:45:00Z"	System-managed

External System Integration

Field	Type	Description	Example	Notes
externalId	String (Nullable)	External system identifier (typically Salesforce Account ID)	"001Ot00000mx5KzIAI"	See detailed explanation below

Understanding the externalId Field

The externalId field is crucial for understanding customer synchronization status and external system relationships:

Field Characteristics:

Data Type: String (nullable)

Initial Value: null when customer is created via Self-Service API

Population: Automatically set when customer syncs to Salesforce

Format: Salesforce Account ID (15 or 18 character alphanumeric)

Read-Only: Cannot be manually set via API

Lifecycle States:

Prospect State (externalId: null)

Customer exists only in Nue

No external system synchronization

Typical for new self-service signups

Synchronized State (externalId: "001Ot00000mx5KzIAI")

Customer has been synchronized to Salesforce

External ID contains the Salesforce Account ID

Bidirectional sync is active

Integration Use Cases:

Status Checking: Determine if customer has synced to external systems

Data Mapping: Link Nue customers to Salesforce accounts

Conditional Logic: Apply different workflows based on sync status

Troubleshooting: Identify integration issues or discrepancies

Example Usage:

// Check if customer is synced to Salesforce
if (customer.externalId) {
  console.log(`Customer synced to Salesforce: ${customer.externalId}`);
  // Enable full CRM features
} else {
  console.log('Customer is prospect - not yet synced');
  // Limit to self-service features
}

Contact Information Fields

Essential communication details for customer outreach and correspondence:

Field	Type	Description	Format/Example	Validation
email	String	Primary email address	"[email protected]"	Valid email format
phone	String	Primary contact phone number	"+1-555-0123"	International format recommended
fax	String	Fax number	"+1-555-0124"	Optional
website	String	Company website URL	"https://company.com"	Valid URL format

Email Validation Rules

Must be a valid email format (contains @ and domain)

Maximum length: 255 characters

Used for system notifications and communication

Phone Number Best Practices

Recommended format: International with country code

Examples: "+1-555-0123", "+44-20-7946-0958"

No strict validation enforced, but consistent formatting improves usability

Address Information

Comprehensive address management for billing and shipping operations:

Billing Address Fields

Field	Type	Description	Example	Max Length
billingStreet	String	Street address for billing	"123 Business Avenue, Suite 100"	255 chars
billingCity	String	City name	"San Francisco"	100 chars
billingState	String	State or province code	"CA"	50 chars
billingPostalCode	String	ZIP or postal code	"94105"	20 chars
billingCountry	String	Country name	"United States"	100 chars

Shipping Address Fields

Field	Type	Description	Example	Max Length
shippingStreet	String	Street address for delivery	"456 Delivery Lane"	255 chars
shippingCity	String	City name	"New York"	100 chars
shippingState	String	State or province code	"NY"	50 chars
shippingPostalCode	String	ZIP or postal code	"10001"	20 chars
shippingCountry	String	Country name	"United States"	100 chars

Address Validation Notes

If shipping address is not provided, tax calculation will fail

State/province can be full name or abbreviation

Business Classification and Segmentation

Fields for categorizing and segmenting customers for targeted business strategies:

Field	Type	Description	Example Values	Notes
industry	String	Industry sector classification	"Technology", "Manufacturing", "Healthcare"	Used for segmentation
type	String	Customer relationship type	"Prospect", "Direct Customer", "Channel Partner"	Tracks relationship stage
ownership	String	Business ownership structure	"Public", "Private", "Subsidiary", "Other"	Business classification
companySize	String	General size classification	"Small", "Medium", "Large", "Enterprise"	Flexible categorization
numberOfEmployees	Integer	Specific employee count	250	Used for precise sizing
annualRevenue	Decimal	Customer's reported annual revenue	50000000.00	Used for segmentation

Industry Standard Values

Common industry values include:

"Technology"

"Manufacturing"

"Healthcare"

"Financial Services"

"Retail"

"Education"

"Government"

"Non-Profit"

Customer Type Lifecycle

Prospect: Initial stage, not yet purchased

Direct Customer: Active customer with orders

Channel Partner: Reseller or distributor

Former Customer: Previously active, now inactive

Financial and Billing Configuration

Critical fields for managing payment processing, billing cycles, and financial operations:

Payment Configuration

Field	Type	Description	Valid Values	Default
paymentTerm	String	Payment terms	"Net 15", "Net 30", "Net 45", "Net 60"	"Net 30"

Billing Cycle Management

Field	Type	Description	Valid Range	Notes
billCycleDay	Integer	Day of month for billing	1-31	If day doesn't exist in month, uses last day
billCycleStartMonth	String	Starting month for annual cycles	"01" - January, "02" - February, etc.	For annual billing
billingProrationEnabled	Boolean	Enable proration calculations	true, false	Default: false

Financial Profile

Field	Type	Description	Example	Notes
taxExempt	Boolean	Tax exemption status	true, false	Affects tax calculations

Relationship and Hierarchy Management

Fields for managing complex customer relationships and organizational structures:

Field	Type	Description	Example	Use Case
parentCustomerId	String	Reference to parent customer	"20aa111d-b3e6-446b-8e94-1d9b3d39e9dd"	Enterprise hierarchies
orderPrimaryContactId	String	Primary contact for orders	"74ef82c9-a9d7-4262-8331-ba7ac33d1f76"	Order approvals
salesAccountId	String	Sales account identifier	"20aa111d-b3e6-446b-8e94-1d9b3d39e9dd"	Territory management

Hierarchy Best Practices

Use parent-child relationships for enterprise accounts with subsidiaries

Link primary contacts to streamline order processing

Sales account IDs help with territory and quota management

Revenue Metrics and Analytics

Real-time financial metrics calculated and maintained by the system:

Field	Type	Description	Example	Calculation
todayARR	Decimal	Annual Recurring Revenue as of today	120000.00	Auto-calculated from subscriptions
todayCMRR	Decimal	Committed Monthly Recurring Revenue	10000.00	Includes future committed revenue
totalTCV	Decimal	Total Contract Value	360000.00	Sum of all contract values

Revenue Metric Notes

These fields are read-only and automatically calculated

Values update in real-time as subscriptions and orders change

ARR calculation includes only active, recurring subscriptions

TCV includes one-time charges and total subscription values

Custom Fields in Self-Service

While Nue provides a rich set of standard fields, many businesses require additional fields to capture industry-specific or business-specific information.

Custom Field Naming Convention

Custom fields must follow the pattern: fieldName__c

Custom Field Implementation

// Example customer creation with custom fields
const customerData = {
  "name": "Innovation Corp",
  "recordType": "Business",
  "email": "[email protected]",
  // Standard fields...
  
  // Custom fields
  "leadSource__c": "Partner Program",
  "expectedCloseDate__c": "2024-12-31",
  "businessPriority__c": "High",
  "companyMaturity__c": "Growth Stage",
  "digitalTransformationStage__c": "Implementing"
};

Adding Custom Fields

To add custom fields to your Nue instance, please use this guide for step-by-step instructions.

Data Validation Rules

Required Field Validation

name: Cannot be empty or null

recordType: Must be exactly "Business" or "Consumer"

Format Validation

email: Must be valid email format if provided

website: Must be valid URL format if provided

billCycleDay: Must be integer between 1-31

numberOfEmployees: Must be positive integer if provided

annualRevenue: Must be positive decimal if provided

String Length Limits

name: 255 characters maximum

email: 255 characters maximum

phone: 50 characters maximum

website: 255 characters maximum

billingStreet: 255 characters maximum

industry: 100 characters maximum

API Response Examples

Prospect Customer Response (Before Salesforce Sync)

{
  "id": "e7f8a9b2-c3d4-4e5f-9876-123456789abc",
  "name": "StartupTech Inc",
  "recordType": "Business",
  "accountNumber": "ACC-2024-002",
  "email": "[email protected]",
  "phone": "+1-555-0200",
  "industry": "Technology",
  "type": "Prospect",
  "billingStreet": "456 Innovation Drive",
  "billingCity": "Austin",
  "billingState": "TX",
  "billingPostalCode": "78701",
  "billingCountry": "United States",
  "paymentTerm": "Net 30",
  "todayARR": 0,
  "externalId": null,
  "createdDate": "2024-12-21T09:15:00Z",
  "modifiedDate": "2024-12-21T09:15:00Z"
}

Active Customer Response (After Salesforce Sync)

{
  "id": "20aa111d-b3e6-446b-8e94-1d9b3d39e9dd",
  "name": "Digital Innovations LLC",
  "recordType": "Business",
  "accountNumber": "ACC-2024-001",
  "email": "[email protected]",
  "phone": "+1-555-0100",
  "industry": "Technology",
  "type": "Direct Customer",
  "billingStreet": "123 Tech Avenue",
  "billingCity": "San Francisco",
  "billingState": "CA",
  "billingPostalCode": "94105",
  "billingCountry": "United States",
  "paymentTerm": "Net 30",
  "todayARR": 48000.00,
  "externalId": "001Ot00000mx5KzIAI",
  "createdDate": "2024-12-21T10:30:00Z",
  "modifiedDate": "2024-12-21T11:45:00Z"
}

Customer with Contacts Response

{
  "id": "74ef82c9-a9d7-4262-8331-ba7ac33d1f76",
  "name": "Digital Innovations LLC",
  "email": "[email protected]",
  "contacts": [
    {
      "id": "contact-456",
      "firstName": "Alex",
      "lastName": "Thompson",
      "email": "[email protected]",
      "title": "CEO",
      "isPrimary": true,
      "customerId": "cust-123abc"
    }
  ]
}

Error Responses

Validation Error Example

{
  "error": "Validation failed",
  "details": [
    {
      "field": "name",
      "message": "Customer name is required"
    },
    {
      "field": "recordType",
      "message": "Record type must be 'Business' or 'Consumer'"
    },
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

Common Error Codes

400: Bad Request - Validation errors or malformed data

401: Unauthorized - Invalid or missing API key

404: Not Found - Customer ID doesn't exist

409: Conflict - Duplicate data or constraint violation

429: Rate Limited - Too many requests

500: Server Error - Internal system error

Best Practices Summary

Always validate required fields before sending requests

Use consistent data formats (especially for phone numbers and addresses)

Implement proper error handling for all validation scenarios

Store Nue UUIDs as the primary customer identifier for all operations

Check externalId status to determine sync state and available features

Use custom fields for business-specific data requirements

Consider billing address requirements for tax calculation needs

Plan for Salesforce synchronization behavior in your workflows

Monitor integration status using externalId and transactionHubData endpoints

Use includes=contacts parameter for performance optimization

Implement retry logic for resilient production systems

Never attempt to manually set externalId - it's automatically managed by the system

This reference provides the complete specification for customer data management in the Nue Self-Service API. Use it alongside the other customer guides for comprehensive implementation guidance.