NetSuite Integration Field Mapping, Configuration Guide and Common Configuration Issues
9 min read
Velaro's NetSuite integration lets your chat, missed-chat, and offline survey data create or update Leads, Prospects, Contacts, and Customers directly in your NetSuite account. Because every NetSuite instance is customized differently, custom fields, required-field rules, roles, and record types all vary by account, getting field mapping right is the single most important step in setting this integration up correctly.
This guide covers how field mapping works and the most common configuration issues we see across NetSuite customers, along with how to resolve them.
Where field mapping lives
Go to Account → Integrations → NetSuite → Record Mappings in Chat Designer. Each record type you use (Lead, Prospect, Contact, Customer, etc.) has its own independent set of field mappings, mapping a field for one record type does not automatically map it for another.
For each field mapping, you choose:
- Which NetSuite field it writes to
- Which source it pulls from (a survey question, a visitor data field, or a fixed default value)
- An optional default value used when no survey/visitor value is available
Issue: Required NetSuite fields not mapped
NetSuite enforces whatever required fields exist on your account's Lead/Contact/Customer entry forms, this is configured in NetSuite itself (Setup → Company → your record's entry form), not by Velaro. If a field is required on your NetSuite form but isn't mapped in your Record Mappings for that record type, NetSuite will reject the entire record creation with an error like:
> Please enter value(s) for: First Name
Fix: for every record type you use, map every field your NetSuite form marks as required, even if it's just a fallback default value (see below) for cases where a visitor doesn't provide that information.
A common trap: a required field gets correctly mapped for one record type (say, Prospect) when first setting up the integration, but a second record type (say, Lead) is added later without re-checking that its required fields are mapped too. Each record type needs its own complete mapping, nothing carries over automatically.
Field mappings created for your live-chat surveys do not automatically apply to missed-chat processing. If you want a field (such as First Name) populated on records created from missed chats or bot conversations, link that field to a survey question in the Missed Chat Surveys tab of the field-linking screen as well as your live-chat surveys. A field linked only under the live-chat tabs will come back empty on a missed-chat or bot-created record.
Issue: Missing default values on optional fields
Not every chat will include every piece of information your NetSuite form requires, a visitor might not give a last name, or might skip the pre-chat survey question you're relying on for a field. Setting a default value on a field mapping (e.g., a placeholder like . for a required-but-often-missing Last Name field) means the record still gets created instead of being rejected outright when that specific piece of data isn't available.
Default values only apply when no survey answer, visitor field, or engagement field produces a value, a real answer from the visitor always takes priority.
Issue: The Visitor "Name" field is often blank or generic
When linking a field, the Visitor tab includes an option labeled Name. This pulls Velaro's own internal visitor display name, not anything the visitor typed. For most visitors this is an auto-generated placeholder rather than a real name, so mapping First Name or Last Name to it will often produce blank or unhelpful values on the resulting NetSuite record.
For an accurate name, link the field to an actual prechat (or missed-chat) survey question the visitor answers themselves, such as "What's your name?", rather than the Visitor Name option.
Splitting a single "full name" survey question into separate First and Last Name fields is not something the field-mapping screen supports on its own, there is no built-in text-splitting or pattern option. If you want to keep one combined name question but still populate separate First Name and Last Name fields in NetSuite, contact Velaro to have a custom mapping rule built for your account. Where possible, we recommend using two separate survey questions (First Name, Last Name) instead: it's self-serve, requires no custom work, and always parses correctly, whereas splitting a single free-text name is inherently unreliable (it will mis-handle middle names, single-word names, and non-Western name ordering).
Issue: Duplicate records from repeat visitors
NetSuite's Duplicate Detection feature (Setup → Company → Duplicate Detection) only evaluates records created through NetSuite's own UI or CSV import. Records created via RESTlet/API, which is how Velaro's integration creates records, are not checked against your Duplicate Detection rules.
In practice, this means: if the same visitor chats more than once and doesn't provide consistent contact information each time (e.g., an email address on one visit but not the next), the integration has no way to automatically recognize it's the same person and will create a separate record each time. Mapping a field such as phone or email only controls what value is sent to NetSuite on record creation, it does not trigger any lookup or matching against existing records.
Fix: the most reliable way to reduce duplicate records is making key identifying fields (typically Email, and/or Phone) required in your pre-chat/offline survey, so every chat consistently captures a matching key. If tighter duplicate prevention is needed beyond that, it needs to be built into your NetSuite-side RESTlet script as a lookup-before-create step, this is a customization on the NetSuite side, not a Velaro setting.
Issue: Two records created for the same missed chat
Missed Chat Rules and Bot Rules are independent rule sets, and both can be configured to create a record for the same group. If a Missed Chat Rule and a Bot Rule both apply to the same missed conversation, for example, one creates a Prospect for any group and another creates a Lead specifically for a bot-handled group, both records get created for that single visitor.
This only affects missed chats (chats where no agent responded, or a bot conversation that never reached a live agent). A bot conversation that gets transferred to and completed by a live agent is a normal live-chat engagement and uses your live-chat record-creation settings, not the Missed Chat Rules or Bot Rules described here.
Fix: review your Missed Chat Rules and Bot Rules together (Account → Integrations → NetSuite) and decide whether you want one record type or two for each group. If you only want one record per missed conversation, adjust the rules so only one of them applies to any given group.
Issue: Integration connection requires specific NetSuite role permissions
<img src="https://azuregallerydev.blob.core.windows.net/logos/KnowledgeBase/1032/85abe60a79b14dda9df3ce3af01c4e5f" alt="NetSuite integration connection screen showing Username, Password, RESTlet URL, and Token Based Authentication fields" style="max-width:100%;border-radius:8px;" />
The NetSuite user/role connected to Velaro needs the REST Web Services permission enabled, along with create/edit permissions for whichever record types (Lead, Prospect, Contact, Customer, etc.) you intend to create through the integration. Without REST Web Services permission specifically, connecting the integration (or refreshing its token) fails with a permissions error even if the underlying login credentials are correct.
Fix: in NetSuite, go to Setup → Users/Roles → Manage Roles, open the role assigned to your integration user, and confirm REST Web Services is enabled under Permissions → Setup, plus the appropriate record-level permissions under Permissions → Transactions or Permissions → Lists (depending on record type).
Two logins under Offline Access, what they're for
The Offline Access section has two connection buttons: Use My Credentials and Connect as User. Both authorize the same thing, the login NetSuite records use when a record is created automatically with no agent present (a missed chat or a bot conversation). Use My Credentials reuses your own admin login for that purpose; Connect as User lets you designate a separate, dedicated login instead. Neither is related to the primary connection at the top of the page, which is what agents use for real-time, in-chat NetSuite actions.
Saving your changes
Record Types and their field mappings save independently of the rest of the page: clicking Save inside the Record Type editor saves that record type immediately, and deleting a record type also saves immediately. The Save Global Settings button at the bottom of the page only covers the checkboxes and rules above it (Missed Chat Rules, Bot Rules, and related settings), it does not need to be clicked to persist Record Type changes, but it does need to be clicked to persist any rule or checkbox changes.
The Disable button removes this integration's entire configuration, including every record type and rule. It is unrelated to Save Global Settings and cannot be undone from the console.
If your NetSuite session isn't currently connected, this screen shows your saved configuration read-only, it looks the same as the editable view, but adding or editing a record type will prompt you to reconnect first. Once reconnected, the same screen becomes fully editable.
Quick reference
| Symptom | Likely cause | Where to fix it |
|---|
Email
Netsuite Troubleshooting