---
title: Contact Data Reference
slug: contact-data-reference
docTags: 
createdAt: 2026-02-13T04:24:47.814Z
---

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

## Core Identification Fields

These fields uniquely identify and establish relationships for your contact records:

### Required Fields

| Field         | Type   | Description           | Example                       | Notes                                        |
| ------------- | ------ | --------------------- | ----------------------------- | -------------------------------------------- |
| **firstName** | String | Contact's first name  | `"Sarah"`                     | Required, max 40 characters                  |
| **lastName**  | String | Contact's last name   | `"Johnson"`                   | Required, max 80 characters                  |
| **name**      | String | Full display name     | `"Sarah Johnson"`             | Required, max 255 characters                 |
| **email**     | String | Primary email address | `"sarah.johnson@company.com"` | Required, must be unique, valid email format |

### System-Generated Fields

| Field                | Type                | Description                         | Example                                  | Notes                     |
| -------------------- | ------------------- | ----------------------------------- | ---------------------------------------- | ------------------------- |
| **id**               | String (UUID)       | System-generated unique identifier  | `"e96ebe1b-7fe1-4bd3-8f2e-81f4a4883f97"` | Auto-generated, read-only |
| **createdDate**      | DateTime (ISO 8601) | Record creation timestamp           | `"2024-12-21T10:30:00Z"`                 | System-managed            |
| **lastModifiedDate** | DateTime (ISO 8601) | Last modification timestamp         | `"2024-12-21T11:45:00Z"`                 | System-managed            |
| **createdById**      | String (UUID)       | ID of user who created record       | `"74ef82c9-a9d7-4262-8331-ba7ac33d1f76"` | System-managed            |
| **lastModifiedById** | String (UUID)       | ID of user who last modified record | `"74ef82c9-a9d7-4262-8331-ba7ac33d1f76"` | System-managed            |

### Relationship Fields

| Field          | Type          | Description                | Example                                  | Notes                                       |
| -------------- | ------------- | -------------------------- | ---------------------------------------- | ------------------------------------------- |
| **customerId** | String (UUID) | Parent customer identifier | `"cc5e1f0f-5e14-48cc-ab98-9e5b191aa46f"` | Required, establishes customer relationship |

### External System Integration

| Field          | Type              | Description                                                  | Example                | Notes                          |
| -------------- | ----------------- | ------------------------------------------------------------ | ---------------------- | ------------------------------ |
| **externalId** | String (Nullable) | External system identifier (typically Salesforce Contact ID) | `"003Ot00001mx7PzIAI"` | See detailed explanation below |

### Understanding the externalId Field for Contacts

The `externalId` field for contacts works similarly to customer externalId, storing the Salesforce Contact ID for integration purposes:

**Field Characteristics:**

- **Data Type**: String (nullable)
- **Initial Value**: `null` when contact is created via Self-Service API
- **Population**: Automatically set when contact syncs to Salesforce
- **Format**: Salesforce Contact ID (15 or 18 character alphanumeric)
- **Read-Only**: Cannot be manually set via API

**Lifecycle States:**

1. **Prospect State** (`externalId: null`)
   - Contact exists only in Nue
   - No external system synchronization
   - Typical for new self-service contacts
2. **Synchronized State** (`externalId: "003Ot00001mx7PzIAI"`)
   - Contact has been synchronized to Salesforce
   - External ID contains the Salesforce Contact ID
   - Bidirectional sync is active

## Personal Information Fields

Essential personal details for individual identification and communication:

| Field          | Type       | Description            | Example                      | Validation                             |
| -------------- | ---------- | ---------------------- | ---------------------------- | -------------------------------------- |
| **middleName** | String     | Middle name or initial | `"Marie"`                    | Optional, max 40 characters            |
| **suffix**     | String     | Name suffix            | `"Jr."`, `"III"`, `"PhD"`    | Optional, max 10 characters            |
| **title**      | String     | Job title or position  | `"Chief Technology Officer"` | Optional, max 128 characters           |
| **birthday**   | Date (ISO) | Date of birth          | `"1985-04-15"`               | Optional, ISO date format (YYYY-MM-DD) |

