Developer Blog Series: System Record IDs Vs. Lookup IDs

Lately some confusion has surfaced in the Community and beyond about which ID is which when interacting with SKY API and its underlying products. I would like to provide some clarity on this front and hopefully provide some insight into why things work the way they do.

First off, I would like to focus on two types of IDs: system record IDs and lookup IDs. In short, system record IDs are the immutable, SQL-defined values that are added when you create records, whereas lookup IDs are customizable, secondary identifiers that users can define for particular records.

For SKY API, we use system record IDs as the primary identifier in entity models and routing structures primarily because of their immutable nature. If we leveraged lookup IDs instead, integrating with a system would be exceedingly difficult and unreliable when matching records with external data stores. For example, we could not guarantee that api.sky.blackbaud.com/constituent/v1/constituents/280 would consistently return Robert Hernandez. However, while we don't allow lookup IDs in our routes to ensure that records are returned consistent, you can use lookup IDs with the Constituent (Search) endpoint to find records with these alternative IDs. Search functionality does not currently exist for other record types , but if you would like to see it added, I encourage you to submit an idea.

Using the Constituent API as an example, the system record ID is the primary identifier for a constituent in SKY API, as populated by Raiser's Edge NXT. In this case, the ID is an auto-incrementing integer that can be found in the Raiser's Edge NXT web view routes or via the "System Record ID" output field in Database View queries.

All Raiser's Edge NXT URL routes match the pattern of renxt.blackbaud.com/{recordType}/{systemId}?tenantid=, so they can easily be leveraged to determine system record IDs when developing and testing your applications.

You can edit and view the lookup ID on the Constituent Summary tile in Web View or on the Bio 1 tab in Database View. On other record types, it is typically available in the summary information at the top of the record page in Web View and on the first tab on the record in Database View.

In a gift record from Raiser's Edge NXT, the system record ID is highlighted in green in the URL at the top, and the lookup ID is highlighted in blue on the record itself.

We recognize that lookup IDs have somewhat confusing labels as they are often simply referred to as "ID" in the product views. However, we will relabel and standardize these labels in the Web View to be consistent with the API moving forward in the hopes of preventing further confusion.

Hopefully this explanation is helpful and provides some much needed clarity!