Global Ids

Every record in the Cloudshelf API has a unique identifier, internally we use ULIDs . When provided to an external source we decorate these with additional information to make them easier to understand.

These are called Global Ids; they are a combination of the owner type, their record type and the ULID, separated by a forward slashes. For more information about Global Ids see here .

Global ID Breakdown

Every entity in the Cloudshelf API will have an ID field, which return one of these Global Ids.

When you make a query to the Cloudshelf API, you use these Global Ids to query for a specific record, you can either provide a Cloudshelf Global ID or an External Global ID.

We recommend that you use the Cloudshelf Global Ids where possible, as these are guaranteed to be unique and will not change over time, however, we recognise there may be situations where you don't have the ability to store our global Ids, therefor do we allow you to query records using your external Global Id that was provided when the record is was ingested.

To query records using your external ID, you simply need to swap the app name provided in the global ID with external .

Example GlobalID for a Cloudshelf Record using an internal ID
Example GlobalID for a Cloudshelf Record using an external ID