Contact Data Reference

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