Skip to main content
Custom BuildsReady-to-Launch
Sandbox

Tags

Unit allows you to attach your own metadata to most entities in the form of tags (key-value pairs). Tags are often used to connect entities on Unit to entities and concepts on your platform.

Examples:

  • Attaching the tag my_customer_id = 3551 to a customer entity on Unit, in order to connect it to a customer identifier on your platform.
  • Attaching the tag purpose = tax to a deposit account entity on Unit, in order to help your code treat it as the destination for a customer's tax funds.
{
    "data": {
        "type": "depositAccount",
        "attributes": {
        /// ...
        "tags": {
            "purpose": "tax",
            "my_account_id": "b6f395c9-e58a-40a5-a5a4-901d603440b9"
        }
    },
    /// ...
}

Tags can help you in a few important ways:

  • You can filter by them when using API endpoints. Example: calling the List Customers endpoint with my_customer_id = 3551 will return one customer only, if it's the only one that you attached this tag to.
  • They appear on entities in API responses and webhook events. Example: when receiving the customer.created webhook event, the customer entity will include the tag my_customer_id = 3551, if you previously attached it.
  • They are shown in the Dashboard when you view the entity it's attached to. This could help your operations team understand the context for entities on Unit. Example: knowing immediately which customer on your system a customer on Unit refers to.

Filtering by Tags​

The List operation under certain resources (such as Application, Customer or Payment) supports searching by tags. You can search by passing any number of key-value pairs. The response will include the resources whose tags contain the key-value pairs you specified, based on the principles of JSON containment.

Example uses:

  • Assume you attach 5 different tags to all applications you create on Unit. One of these tags is a my_customer_id tag that helps you connect every Unit application to a unique customer identifier in your app. To search for the application that belongs to a known customer, specify a key-value pair in the following way: { "my_customer_id": "b6f395c9-e58a-40a5-a5a4-901d603440b9" }
  • Assume you attach 4 different tags to all book transfers you create on Unit. Two of these tags are is_loan and number_of_repayments. To search for all loans that have four repayments, specify two key-value pairs in the following way: { "is_loan": "true", "number_of_repayments": "4" }

Updating Tags​

You can add, update or delete tags from resources with the tags attribute on their corresponding Update operation (for example, Update Deposit Account).

Unit follows the JSON Merge Patch RFC when updating the tags. In general:

  • To add or update a tag, specify its key and value.
  • To delete a tag, specify its key and null for the value.

Tag Inheritance​

Some entities are created as a result of you creating a source entity. For example, a Customer is created once you create an Application and it's approved.

In these cases, entities inherit all tags from their source entity:

Tag Constraints​

  • Maximum number of tags per resource: 30
  • Keys and values are case-sensitive
  • Key constraints: 128 characters consisting of letters, numbers and underscores
  • Value constraints: 256 characters