External IDs Overview

The externalId attribute of a RecordRef provides a means to reference an object by its foreign key in an external database.

You can set the externalID attribute during an add or update operation. External IDs are useful in the following situations:

• Maintaining client ID relationships

  In cases where a client application already maintains references between records, set the externalId attribute for each record during imports. In subsequent API calls, you can then reference associated records by the known external ID.

• Establishing relationships during a single import operation

  For example, suppose you want to import customer records with references to sales reps into NetSuite. If no external ID is used, you would need to import the customer records, determine the IDs of the related sales reps' employee records, and then re-import the customer records with the sales reps ID references. By providing an external ID, you can import the customer records in a single API call using the external ID references to the sales reps.

To prevent duplicate records, you should use external IDs and the upsert and upsertList operations to add records to NetSuite.

Most NetSuite record types support the use of external ID, but not all do. The following list identifies the record types that do not support external ID. For all other records, you should assume that external ID is supported. When in doubt, refer to the appropriate page in the SOAP Schema Browser. On each page describing a record type, view the Attributes table to see whether external ID is supported.

Important:

External IDs are not displayed on records by default. However, you can search for external IDs, or you can add a custom field to the record types where you want to the external ID to be displayed in the UI. For information about searching in SOAP web services, see Basic Searches in SOAP Web Services. For information about working with custom fields, see Custom Fields.

The record types that do not support external ID are:

• Accounting Period

• Budget Category

• CRM Custom Field

• Currency Rate

• Custom List

• Custom Record Custom Field

• Custom Record Type

• Entity Custom Field

• Gift Certificate

• Item Custom Field

• Item Number Custom Field

• Item Option Custom Field

• Landed Cost

• Other Custom Field

• State

• Transaction Body Custom Field

• Transaction Column Custom Field

Guidelines for External IDs

Consider the following guidelines for external IDs:

• External IDs must be unique not just within a single record type, but also within certain record groups. For details about record types and record groups, see Shared Internal and External IDs.

• External IDs can be updated through CSV import or web services. Therefore, your organization should use a single approach for maintaining external IDs, so that external IDs are not unknowingly updated using two separate methods.

  Although records of a particular type may be used in multiple integration scenarios, each record instance can only have a single external ID value. To maintain data integrity, only a single integrated application can set and update external ID values for each record type. External ID values for all records of a particular type must all come from the same external application.

• External IDs are case insensitive in web services references. For details, see Using Internal IDs, External IDs, and References.

Related Topics

Records in SOAP Web Services

Record Types

Search Records

Subrecords

Using Internal IDs, External IDs, and References

Shared Internal and External IDs

General Notices