Quiltt Logo

Custom Metadata

Core resources in Quiltt can be easily extended with additional custom information, using the metadata field.

Link to this section#Use Cases

The metadata field allows you to store arbitrary custom data in a structured manner. You can use this to store many types of static or dynamic information that may be useful to retrieve later. Below are some examples:

Link to this section#Static Data:

  • A Profile's nickname or pronoun
  • An internal ID or reference
  • An external identifier for a 3rd party system

Link to this section#Dynamic States:

  • When was the last time someone interacted with a Connection or Account?
  • Is an Account treated as "active" in your system?
  • Should a Transaction be hidden in your UI?

Link to this section#Supported Resources

The following resources currently expose a metadata field:

  • Profile
  • Connection
  • Account
  • Transaction

Link to this section#Examples

The below examples assume that you're interacting with a Profile through one of Quiltt's APIs. To start, we're going to use an end-user called who likes to be called Quiltty.

Link to this section#Adding Metadata

First let's add some metadata, which is initially null:

Link to this section#Payload

{
  "metadata": {
    "favoriteColor": "green",
    "nickname": "Quiltty"
  }
}

Link to this section#Updating a Metadata Value

Quiltty has decided that purple is now their favorite color. We can update that in the system simply by changing the value:

Link to this section#Payload

{
  "metadata": {
    "favoriteColor": "purple"
  }
}

The metadata will become:

{
  "favoriteColor": "purple",
  "nickname": "Quiltty"
}

Link to this section#Deleting Metadata

To delete just the favorite color, we can set the favoriteColor to null:

Link to this section#Payload

{
  "metadata": {
    "favoriteColor": null
  }
}

The favoriteColor key will be deleted and the metadata will become:

{
  "nickname": "Quiltty"
}

To entirely delete the metadata and reset it to its initial value, we can set it to null like so:

Link to this section#Payload

{
  "metadata": null
}

Link to this section#Restrictions

Custom metadata must be sent as a valid key-value JSON object, and must include at least 1 string key. There is a maximum capacity of 50 keys per record, with key names limited to 50 characters and values limited to 500 characters.

You should avoid storing any sensitive data that may contain PII (Personally Identifiable Information) in the metadata object. If you need to store sensitive data like emails, phone numbers or birthdays, use the dedicated fields on the Profile, which provide an additional level of encryption, as explained in the Core Concepts guide.

Webhooks →