Sign In Try it free

Object Model

Item IDs

All items retrieved from underlying providers have a unique ID with which they can be referenced.

The ID is a compound of the Integration ID and the remote provider's item ID.

An item's WorkAPI ID can be determined by concatenating them (with a colon as separator) and encoding to a strict Base64 string: <integration_id>:<remote_id>.

The decoded concatenated ID string may also be right-padded with separators (colons, :) so as to avoid the = character added to the Base64 strings for padding.

Extracting the remote item ID using the SDK

This is handled under the hood when using the SDKs.

The SDKs will enable the developer to call item.integration_id and item.remote_id to retrieve the underlying IDs.

item = 'aW50ZWdyYXRpb25fMTIzOmVtYWlsX3h5eDo6')
item.integration_id # => 'integration_123'
item.remote_id # => 'email_xyz'

Building the WorkAPI ID using the SDK

Conversely, when setting item.integration_id and item.remote_id manually, the WorkAPI ID is calculated automatically:

item = 'email_xyz', integration_id: 'integration_123') # => 'aW50ZWdyYXRpb25fMTIzOmVtYWlsX3h5eDo6' 

# Note: as mentioned, this is padded to avoid '==' on the base64 string
#       Without paddding, the Base64 output is 'aW50ZWdyYXRpb25fMTIzOmVtYWlsX3h5eA=='
#       Both strings will be handled in the same way by the API

Working with IDs outside of the SDK

Without using the SDK, the ID can be generated as follows:

remote_id = 'email_xyz'
integration_id = 'integration123'

encoded_id = Base64.strict_encode64("#{integration_id}:#{remote_id}")
encoded_id # => 'aW50ZWdyYXRpb25fMTIzOmVtYWlsX3h5eDo6'

And the inverse

id = 'aW50ZWdyYXRpb25fMTIzOmVtYWlsX3h5eDo6'

decoded_id = Base64.strict_decode64(id)
integration_id, remote_id = decoded_id.split(':')

integration_id # => 'integration123'
remote_id # => 'email_xyz'

First 50,000 requests are free every month