Creating Customers

this comprehensive guide covers creating customers using the nue lifecycle management api, including single and batch operations, advanced billing configurations, enterprise features, and complete error handling learn how to efficiently onboard customers with full data validation and integration capabilities prerequisites before you begin, ensure you have a valid nue api key with customer creation permissions understanding of customer data requirements and validation rules basic knowledge of rest apis and json familiarity with your business's customer onboarding process knowledge of batch processing limits (200 customers per request) understanding of your integration requirements (salesforce, stripe, etc ) authentication all customer creation operations require authentication using your nue api key in the nue api key header const myheaders = new headers(); myheaders append("nue api key", "your api key here"); myheaders append("content type", "application/json"); basic customer creation create single customer try it now create customers → https //api docs nue io/create customers const myheaders = new headers(); myheaders append("nue api key", "your api key here"); myheaders append("content type", "application/json"); // create a single customer with required fields const customerdata = \[{ name "acme corporation", recordtype "consumer" // required "consumer" or "business" }]; fetch('https //api nue io/customers', { method 'post', headers myheaders, body json stringify(customerdata) }) then(response => response json()) then(result => { if (result status === 'success') { console log('✅ customer created successfully'); const customer = result data\[0]; console log(`created ${customer name}`); console log(`customer id ${customer id}`); console log(`account number ${customer accountnumber}`); console log(`created date ${customer createddate}`); // check for warnings if (result warnings && result warnings length > 0) { console log('⚠️ warnings ', result warnings); } } else { console error('❌ customer creation failed ', result); } }) catch(error => console log('error ', error)); create customer with complete information create a customer with comprehensive business and billing details const comprehensivecustomer = \[{ // required fields name "techstart solutions inc ", recordtype "business", // business information legalentityname "techstart solutions incorporated", industry "technology", annualrevenue 5000000 00, description "leading technology solutions provider", funding "500000", type "customer", // customer, prospect, partner accountsource "web", // web, phone, email, referral // contact information email "billing\@techstart solutions com", phone "+1 555 0123", fax "+1 555 0124", website "https //techstart solutions com", timezone "america/new york", // billing configuration billcycleday "1st of month", // "1st of month", "7th of month", "15th of month", "last day of month" billcyclestartmonth "01", autorenew "yes", billingperiod "monthly", // monthly, quarterly, annual billingprorationenabled "yes", // billing address billingstreet "123 tech street", billingcity "san francisco", billingstate "ca", billingpostalcode "94105", billingcountry "united states", // shipping address (if different) shippingstreet "456 innovation ave", shippingcity "palo alto", shippingstate "ca", shippingpostalcode "94301", shippingcountry "united states", // additional information description "enterprise software company specializing in ai solutions", accountsource "web" }]; fetch('https //api nue io/customers', { method 'post', headers myheaders, body json stringify(comprehensivecustomer) }) then(response => response json()) then(result => { console log('comprehensive customer created ', result); const customer = result\[0]; console log(`\n✅ customer created successfully`); console log(`name ${customer name}`); console log(`id ${customer id}`); console log(`account number ${customer accountnumber}`); console log(`industry ${customer industry}`); console log(`bill cycle day ${customer billcycleday} of each month`); console log(`payment method ${customer paymentmethod}`); console log(`auto renew ${customer autorenew}`); }) catch(error => console log('error ', error)); bulk customer creation create multiple customers efficiently create multiple customers in a single api call const bulkcustomers = \[ { name "global enterprises llc", recordtype "business", industry "manufacturing", email "billing\@globalenterprises com", billcycleday 15, paymentmethod "ach", billingstreet "789 industrial blvd", billingcity "detroit", billingstate "mi", billingpostalcode "48201", billingcountry "united states" }, { name "startup innovations", recordtype "business", industry "technology", email "finance\@startupinnov com", billcycleday 1, paymentmethod "credit card", billingstreet "321 startup way", billingcity "austin", billingstate "tx", billingpostalcode "73301", billingcountry "united states" }, { name "john smith", recordtype "consumer", email "john smith\@email com", phone "+1 555 0199", billcycleday 1, paymentmethod "credit card", billingstreet "456 main street", billingcity "denver", billingstate "co", billingpostalcode "80202", billingcountry "united states" } ]; fetch('https //api nue io/customers', { method 'post', headers myheaders, body json stringify(bulkcustomers) }) then(response => response json()) then(customers => { console log(`\n✅ successfully created ${customers length} customers `); customers foreach((customer, index) => { console log(`\n${index + 1} ${customer name}`); console log(` id ${customer id}`); console log(` account ${customer accountnumber}`); console log(` type ${customer recordtype}`); console log(` email ${customer email}`); console log(` billing day ${customer billcycleday} via ${customer paymentmethod}`); }); }) catch(error => console log('error ', error)); advanced customer creation patterns customer onboarding workflow implement a complete customer onboarding process class customeronboardingservice { constructor(apikey) { this apikey = apikey; this headers = new headers(); this headers append("nue api key", apikey); this headers append("content type", "application/json"); } async onboardnewcustomer(customerinput) { try { // step 1 validate customer data const validateddata = this validatecustomerdata(customerinput); // step 2 enrich with defaults const enricheddata = this enrichcustomerdata(validateddata); // step 3 create customer const createdcustomer = await this createcustomer(enricheddata); // step 4 set up additional configurations await this setupcustomerconfigurations(createdcustomer); // step 5 send welcome communications await this sendwelcomeemail(createdcustomer); return { success true, customer createdcustomer, message `customer ${createdcustomer name} onboarded successfully` }; } catch (error) { console error('onboarding failed ', error); return { success false, error error message, customerinput }; } } validatecustomerdata(input) { const errors = \[]; // required field validation if (!input name || input name trim() length === 0) { errors push('customer name is required'); } if (!input recordtype || !\['consumer', 'business'] includes(input recordtype)) { errors push('record type must be "consumer" or "business"'); } // email validation if (input email && !this isvalidemail(input email)) { errors push('invalid email format'); } // bill cycle day validation if (input billcycleday && (input billcycleday < 1 || input billcycleday > 31)) { errors push('bill cycle day must be between 1 and 31'); } if (errors length > 0) { throw new error(`validation failed ${errors join(', ')}`); } return input; } enrichcustomerdata(input) { // apply business defaults const enriched = { input, // default billing configuration billcycleday input billcycleday || 1, paymentterm input paymentterm || "net 30", autorenew input autorenew || "defaulttosubscriptionconfiguration", billingprorationenabled input billingprorationenabled || "yes", taxexempt input taxexempt || "none", accountsource input accountsource || "api", // set timezone if not provided timezone input timezone || this getdefaulttimezone(input billingstate), // set industry for business customers industry input recordtype === 'business' ? (input industry || 'other') undefined }; return enriched; } async createcustomer(customerdata) { const response = await fetch('https //api nue io/customers', { method 'post', headers this headers, body json stringify(\[customerdata]) }); if (!response ok) { throw new error(`customer creation failed ${response status} ${response statustext}`); } const customers = await response json(); return customers\[0]; } async setupcustomerconfigurations(customer) { // additional setup steps could include // setting up payment methods // configuring billing preferences // creating default contacts // setting up integrations console log(`setting up configurations for ${customer name} `); // example log setup completion console log(`✅ configurations completed for account ${customer accountnumber}`); } async sendwelcomeemail(customer) { // integration with email service console log(`📧 sending welcome email to ${customer email} `); // mock email service integration const emaildata = { to customer email, subject `welcome to nue, ${customer name}!`, template 'customer welcome', data { customername customer name, accountnumber customer accountnumber, billcycleday customer billcycleday, paymentmethod customer paymentmethod } }; // in real implementation, integrate with your email service console log(`✅ welcome email queued for ${customer email}`); } isvalidemail(email) { const emailregex = /^\[^\s@]+@\[^\s@]+\\ \[^\s@]+$/; return emailregex test(email); } getdefaulttimezone(state) { const timezonemap = { 'ca' 'america/los angeles', 'ny' 'america/new york', 'tx' 'america/chicago', 'fl' 'america/new york', 'il' 'america/chicago' }; return timezonemap\[state] || 'america/new york'; } } // usage example const onboardingservice = new customeronboardingservice("your api key here"); const newcustomerdata = { name "innovative solutions corp", recordtype "business", industry "consulting", email "billing\@innovative solutions com", phone "+1 555 0150", annualrevenue 2500000, numberofemployees 25, billingstreet "100 business plaza", billingcity "seattle", billingstate "wa", billingpostalcode "98101", billingcountry "united states", billcycleday 15, paymentmethod "ach" }; onboardingservice onboardnewcustomer(newcustomerdata) then(result => { if (result success) { console log('\n🎉 customer onboarding completed successfully!'); console log(`customer ${result customer name}`); console log(`account ${result customer accountnumber}`); console log(`id ${result customer id}`); } else { console error('❌ onboarding failed ', result error); } }); customer creation with validation implement comprehensive validation and error handling class customervalidator { static validate(customerdata) { const errors = \[]; // required fields if (!customerdata name? trim()) { errors push('name customer name is required'); } if (!\['consumer', 'business'] includes(customerdata recordtype)) { errors push('recordtype must be "consumer" or "business"'); } // email validation if (customerdata email && !this isvalidemail(customerdata email)) { errors push('email invalid email format'); } // phone validation if (customerdata phone && !this isvalidphone(customerdata phone)) { errors push('phone invalid phone format'); } // business specific validations if (customerdata recordtype === 'business') { if (customerdata annualrevenue && customerdata annualrevenue < 0) { errors push('annualrevenue must be a positive number'); } if (customerdata numberofemployees && customerdata numberofemployees < 1) { errors push('numberofemployees must be at least 1'); } } // billing validations if (customerdata billcycleday && (customerdata billcycleday < 1 || customerdata billcycleday > 31)) { errors push('billcycleday must be between 1 and 31'); } // address validation if (customerdata billingstreet && !customerdata billingcity) { errors push('billingcity required when billing street is provided'); } return { isvalid errors length === 0, errors }; } static isvalidemail(email) { const emailregex = /^\[^\s@]+@\[^\s@]+\\ \[^\s@]+$/; return emailregex test(email); } static isvalidphone(phone) { const phoneregex = /^\\+?\[\d\s\\ \\(\\)]{10,}$/; return phoneregex test(phone); } } async function createvalidatedcustomer(customerdata) { const myheaders = new headers(); myheaders append("nue api key", "your api key here"); myheaders append("content type", "application/json"); try { // validate input data const validation = customervalidator validate(customerdata); if (!validation isvalid) { throw new error(`validation failed \n${validation errors join('\n')}`); } // create customer const response = await fetch('https //api nue io/customers', { method 'post', headers myheaders, body json stringify(\[customerdata]) }); if (!response ok) { const errortext = await response text(); throw new error(`api error ${response status} ${errortext}`); } const customers = await response json(); const customer = customers\[0]; console log('✅ customer created and validated successfully '); console log(` name ${customer name}`); console log(` id ${customer id}`); console log(` account ${customer accountnumber}`); return customer; } catch (error) { console error('❌ customer creation failed ', error message); throw error; } } // usage with validation const customertocreate = { name "valid business corp", recordtype "business", email "billing\@validbusiness com", phone "+1 555 0100", industry "technology", billcycleday 1, billingstreet "123 valid street", billingcity "valid city", billingstate "ca", billingpostalcode "90210", billingcountry "united states" }; createvalidatedcustomer(customertocreate) then(customer => { console log('customer ready for use ', customer id); }) catch(error => { console log('handle creation failure appropriately'); }); request body schema required fields field type description options/format name string customer name (max 255 chars) "acme corporation" recordtype string customer type "consumer" or "business" business information fields field type description options/format legalentityname string legal entity name max 255 characters industry string industry classification see industry options below annualrevenue number annual revenue amount positive decimal number description string customer description free text funding string funding amount numeric string type string customer classification customer , prospect , partner accountsource string lead source web , phone , email , referral site string site information free text contact information fields field type description format email string primary email valid email format phone string primary phone international format recommended fax string fax number international format website string company website valid url format timezone string customer timezone iana timezone identifier imagesignedurl string profile image url signed url (read only) billing configuration fields field type description options billcycleday string day of month for billing "1st of month" , "7th of month" , "15th of month" , "last day of month" billcyclestartmonth string starting month "01" to "12" autorenew string auto renewal setting yes , no , defaulttosubscriptionconfiguration billingperiod string billing frequency monthly , quarterly , annual billingprorationenabled string enable proration yes , no address fields billing address billingstreet , billingcity , billingstate , billingpostalcode , billingcountry shipping address shippingstreet , shippingcity , shippingstate , shippingpostalcode , shippingcountry industry options common industry values include technology healthcare financial services manufacturing retail education government non profit consulting other response structure success response (201 created) { "status" "success", "data" \[ { "accountnumber" "z100293", "accountsource" "web", "annualrevenue" 5000000 00, "autorenew" "yes", "billcycleday" "7th of month", "billcyclestartmonth" "03", "billingcity" "san francisco", "billingcountry" "us", "billingperiod" "annual", "billingpostalcode" "94005", "billingprorationenabled" "yes", "billingstate" "ca", "billingstreet" "123 main street", "createdbyid" "3865c4c7 f233 4d7f 8426 2eb882856e5c", "createddate" "2025 06 27t23 23 53 002+00 00", "description" "some customer description", "email" "company\@email com", "fax" "+1 650 383 2838", "funding" "500000", "id" "c5786254 06a2 44fe 88d5 3dd5dad66e78", "imagesignedurl" "https //signedurl io", "industry" "agriculture", "lastmodifiedbyid" "3865c4c7 f233 4d7f 8426 2eb882856e5c", "lastmodifieddate" "2025 06 27t23 23 53 002+00 00", "legalentityname" "entityname", "name" "jadiceguyu", "phone" "393 393 2939", "recordtype" "consumer", "shippingcity" "san francisco", "shippingcountry" "us", "shippingpostalcode" "94005", "shippingstate" "ca", "shippingstreet" "123 main street", "site" "website", "timezone" "pacific/kiritimati", "type" "prospect", "website" "https //url com" } ], "warnings" \[] } error handling complete error reference the customer api returns comprehensive error information to help you handle all scenarios error code http status description resolution resource not found 404 customer not found verify customer id exists duplicate resource 409 customer already exists check for existing customer with same details request size exceeded 400 batch limit exceeded reduce batch size (max 200 customers) missing parameter 400 required field missing provide all required fields invalid field value format 400 invalid field format check field format requirements reserved field 400 attempting to modify reserved field remove reserved fields from request stripe customer upsert failed 500 payment integration error check stripe configuration customer not match 400 customer mismatch verify customer relationships salesforce sync failed 500 salesforce integration error check salesforce connection batch processing error 500 bulk operation failed retry with smaller batch validation error 422 data validation failed review field constraints unauthorized 401 invalid api key verify api key and permissions rate limited 429 too many requests implement retry with exponential backoff error response format { "status" "error", "error" { "code" "missing parameter", "message" "required field 'name' is missing", "details" { "field" "name", "requirement" "customer name is required and cannot be empty" } } } validation rules required fields name (string, max 255 characters) recordtype ("consumer" or "business") field constraints email valid email format required billcycleday "1st of month", "7th of month", "15th of month", or "last day of month" billcyclestartmonth "01" to "12" autorenew "yes", "no", or "defaulttosubscriptionconfiguration" billingperiod "monthly", "quarterly", or "annual" timezone valid iana timezone identifier annualrevenue positive number phone / fax international format recommended batch limits maximum 200 customers per request requests exceeding limit return request size exceeded error advanced features batch processing create up to 200 customers in a single request for efficient bulk operations const batchcustomers = \[ { name "customer one", recordtype "business", email "customer1\@example com", industry "technology" }, { name "customer two", recordtype "consumer", email "customer2\@example com", billingperiod "monthly" } // up to 200 customers ]; fetch('https //api nue io/orders/customers', { method 'post', headers myheaders, body json stringify(batchcustomers) }) then(response => response json()) then(result => { if (result status === 'success') { console log(`✅ created ${result data length} customers successfully`); // process each created customer result data foreach((customer, index) => { console log(`${index + 1} ${customer name} (${customer accountnumber})`); }); } }); enterprise integrations salesforce synchronization automatic bidirectional sync with salesforce crm // create customer with salesforce sync enabled const salesforcecustomer = \[{ name "enterprise client corp", recordtype "business", email "enterprise\@client com", // salesforce integration fields salesforceaccountid "0013000000abc123", syncwithsalesforce true, salesforceowner "sales rep\@company com" }]; custom fields support store additional business specific data using jsonb custom fields const customfieldscustomer = \[{ name "custom data corp", recordtype "business", // custom fields stored as jsonb customfields { "crm score" 85, "lead source" "trade show", "contract type" "enterprise", "renewal probability" 0 92, "custom tags" \["high value", "tech sector"] } }]; revenue analytics automatic calculation of key revenue metrics // customer creation triggers automatic analytics const analyticscustomer = \[{ name "analytics customer", recordtype "business", annualrevenue 2500000 00, // analytics will automatically calculate // total contract value (tcv) // annual recurring revenue (arr) // customer monthly recurring revenue (cmrr) // customer lifetime value (clv) }]; best practices data quality validate input data before sending to api use consistent formatting for phone numbers and addresses set appropriate defaults for billing configuration normalize business names for consistency implement data deduplication to prevent duplicate customers use custom fields for business specific requirements performance batch customer creation when possible (up to 200 per request) implement retry logic with exponential backoff for transient failures use distributed locking for concurrent operations monitor rate limits and implement proper throttling cache frequently accessed data to reduce api calls use async processing for large batch operations security validate all input data to prevent injection attacks implement proper authentication and api key management use tenant isolation to prevent cross tenant data access log all creation activities for comprehensive audit trails implement proper error handling without exposing sensitive data use https for all api communications encrypt sensitive custom field data when necessary integration best practices configure salesforce sync for crm integration set up stripe integration for payment processing implement webhook handlers for real time event processing use graphql filtering for complex customer queries monitor integration health and implement fallback mechanisms handle integration failures gracefully with proper error recovery this comprehensive guide enables you to efficiently create and onboard customers using the nue lifecycle management api, supporting everything from simple customer creation to complex onboarding workflows