### Name Field Best Practices

- **firstName**: First/given name only
- **lastName**: Surname/family name only
- **name**: Can be auto-generated from firstName + lastName or manually set
- **middleName**: Middle name, initial, or multiple middle names
- **suffix**: Professional or generational suffixes

## Contact Information Fields

Communication details for reaching and corresponding with contacts:

| Field           | Type   | Description              | Format/Example  | Validation                  |
| --------------- | ------ | ------------------------ | --------------- | --------------------------- |
| **phone**       | String | Primary phone number     | `"+1-555-0123"` | Optional, max 40 characters |
| **mobilePhone** | String | Mobile/cell phone number | `"+1-555-0124"` | Optional, max 40 characters |
| **homePhone**   | String | Home phone number        | `"+1-555-0125"` | Optional, max 40 characters |
| **fax**         | String | Fax number               | `"+1-555-0126"` | Optional, max 40 characters |

### Email Validation Rules

- Must be a valid email format (contains @ and domain)
- Maximum length: 255 characters
- Must be unique across the entire Nue platform
- Used for authentication and communication
- Cannot be duplicated between contacts

### 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
- Consider mobile-first for self-service notifications

## Address Information

Comprehensive address management for shipping and billing operations:

### Shipping Address Fields

| Field                  | Type   | Description                 | Example                       | Max Length |
| ---------------------- | ------ | --------------------------- | ----------------------------- | ---------- |
| **shippingStreet**     | String | Street address for delivery | `"456 Delivery Lane, Apt 5B"` | 255 chars  |
| **shippingCity**       | String | City name                   | `"New York"`                  | 40 chars   |
| **shippingState**      | String | State or province code      | `"NY"`                        | 80 chars   |
| **shippingPostalCode** | String | ZIP or postal code          | `"10001"`                     | 20 chars   |
| **shippingCountry**    | String | Country name                | `"United States"`             | 80 chars   |

### 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"`                  | 40 chars   |
| **billingState**      | String | State or province code     | `"CA"`                             | 80 chars   |
| **billingPostalCode** | String | ZIP or postal code         | `"94105"`                          | 20 chars   |
| **billingCountry**    | String | Country name               | `"United States"`                  | 80 chars   |

### Address Validation Notes

- Shipping address is used for product delivery
- Billing address may be used for financial communications
- If no billing address is provided, customer billing address is typically used
- Country names should be spelled out (not ISO codes)
- State/province can be full name or abbreviation

## Communication Preferences

Fields for managing how contacts prefer to be contacted:

| Field                  | Type    | Description               | Example Values  | Notes            |
| ---------------------- | ------- | ------------------------- | --------------- | ---------------- |
| **hasOptedOutOfEmail** | Boolean | Email opt-out status      | `true`, `false` | Default: `false` |
| **doNotCall**          | Boolean | Phone call opt-out status | `true`, `false` | Default: `false` |

### Communication Preference Best Practices

- Always respect opt-out preferences
- Consider implementing granular communication preferences
- Maintain audit trail of preference changes
- Comply with regional regulations (GDPR, CAN-SPAM, etc.)

## Role and Permission Management

While not explicitly defined in the API, these patterns help organize contact roles:

### Common Role Classifications

| Role Type          | Title Examples                   | Typical Responsibilities                             |
| ------------------ | -------------------------------- | ---------------------------------------------------- |
| **Executive**      | CEO, President, Owner            | Full admin access, order approval, billing oversight |
| **Financial**      | CFO, Controller, Finance Manager | Billing management, payment oversight                |
| **Technical**      | CTO, IT Director, DevOps Lead    | Technical integration, system management             |
| **Administrative** | Admin, Office Manager, Assistant | User management, general administration              |
| **Operational**    | VP Operations, Project Manager   | Day-to-day operations, team management               |
| **Standard User**  | Analyst, Coordinator, Specialist | Basic access, limited permissions                    |

### Permission Patterns

Based on contact titles and roles, you might implement these permission patterns:

