---
title: Customer Data Reference
slug: customer-data-reference
docTags: 
createdAt: 2026-02-13T04:24:47.548Z
---

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:**

1. **Prospect State** (`externalId: null`)
   - Customer exists only in Nue
   - No external system synchronization
   - Typical for new self-service signups
2. **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:**

```javascript
// 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        | `"contact@company.com"` | 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

```javascript
// Example customer creation with custom fields
const customerData = {
  "name": "Innovation Corp",
  "recordType": "Business",
  "email": "contact@innovation.com",
  // 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](https://docs.nue.io/manage-custom-fields) 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)

```json
{
  "id": "e7f8a9b2-c3d4-4e5f-9876-123456789abc",
  "name": "StartupTech Inc",
  "recordType": "Business",
  "accountNumber": "ACC-2024-002",
  "email": "hello@startuptech.io",
  "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)

```json
{
  "id": "20aa111d-b3e6-446b-8e94-1d9b3d39e9dd",
  "name": "Digital Innovations LLC",
  "recordType": "Business",
  "accountNumber": "ACC-2024-001",
  "email": "contact@digitalinnovations.com",
  "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

```json
{
  "id": "74ef82c9-a9d7-4262-8331-ba7ac33d1f76",
  "name": "Digital Innovations LLC",
  "email": "contact@digitalinnovations.com",
  "contacts": [
    {
      "id": "contact-456",
      "firstName": "Alex",
      "lastName": "Thompson",
      "email": "alex.thompson@digitalinnovations.com",
      "title": "CEO",
      "isPrimary": true,
      "customerId": "cust-123abc"
    }
  ]
}
```

## Error Responses

### Validation Error Example

```json
{
  "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

1. **Always validate required fields** before sending requests
2. **Use consistent data formats** (especially for phone numbers and addresses)
3. **Implement proper error handling** for all validation scenarios
4. **Store Nue UUIDs** as the primary customer identifier for all operations
5. **Check externalId status** to determine sync state and available features
6. **Use custom fields** for business-specific data requirements
7. **Consider billing address requirements** for tax calculation needs
8. **Plan for Salesforce synchronization** behavior in your workflows
9. **Monitor integration status** using externalId and transactionHubData endpoints
10. **Use includes=contacts** parameter for performance optimization
11. **Implement retry logic** for resilient production systems
12. **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.