Fetching Customers

this guide provides comprehensive instructions for retrieving customer data using the nue lifecycle management api learn how to fetch single or multiple customers, include related data, and implement efficient customer data retrieval workflows prerequisites before you begin, ensure you have a valid nue api key with customer read permissions customer ids (either salesforce ids or nue uuids) basic understanding of rest apis and json familiarity with customer data structures authentication all customer retrieval 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 retrieval fetch single customer try it now fetch customers → https //api docs nue io/fetch customers const myheaders = new headers(); myheaders append("nue api key", "your api key here"); myheaders append("content type", "application/json"); // fetch a single customer const customerids = \["d2e04653 ae90 49df a986 134cf64f6d03"]; const encodedcustomerids = encodeuricomponent(json stringify(customerids)); fetch(`https //api nue io/customers?customerids=${encodedcustomerids}`, { method 'get', headers myheaders }) then(response => response json()) then(result => { console log('customer retrieved successfully ', result); if (result status === 'success' && result data length > 0) { const customer = result data\[0]; console log(`\ncustomer ${customer name}`); console log(`customer id ${customer id}`); console log(`account number ${customer externalid}`); console log(`record type ${customer recordtype}`); console log(`status ${customer status}`); console log(`created ${customer createddate}`); } }) catch(error => console log('error ', error)); fetch multiple customers retrieve multiple customers in a single api call // fetch multiple customers const customerids = \[ "d2e04653 ae90 49df a986 134cf64f6d03", "cc5e1f0f 5e14 48cc ab98 9e5b191aa46f", "f1b2c3d4 e5f6 7890 abcd ef1234567890" ]; const encodedcustomerids = encodeuricomponent(json stringify(customerids)); fetch(`https //api nue io/customers?customerids=${encodedcustomerids}`, { method 'get', headers myheaders }) then(response => response json()) then(result => { if (result status === 'success') { console log(`retrieved ${result data length} customers`); result data foreach((customer, index) => { console log(`\n${index + 1} ${customer name}`); console log(` id ${customer id}`); console log(` type ${customer recordtype}`); console log(` status ${customer status}`); console log(` account ${customer externalid}`); }); } }) catch(error => console log('error ', error)); including related data fetch customers with contact information include customer contacts in the response const customerids = \["d2e04653 ae90 49df a986 134cf64f6d03"]; const encodedids = encodeuricomponent(json stringify(customerids)); // include contacts in the response const urlwithcontacts = `https //api nue io/customers?customerids=${encodedids}\&includes=contacts`; fetch(urlwithcontacts, { method 'get', headers myheaders }) then(response => response json()) then(result => { if (result status === 'success' && result data) { result data foreach(customer => { console log(`\n🏢 customer ${customer name}`); console log(` account ${customer accountnumber}`); console log(` email ${customer email || 'not provided'}`); // display contacts if included if (customer contacts && customer contacts length > 0) { console log(`\n 👥 contacts (${customer contacts length}) `); customer contacts foreach(contact => { console log(` • ${contact firstname} ${contact lastname}`); console log(` email ${contact email || 'not provided'}`); console log(` phone ${contact phone || 'not provided'}`); console log(` role ${contact title || 'not specified'}`); }); } else { console log(' no contacts available'); } }); } }) catch(error => console log('error ', error)); query parameters reference parameter type required description options customerids array\[string] yes json encoded array of customer ids \["customer uuid 1", "customer uuid 2"] includes string no related data to include "contacts" , "orders" , "assets" response structure success response (200 ok) { "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 common retrieval errors error description resolution invalid customer id customer id format invalid verify customer id format customer not found customer does not exist check customer id exists invalid record type invalid record type filter use "business" or "consumer" invalid includes invalid include parameter check available include options robust customer fetching async function safecustomerfetch(customerids, options = {}) { try { // validate inputs if (!array isarray(customerids) || customerids length === 0) { throw new error('customerids must be a non empty array'); } const encodedids = encodeuricomponent(json stringify(customerids)); let url = `https //api nue io/customers?customerids=${encodedids}`; // add optional parameters if (options includes) { url += `\&includes=${options includes}`; } const response = await fetch(url, { method 'get', headers myheaders }); if (!response ok) { throw new error(`http ${response status} ${response statustext}`); } const result = await response json(); if (result status !== 'success') { throw new error(`api error ${result message || 'unknown error'}`); } return { customers result data || \[], found result data? length || 0, requested customerids length }; } catch (error) { console error('customer fetch error ', error); return { customers \[], found 0, requested customerids length, error error message }; } } best practices data retrieval use specific filters to reduce data transfer include related data only when needed to optimize performance batch customer queries efficiently cache frequently accessed customer data performance optimization limit includes to required data only use appropriate timeout settings for api calls monitor api usage and respect rate limits implement proper error handling for network issues business intelligence analyze customer profiles for segmentation insights track customer engagement through contact completeness monitor commercial activity and order patterns generate actionable insights from customer data this comprehensive guide enables you to efficiently retrieve and analyze customer data using the nue lifecycle management api, supporting everything from simple customer lookups to complex portfolio analysis and business intelligence operations