External ids allow systems to set internal ids on items (files, urls, or folders) as they are created. We offer clients the ability to set both an externalId and an externalConnectionId though neither are required. These ids enable integrations to better manage, and track, content that has been loaded into the system.
- externalId should represent the id / document id of the asset from its source system
- externalConnectionId allows clients to define either a connection id or system id to track the integration source.
Duplication
Duplicate ids are accepted though we don't recommend having the same pairing of externalId and externalConnectionId
With external ids set the query endpoint (Get items via query) can be used to locate items by their external ids which will return the underlying information about an item that can later be used to call additional endpoints to directly manage content.
Examples
The following example shows how to define the body for externalId and externalConnectionId.
{
"id" : "211fad54-e981-43c0-a588-8c585828cf18",
"name" : "test file 1",
"description" : "This example demonstrates setting an external id and external connection id",
"externalId" : "12345",
"externalConnectionId" : "SystemABC"
}
The following example visually demonstrates 2 integrations with dropbox broken up by the external connection id.
[
{
"id" : "211fad54-e981-43c0-a588-8c585828cf18",
"name" : "test file 1",
"externalId" : "U200600",
"externalConnectionId" : "dropboxSync1"
},
{
"id" : "811fad54-e981-84c0-a588-8c5858288582",
"name" : "test file 2",
"externalId" : "U100900",
"externalConnectionId" : "dropboxSync2"
}
]