Reference Codes

How to use reference codes to easily store and retrieve api objects, and wrap custom metadata

Introduction

Every item retrieved from our API includes a refCode field. This field contains a long string that acts as the unique identifier or ID for the item. This string is a base64-url safe encoded JSON object. The refCode is essential for retrieving the same item with consistent data across different retrieval methods due to the potential for multiple links and slight data variations within our system.

Example of a Reference Code

eyJhY3Rpb24iOiAicmVmZXJlbmNlIiwgImxhYmVsaWQiOiAiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIiwgInR5cGUiOiAicmVmZXJlbmNlIiwgInJlc3VsdGlkIjogIjE5MjgzNzU5MTIiLCAibWV0YWRhdGEiOiB7fX0=

Retrieval Using Reference Code

Items can be retrieved using the refCode via the Reference Code GET route in our API. Storing this refCode allows for the future retrieval of the item using a single identifier, ensuring consistency in the data returned.

Custom Metadata in Reference Codes

Adding Metadata

When performing a search, you can pass custom metadata, such as a lookup date, which will be encoded into the reference code of all returned items. For example, to add a lookup date:

?metadata=eyJsb29rdXBEYXRlIjogIjIwMjQtMDQtMjkifQ==

Decoding Metadata

To decode and retrieve this metadata from a refCode, perform the following operations:

1. Base64 URL-decode the refCode.

2. Convert the decoded string to a JSON object. The custom fields will be located in the metadata section of the JSON object.

Metadata Merging

If a refCode containing metadata is used in a request and additional custom metadata is passed as a query parameter, the returned refCode will merge both sets of metadata. In cases of key conflicts, the value from the custom metadata query parameter will take precedence.

Code Example: Decoding a Reference Code

Below is a Python example demonstrating how to decode a refCode:

import base64
import json

# Base64 URL-safe encoded string
encoded_str = "eyJhY3Rpb24iOiAicmVmZXJlbmNlIiwgImxhYmVsaWQiOiAiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIiwgInR5cGUiOiAicmVmZXJlbmNlIiwgInJlc3VsdGlkIjogIjE5MjgzNzU5MTIiLCAibWV0YWRhdGEiOiB7Imxvb2t1cERhdGUiOiAiMjAyNC0wNC0yOSJ9fQ=="

# Decode the Base64 URL-safe string
decoded_bytes = base64.urlsafe_b64decode(encoded_str)

# Convert the decoded bytes to a JSON object
decoded_json = json.loads(decoded_bytes.decode('utf-8'))

print(decoded_json)