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.

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: 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.

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: Integration connection requires specific NetSuite role permissions

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).

Quick reference

Review your Record Mappings any time you add a new record type, change your NetSuite form's required fields, or notice unexpected record-creation errors in your NetSuite account.