Published on July 22, 2023.

One of the really nice things about NetSuite's SuiteTalk REST is that it makes working with External IDs very easy. With SuiteTalk REST, you can set a record's external ID, retrieve a record by its external ID, and work with a record by referencing its external ID.

In this post, I'll show several SuiteTalk REST API calls that involve External IDs.

Note that in the examples that follow, I'll be referencing records in the Employee table.

Assigning A New Record's External ID

To set a new record's External ID value, you simply include it in the payload just as you would any other column value. For example, to add a new Employee record with External ID "emp-20230722-1626," you might send a POST request like this:

URL:
https://tstdrv2533109.suitetalk.api.netsuite.com/services/rest/record/v1/employee

Payload:

{
  "firstName": "Jane",
  "lastName": "Rizzoli",
  "email": "jane.rizzoli@test.com",
  "currency": 1,
  "subsidiary": 1,
  "externalid": "emp-20230722-1626"
}

Note that the ExternalID is wrapped in double quotes. That's because the ExternalID column is a text value, which allows for alpha-numeric values.

Updating An Existing Record's External ID

To set or update an existing record's External ID, you include an "externalid" value in the payload - just as you would if you were setting it for a new record. For example, to update the External ID for a record with internal ID 2426, you would send a PATCH request like this.

URL:
https://tstdrv2533109.suitetalk.api.netsuite.com/services/rest/record/v1/employee/2426/

Payload:

{
  "externalid": "emp-20230722-1634"
}

Duplicate External IDs and Case Sensitivity

If you attempt to set a record's external ID to a value that has already been assigned to another record (in the same table), then SuiteTalk will return a 400 "Bad Request" response code.

The response body will look something like this.

{
  "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",
  "title": "Bad Request",
  "status": 400,
  "o:errorDetails": [
    {
      "detail": "Error while accessing a resource. This entity already exists.",
      "o:errorCode": "USER_ERROR"
    }
  ]
}

External IDs are not case sensitive. So if you attempt to set one record's external ID to "emp-20230722-1600" and another's to "EMP-20230722-1600" then you will also get the same 400 "Bad Request" response.

External IDs And Empty Strings

You cannot set a record's External ID to an empty string. If you attempt to do so, you'll get a 400 "Bad Request" response code, and the response body will look like this:

{
  "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",
  "title": "Bad Request",
  "status": 400,
  "o:errorDetails": [
    {
      "detail": "Invalid value '' for the field externalid.",
      "o:errorPath": "externalid",
      "o:errorCode": "INVALID_VALUE"
    }
  ]
}

External IDs And NULLs

Once you've set a record's External ID, you cannot unset or clear it by setting it to NULL.

If you attempt to do so, you'll get a 400 "Bad Request" response code, and the response body will look like this:

{
  "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1",
  "title": "Bad Request",
  "status": 400,
  "o:errorDetails": [
    {
      "detail": "Invalid value for the resource or sub-resource field 'externalid'. Provide a valid value.",
      "o:errorPath": "externalid",
      "o:errorCode": "INVALID_VALUE"
    }
  ]
}

Referencing A Record by Its External ID

As I discussed in "SuiteTalk REST Overview, Common Issues, and Advice," the URL used to retrieve a record by its external ID is very similar to the URL that you'd use to retrieve it by its internal ID. Instead of using the internal ID in the URL, you indicate that you want to use the external ID by including "eid:" followed by the external ID value.

For example, to retrieve the record that we created earlier, with external ID "emp-20230722-1602," you would use this URL:

https://tstdrv2533109.suitetalk.api.netsuite.com/services/rest/record/v1/employee/eid:emp-20230722-1602

Similarly, you can use an external ID value to update or delete a record.

External IDs and SuiteQL

Of course, another way to retrieve a record by its external ID is to use SuiteQL. For example, to query for the ID, First Name, and Last Name of the employee record with External ID "emp-20230722-1602" you would send a POST request like this.

URL:
https://tstdrv2533109.suitetalk.api.netsuite.com/services/rest/query/v1/suiteql

Payload:

{
  "q": "SELECT ID, FirstName, LastName FROM Employee WHERE ExternalID = 'emp-20230722-1602'"
}

Wrapping Up

As you can see, SuiteTalk REST makes working with external IDs very easy and convenient. NetSuite has done a great job of supporting the use of external IDs, both in terms of setting values, and utilizing those values to retrieve, update, or delete records. So if you need to synchronize data between NetSuite and an external system, SuiteTalk REST might be a good choice for you in terms of integration options.

And finally, if you need to provide external ID support to your users - and specifically to allow users to easily lookup records by external IDs - then you might want to check out the Power Search Suitelet, and the External ID Search Utility.