Using External IDs

Each record in NetSuite can be uniquely identified by its record type in combination with either an external ID or a system-generated internal ID. For an overview of internal and external IDs, see Using Internal IDs, External IDs, and References.

You can use an external ID as a key to a record instead of an internal ID. The main use of external IDs is during synchronization with existing data outside of NetSuite.

In REST web services, an external ID starts with the prefix "eid:" in the following format: eid:external_id.

An external ID can be any string containing letters, numbers, underscore (_), and hyphen (-).

You can use external IDs anywhere in the URL where an internal ID can be used. You can also use an external ID in the request body with the field name externalId.

The following example adds a record. The external ID is used in the request body.

          POST http://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/customer
BODY {
  "firstName": "John",
  "lastName": "Smith",
  "isPerson": true,
  "externalId": "CID001",
  "subsidiary": {
  "id": "1"
  }
 }

The following example retrieves a record. External IDs are used in the request to identify the record.

          GET http://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/customer/eid:CID001/subscriptions/eid:SUID042

Tip:

If your external ID contains the pipe character (|), this is treated in REST web services as a multi-select delimiter, so the external ID is not parsed correctly. In this case, you can use the following workaround. Use the q= parameter and specify the external ID in the search criteria, surrounded by double quotation marks as in the following example.

          GET http://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/purchaseOrder/?q=externalId IS "RED|PO|1337"

Related Topics