```javascript
// Example permission mapping
const getPermissions = (contact) => {
  const title = contact.title?.toLowerCase() || '';
  
  if (title.includes('ceo') || title.includes('president')) {
    return ['admin', 'billing', 'orders', 'users', 'settings'];
  } else if (title.includes('cfo') || title.includes('financial')) {
    return ['billing', 'orders', 'reports'];
  } else if (title.includes('cto') || title.includes('technical')) {
    return ['technical', 'integrations', 'users'];
  } else if (title.includes('manager') || title.includes('director')) {
    return ['orders', 'reports', 'team'];
  } else {
    return ['basic', 'profile'];
  }
};
```

## Data Validation Rules

### Required Field Validation

- **firstName**: Cannot be empty or null
- **lastName**: Cannot be empty or null
- **name**: Cannot be empty or null
- **email**: Cannot be empty or null, must be valid format
- **customerId**: Must reference an existing customer

### Format Validation

- **email**: Must be valid email format with @ and domain
- **birthday**: Must be valid ISO date format (YYYY-MM-DD) if provided
- **phone numbers**: No specific format required, but consistent formatting recommended

### String Length Limits

- **firstName**: 40 characters maximum
- **lastName**: 80 characters maximum
- **name**: 255 characters maximum
- **email**: 255 characters maximum
- **title**: 128 characters maximum
- **phone fields**: 40 characters maximum
- **address fields**: Various limits (see address section above)

### Uniqueness Constraints

- **id**: System-generated UUID, guaranteed unique

## API Response Examples

### Contacts Array Response (from Customer endpoint)

```json
{
  "status": "SUCCESS",
  "data": [
    {
      "id": "cc5e1f0f-5e14-48cc-ab98-9e5b191aa46f",
      "name": "TechInnovate Solutions",
      "contacts": [
        {
          "id": "e96ebe1b-7fe1-4bd3-8f2e-81f4a4883f97",
          "firstName": "Sarah",
          "lastName": "Johnson",
          "name": "Sarah Johnson", 
          "email": "sarah.johnson@company.com",
          "title": "Chief Technology Officer",
          "customerId": "cc5e1f0f-5e14-48cc-ab98-9e5b191aa46f"
        },
        {
          "id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
          "firstName": "Michael",
          "lastName": "Chen", 
          "name": "Michael Chen",
          "email": "michael.chen@company.com",
          "title": "VP of Operations",
          "customerId": "cc5e1f0f-5e14-48cc-ab98-9e5b191aa46f"
        }
      ]
    }
  ]
}
```

## Error Responses

### Validation Error Example

```json
{
  "status": "FAILURE",
  "errorType": "INVALID_PARAMETER", 
  "message": "Validation failed for contact creation",
  "details": [
    {
      "field": "email",
      "message": "Email is required and must be valid"
    },
    {
      "field": "firstName", 
      "message": "First name is required"
    },
    {
      "field": "lastName",
      "message": "Last name cannot exceed 80 characters"
    }
  ]
}
```

### Common Error Codes

- **400**: Bad Request - Validation errors or malformed data
- **401**: Unauthorized - Invalid or missing API key
- **404**: Not Found - Contact ID or Customer ID doesn't exist
- **409**: Conflict - Duplicate email address
- **429**: Rate Limited - Too many requests
- **500**: Server Error - Internal system error

## Best Practices Summary

1. **Always validate required fields** before sending requests
2. **Ensure email uniqueness** across your application
3. **Use consistent phone number formats** for better usability
4. **Store Nue UUIDs** as the primary contact identifier for all operations
5. **Check externalId status** to determine sync state and available features
6. **Implement proper error handling** for validation and duplicate email scenarios
7. **Consider role-based permissions** based on contact titles and positions
8. **Respect communication preferences** and opt-out settings
9. **Plan for customer-contact relationships** in your data architecture
10. **Use the includes=contacts parameter** for efficient data loading
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 contact data management in the Nue Self-Service API. Use it alongside the other contact guides for comprehensive implementation guidance.