Creating Contacts

this guide provides comprehensive instructions for creating new contacts using the nue lifecycle management api learn how to create single or multiple contacts for customers, set up complete contact profiles, and implement efficient contact onboarding workflows prerequisites before you begin, ensure you have a valid nue api key with contact creation permissions valid customer id to associate contacts with understanding of contact data requirements basic knowledge of rest apis and json authentication all contact 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 contact creation create single contact try it now create customer contacts → https //api docs nue io/create customer contacts const myheaders = new headers(); myheaders append("nue api key", "your api key here"); myheaders append("content type", "application/json"); // create a single contact for a customer const customerid = "d2e04653 ae90 49df a986 134cf64f6d03"; const contactdata = \[{ firstname "john", lastname "doe", name "john doe", // required full name email "john doe\@acme com" // required email address }]; fetch(`https //api nue io/customers/${customerid}/contacts`, { method 'post', headers myheaders, body json stringify(contactdata) }) then(response => response json()) then(result => { if (result status === 'success') { const contacts = result data; console log('contact created successfully ', result); if (contacts length > 0) { const contact = contacts\[0]; console log(`✅ created ${contact name}`); console log(`contact id ${contact id}`); console log(`email ${contact email}`); console log(`customer id ${contact customerid}`); console log(`created date ${contact createddate}`); } // handle any warnings if (result warnings && result warnings length > 0) { console warn('warnings ', result warnings); } } else { console error('failed to create contact ', result error); } }) catch(error => console log('error ', error)); create contact with complete information create a contact with comprehensive personal and address details const customerid = "d2e04653 ae90 49df a986 134cf64f6d03"; const comprehensivecontact = \[{ // required fields firstname "jane", lastname "smith", name "jane smith", email "jane smith\@acme com", // optional personal information middlename "elizabeth", suffix "jr ", title "chief technology officer", birthday "1985 03 15", // iso format yyyy mm dd // contact information phone "+1 555 0123", mobilephone "+1 555 0124", // billing address billingstreet "123 business plaza, suite 400", billingcity "san francisco", billingstate "ca", billingpostalcode "94105", billingcountry "united states", // shipping address (if different) shippingstreet "456 home street", shippingcity "oakland", shippingstate "ca", shippingpostalcode "94612", shippingcountry "united states" }]; fetch(`https //api nue io/customers/${customerid}/contacts`, { method 'post', headers myheaders, body json stringify(comprehensivecontact) }) then(response => response json()) then(result => { if (result status === 'success') { const contacts = result data; console log('comprehensive contact created ', result); const contact = contacts\[0]; console log(`\n✅ contact created successfully`); console log(`name ${contact firstname} ${contact middlename} ${contact lastname} ${contact suffix}`); console log(`title ${contact title}`); console log(`email ${contact email}`); console log(`phone ${contact phone}`); console log(`mobile ${contact mobilephone}`); console log(`birthday ${contact birthday}`); console log(`customer id ${contact customerid}`); // handle any warnings if (result warnings && result warnings length > 0) { console warn('warnings ', result warnings); } } else { console error('failed to create contact ', result error); } }) catch(error => console log('error ', error)); bulk contact creation create multiple contacts efficiently create multiple contacts for a customer in a single api call const customerid = "d2e04653 ae90 49df a986 134cf64f6d03"; const bulkcontacts = \[ { firstname "robert", lastname "johnson", name "robert johnson", email "robert johnson\@acme com", title "chief financial officer", phone "+1 555 0200", billingstreet "123 business plaza, suite 400", billingcity "san francisco", billingstate "ca", billingpostalcode "94105", billingcountry "united states" }, { firstname "sarah", lastname "williams", name "sarah williams", email "sarah williams\@acme com", title "vp of operations", phone "+1 555 0201", mobilephone "+1 555 0301", billingstreet "123 business plaza, suite 400", billingcity "san francisco", billingstate "ca", billingpostalcode "94105", billingcountry "united states" }, { firstname "michael", lastname "brown", name "michael brown", email "michael brown\@acme com", title "director of engineering", phone "+1 555 0202", mobilephone "+1 555 0302", birthday "1988 07 22" } ]; fetch(`https //api nue io/customers/${customerid}/contacts`, { method 'post', headers myheaders, body json stringify(bulkcontacts) }) then(response => response json()) then(result => { if (result status === 'success') { const contacts = result data; console log(`\n✅ successfully created ${contacts length} contacts `); contacts foreach((contact, index) => { console log(`\n${index + 1} ${contact name}`); console log(` id ${contact id}`); console log(` email ${contact email}`); console log(` title ${contact title || 'not specified'}`); console log(` phone ${contact phone || 'not provided'}`); console log(` mobile ${contact mobilephone || 'not provided'}`); }); // handle any warnings if (result warnings && result warnings length > 0) { console warn('warnings ', result warnings); } } else { console error('failed to create contacts ', result error); } }) catch(error => console log('error ', error)); advanced contact creation patterns contact onboarding service implement a complete contact onboarding process with validation and enrichment class contactonboardingservice { constructor(apikey) { this apikey = apikey; this headers = new headers(); this headers append("nue api key", apikey); this headers append("content type", "application/json"); } async onboardnewcontact(customerid, contactinput) { try { // step 1 validate contact data const validateddata = this validatecontactdata(contactinput); // step 2 enrich with defaults and formatting const enricheddata = this enrichcontactdata(validateddata); // step 3 check for duplicates await this checkforduplicates(customerid, enricheddata email); // step 4 create contact const createdcontact = await this createcontact(customerid, enricheddata); // step 5 set up additional configurations await this setupcontactconfigurations(createdcontact); // step 6 send welcome communications await this sendwelcomeemail(createdcontact); return { success true, contact createdcontact, message `contact ${createdcontact name} onboarded successfully` }; } catch (error) { console error('contact onboarding failed ', error); return { success false, error error message, contactinput }; } } validatecontactdata(input) { const errors = \[]; // required field validation if (!input firstname || input firstname trim() length === 0) { errors push('firstname first name is required'); } if (!input lastname || input lastname trim() length === 0) { errors push('lastname last name is required'); } if (!input name || input name trim() length === 0) { errors push('name full name is required'); } if (!input email || !this isvalidemail(input email)) { errors push('email valid email address is required'); } // length validations if (input firstname && input firstname length > 40) { errors push('firstname maximum 40 characters allowed'); } if (input lastname && input lastname length > 80) { errors push('lastname maximum 80 characters allowed'); } if (input name && input name length > 255) { errors push('name maximum 255 characters allowed'); } if (input middlename && input middlename length > 40) { errors push('middlename maximum 40 characters allowed'); } if (input suffix && input suffix length > 40) { errors push('suffix maximum 40 characters allowed'); } // phone validation if (input phone && !this isvalidphone(input phone)) { errors push('phone invalid phone number format'); } if (input mobilephone && !this isvalidphone(input mobilephone)) { errors push('mobilephone invalid mobile phone number format'); } // birthday validation if (input birthday && !this isvaliddate(input birthday)) { errors push('birthday invalid date format, use yyyy mm dd'); } if (errors length > 0) { throw new error(`validation failed ${errors join(', ')}`); } return input; } enrichcontactdata(input) { // auto generate full name if not provided const enriched = { input, name input name || `${input firstname} ${input lastname}` trim() }; // normalize email to lowercase enriched email = enriched email tolowercase() trim(); // format phone numbers if (enriched phone) { enriched phone = this formatphonenumber(enriched phone); } if (enriched mobilephone) { enriched mobilephone = this formatphonenumber(enriched mobilephone); } // standardize title case for names enriched firstname = this totitlecase(enriched firstname); enriched lastname = this totitlecase(enriched lastname); if (enriched middlename) { enriched middlename = this totitlecase(enriched middlename); } return enriched; } async checkforduplicates(customerid, email) { // in a real implementation, you might want to check for existing contacts // with the same email address for this customer console log(`checking for duplicate contacts with email ${email}`); // for now, we'll just log in practice you'd fetch existing contacts // and compare email addresses } async createcontact(customerid, contactdata) { const response = await fetch(`https //api nue io/customers/${customerid}/contacts`, { method 'post', headers this headers, body json stringify(\[contactdata]) }); if (!response ok) { const errortext = await response text(); throw new error(`contact creation failed ${response status} ${errortext}`); } const result = await response json(); if (result status === 'success') { return result data\[0]; } else { throw new error(`contact creation failed ${result error}`); } } async setupcontactconfigurations(contact) { // additional setup steps could include // setting up communication preferences // adding to distribution lists // setting up access permissions // integrating with external systems console log(`setting up configurations for ${contact name} `); console log(`✅ configurations completed for contact ${contact id}`); } async sendwelcomeemail(contact) { // integration with email service console log(`📧 sending welcome email to ${contact email} `); // mock email service integration const emaildata = { to contact email, subject `welcome ${contact firstname}!`, template 'contact welcome', data { firstname contact firstname, contactid contact id, title contact title } }; console log(`✅ welcome email queued for ${contact email}`); } isvalidemail(email) { const emailregex = /^\[^\s@]+@\[^\s@]+\\ \[^\s@]+$/; return emailregex test(email); } isvalidphone(phone) { const phoneregex = /^\\+?\[\d\s\\ \\(\\)]{10,}$/; return phoneregex test(phone); } isvaliddate(datestring) { const dateregex = /^\d{4} \d{2} \d{2}$/; if (!dateregex test(datestring)) return false; const date = new date(datestring); return date instanceof date && !isnan(date) && date toisostring() split('t')\[0] === datestring; } formatphonenumber(phone) { // basic phone formatting remove extra spaces and standardize format return phone replace(/\s+/g, ' ') trim(); } totitlecase(str) { return str replace(/\w\s /g, (txt) => txt charat(0) touppercase() + txt substr(1) tolowercase() ); } } // usage example const onboardingservice = new contactonboardingservice("your api key here"); const newcontactdata = { firstname "alice", lastname "johnson", email "alice johnson\@techcorp com", title "senior software engineer", phone "555 0150", mobilephone "+1 555 0250", birthday "1990 12 05", billingstreet "789 tech avenue", billingcity "austin", billingstate "tx", billingpostalcode "73301", billingcountry "united states" }; onboardingservice onboardnewcontact( "d2e04653 ae90 49df a986 134cf64f6d03", newcontactdata ) then(result => { if (result success) { console log('\n🎉 contact onboarding completed successfully!'); console log(`contact ${result contact name}`); console log(`id ${result contact id}`); console log(`email ${result contact email}`); } else { console error('❌ onboarding failed ', result error); } }); team contact creation workflow create contacts for entire teams with role based configurations class teamcontactmanager { constructor(apikey) { this apikey = apikey; this headers = new headers(); this headers append("nue api key", apikey); this headers append("content type", "application/json"); } async createteamcontacts(customerid, teamdata) { try { console log(`👥 creating team contacts for customer ${customerid} `); // prepare team contacts with role based defaults const teamcontacts = teamdata members map(member => { const contact = { firstname member firstname, lastname member lastname, name `${member firstname} ${member lastname}`, email member email, title member title || this getdefaulttitle(member role), phone member phone, mobilephone member mobilephone, this getrolebaseddefaults(member role), teamdata commonaddress }; return contact; }); // create all contacts in batch const response = await fetch(`https //api nue io/customers/${customerid}/contacts`, { method 'post', headers this headers, body json stringify(teamcontacts) }); if (!response ok) { throw new error(`team creation failed ${response status}`); } const createdcontacts = await response json(); // organize by role for reporting const teamstructure = this organizeteambyrole(createdcontacts, teamdata members); console log(`✅ successfully created ${createdcontacts length} team contacts `); object entries(teamstructure) foreach((\[role, contacts]) => { console log(`\n👔 ${role} (${contacts length}) `); contacts foreach(contact => { console log(` • ${contact name} ${contact email}`); }); }); return { contacts createdcontacts, teamstructure, summary { totalmembers createdcontacts length, roles object keys(teamstructure), customerid customerid } }; } catch (error) { console error('team contact creation failed ', error); throw error; } } getdefaulttitle(role) { const roletitlemap = { 'executive' 'executive', 'manager' 'manager', 'lead' 'team lead', 'senior' 'senior specialist', 'regular' 'specialist', 'admin' 'administrator' }; return roletitlemap\[role] || 'team member'; } getrolebaseddefaults(role) { // role based default configurations const roledefaults = { 'executive' { // executives might need special handling }, 'manager' { // managers might have different requirements }, 'admin' { // administrators might need specific access } }; return roledefaults\[role] || {}; } organizeteambyrole(createdcontacts, originalmembers) { const teamstructure = {}; createdcontacts foreach((contact, index) => { const memberdata = originalmembers\[index]; const role = memberdata role || 'regular'; if (!teamstructure\[role]) { teamstructure\[role] = \[]; } teamstructure\[role] push({ contact, role role }); }); return teamstructure; } } // usage example const teammanager = new teamcontactmanager("your api key here"); const teamdata = { commonaddress { billingstreet "100 corporate plaza", billingcity "seattle", billingstate "wa", billingpostalcode "98101", billingcountry "united states" }, members \[ { firstname "david", lastname "chen", email "david chen\@startup com", role "executive", title "ceo", phone "+1 555 0300" }, { firstname "lisa", lastname "rodriguez", email "lisa rodriguez\@startup com", role "manager", title "vp engineering", phone "+1 555 0301", mobilephone "+1 555 0401" }, { firstname "tom", lastname "wilson", email "tom wilson\@startup com", role "lead", title "technical lead", phone "+1 555 0302" }, { firstname "emma", lastname "davis", email "emma davis\@startup com", role "regular", title "software engineer", mobilephone "+1 555 0402" } ] }; teammanager createteamcontacts( "d2e04653 ae90 49df a986 134cf64f6d03", teamdata ) then(result => { console log(`\n🎉 team setup completed!`); console log(`total members ${result summary totalmembers}`); console log(`roles ${result summary roles join(', ')}`); }); contact creation with validation implement comprehensive validation and error handling class contactvalidator { static validate(contactdata) { const errors = \[]; // required fields if (!contactdata firstname? trim()) { errors push('firstname first name is required'); } if (!contactdata lastname? trim()) { errors push('lastname last name is required'); } if (!contactdata name? trim()) { errors push('name full name is required'); } if (!contactdata email? trim()) { errors push('email email address is required'); } else if (!this isvalidemail(contactdata email)) { errors push('email invalid email format'); } // length validations if (contactdata firstname && contactdata firstname length > 40) { errors push('firstname maximum 40 characters allowed'); } if (contactdata lastname && contactdata lastname length > 80) { errors push('lastname maximum 80 characters allowed'); } if (contactdata name && contactdata name length > 255) { errors push('name maximum 255 characters allowed'); } if (contactdata middlename && contactdata middlename length > 40) { errors push('middlename maximum 40 characters allowed'); } if (contactdata suffix && contactdata suffix length > 40) { errors push('suffix maximum 40 characters allowed'); } // phone validations if (contactdata phone && !this isvalidphone(contactdata phone)) { errors push('phone invalid phone number format'); } if (contactdata mobilephone && !this isvalidphone(contactdata mobilephone)) { errors push('mobilephone invalid mobile phone number format'); } // birthday validation if (contactdata birthday && !this isvaliddate(contactdata birthday)) { errors push('birthday invalid date format, use yyyy mm dd'); } // address validation if (contactdata billingstreet && !contactdata 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); } static isvaliddate(datestring) { const dateregex = /^\d{4} \d{2} \d{2}$/; if (!dateregex test(datestring)) return false; const date = new date(datestring); return date instanceof date && !isnan(date) && date toisostring() split('t')\[0] === datestring; } } async function createvalidatedcontact(customerid, contactdata) { 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 = contactvalidator validate(contactdata); if (!validation isvalid) { throw new error(`validation failed \n${validation errors join('\n')}`); } // create contact const response = await fetch(`https //api nue io/customers/${customerid}/contacts`, { method 'post', headers myheaders, body json stringify(\[contactdata]) }); if (!response ok) { const errortext = await response text(); throw new error(`api error ${response status} ${errortext}`); } const contacts = await response json(); const contact = contacts\[0]; console log('✅ contact created and validated successfully '); console log(` name ${contact name}`); console log(` id ${contact id}`); console log(` email ${contact email}`); console log(` customer id ${contact customerid}`); return contact; } catch (error) { console error('❌ contact creation failed ', error message); throw error; } } // usage with validation const contacttocreate = { firstname "valid", lastname "contact", name "valid contact", email "valid contact\@example com", title "test contact", phone "+1 555 0100", birthday "1990 01 01", billingstreet "123 valid street", billingcity "valid city", billingstate "ca", billingpostalcode "90210", billingcountry "united states" }; createvalidatedcontact( "d2e04653 ae90 49df a986 134cf64f6d03", contacttocreate ) then(contact => { console log('contact ready for use ', contact id); }) catch(error => { console log('handle creation failure appropriately'); }); request body schema required fields field type description example firstname string first name (max 40 chars) "john" lastname string last name (max 80 chars) "doe" name string full name (max 255 chars) "john doe" email string email address "john doe\@example com" optional personal information field type description format/constraints middlename string middle name max 40 characters suffix string name suffix max 40 characters title string professional title free text birthday string birth date iso format yyyy mm dd contact information field type description format phone string primary phone number international format recommended mobilephone string mobile phone number international format recommended address information billing address fields billingstreet , billingcity , billingstate , billingpostalcode , billingcountry shipping address fields shippingstreet , shippingcity , shippingstate , shippingpostalcode , shippingcountry response structure success response (201 created) \[ { "id" "contact uuid here", "customerid" "customer uuid here", "firstname" "john", "lastname" "doe", "name" "john doe", "email" "john doe\@example com", "title" "software engineer", "phone" "+1 555 0123", "mobilephone" "+1 555 0124", "birthday" "1990 01 01", "billingstreet" "123 main st", "billingcity" "san francisco", "billingstate" "ca", "billingpostalcode" "94105", "billingcountry" "united states", "createddate" "2025 06 25t12 00 00z", "createdbyid" "user id", "lastmodifieddate" "2025 06 25t12 00 00z", "lastmodifiedbyid" "user id" } ] error handling common error scenarios error description resolution 400 bad request invalid request data or missing customer id check required fields and customer id 401 unauthorized invalid api key verify api key and permissions 404 not found customer id not found verify customer exists 422 validation error data validation failed review field constraints 429 rate limited too many requests implement retry with backoff validation errors missing required fields ensure firstname , lastname , name , and email are provided invalid email format use proper email validation field length exceeded check character limits for each field invalid date format use iso format yyyy mm dd for birthday invalid phone format use international phone number format best practices data quality validate input data before sending to api use consistent formatting for names and contact information normalize email addresses to lowercase standardize phone number formats for consistency performance batch contact creation when possible (multiple contacts per request) implement retry logic for transient failures cache customer information to reduce lookup calls monitor rate limits and implement backoff security validate all input data to prevent injection log creation activities for audit trails implement proper error handling without exposing sensitive data use https for all api communications organization use consistent naming conventions for contact data implement role based contact organization for teams set up proper address hierarchies for multi location customers maintain data relationships between contacts and customers this comprehensive guide enables you to efficiently create and onboard contacts using the nue lifecycle management api, supporting everything from simple contact creation to complex team onboarding workflows