Contact Data Reference

24 min

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	"[email protected]"	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:

Prospect State (externalId: null)

Contact exists only in Nue

No external system synchronization

Typical for new self-service contacts

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:

// 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)

{
  "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": "[email protected]",
          "title": "Chief Technology Officer",
          "customerId": "cc5e1f0f-5e14-48cc-ab98-9e5b191aa46f"
        },
        {
          "id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
          "firstName": "Michael",
          "lastName": "Chen", 
          "name": "Michael Chen",
          "email": "[email protected]",
          "title": "VP of Operations",
          "customerId": "cc5e1f0f-5e14-48cc-ab98-9e5b191aa46f"
        }
      ]
    }
  ]
}

Error Responses

Validation Error Example

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

Always validate required fields before sending requests

Ensure email uniqueness across your application

Use consistent phone number formats for better usability

Store Nue UUIDs as the primary contact identifier for all operations

Check externalId status to determine sync state and available features

Implement proper error handling for validation and duplicate email scenarios

Consider role-based permissions based on contact titles and positions

Respect communication preferences and opt-out settings

Plan for customer-contact relationships in your data architecture

Use the includes=contacts parameter for efficient data loading

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 contact data management in the Nue Self-Service API. Use it alongside the other contact guides for comprehensive implementation guidance.