Customer Data Reference

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