Key Value Pairs

While our APIs aim to provide dedicated named attributes for most data points, some data requires more flexibility. For these cases, we use Key-Value Pairs (KVPs) - an array of additional data that allows for dynamic attribute storage.

These KVPs are “loosely typed” - all values are stored as strings, though you can specify a type to provide usage hints. Note that type specifications are generally not strictly enforced.

Understanding KVP Types

KVP types help describe the data content and its intended use. Here’s what you need to know about the different categories:

  • general.* - For common data types (string, integer, float, etc.)
  • raw.* - For storing binary or unprocessed data (Base64 encoded)
  • id.* - For data that can be used to create document objects/entities
  • id.external - For capturing external service IDs (searchable in the index)

id.external is distinct from result.id. When attached to an entity’s extraData KVP array, id.external values become searchable via the /search API.

  • defunct - Marks deleted KVPs where value retention is required
  • result.* - Captures external service responses and transaction IDs
  • error.* - Handles non-critical error information
  • transient.* - Temporary values that exist only during the initial service call

Complete Type Reference

  - defunct 
  - general.string 
  - general.integer 
  - general.float 
  - general.bool 
  - general.date 
  - general.datetime
Best Practice

When working with sensitive data that needs to be used only once, consider using transient.* types. These values are processed during the initial call but aren’t persisted in storage.

Built with