Custom Data

Get Started

All Tight API entities have a customData parameter. Use this parameter to attach freeform JSON data to Tight API entities. Custom data can be used to add additional, structured information on an entity. For example, you can add an internal identifier to a Bank Transaction or specialized tax info on a user’s General Ledger accounts:

curl -X POST https://sandbox.tight.com/v6/banks/transactions \
-H 'Authorization: Bearer <access_token>' \
-D '[{
        "id": "btn_936723",
        "customData": {
            "internal_key": "some_internal_key",
            "some_other_field": 23434
        }
    }]'

customData can support up to 50 fields and up to 2000 characters of freeform JSON data

Once added, this bank transaction’s customData will be included anywhere else the transaction can be fetched from the Tight API. For example, the response to the following request includes the customData set on this bank transaction:

curl -X GET 'https://sandbox.tight.com/v6/banks/transactions/btn_936723' \
-H 'Authorization: Bearer <access_token>'

{
    "result": "SUCCESS",
    "data": {
        "id": "btn_936723",
        "type": "REVENUE",
        "amount": 15399,
        "customData": {
            "internal_key": "some_internal_key",
            "some_other_field": 23434
        }
        /* remainder of the properties on this bank transaction */
    },
    "error": []
}

The customData object now appears in the response, you can leverage this functionality to enhance integrations, reporting, or internal workflows.

Update custom data

When you update an entity, customData is merged per key into the existing value, rather than replacing it. Each top-level key in the request is handled on its own:

Key in the request	Result
Omitted	The existing value for that key is kept
Present with a value	The value is set, replacing any existing value for that key
Present with `null`	The key is removed

To clear all custom data on the entity, send "customData": null. Omitting customData from the request leaves it unchanged. The merge is one level deep. Arrays and nested objects are treated as a single value and are replaced whole, never merged into.

You can’t store a literal null as a value, because null means “delete this key”. If you need to represent an empty value, use a different sentinel, such as an empty string or false.

Examples

Each example below starts from the existing customData shown under Before, then sends the customData shown under Request in an update, such as this bank transaction update:

curl -X POST https://sandbox.tight.com/v6/banks/transactions \
-H 'Authorization: Bearer <access_token>' \
-D '[{
        "id": "btn_936723",
        "customData": { "some_other_field": 50000 }
    }]'

Add a key
Overwrite a key
Delete a key
Replace a nested object
Clear all

Before

{ "internal_key": "some_internal_key" }

Request

{ "region": "northeast" }

After

{ "internal_key": "some_internal_key", "region": "northeast" }

Before

{ "internal_key": "some_internal_key", "some_other_field": 23434 }

Request

{ "some_other_field": 50000 }

After

{ "internal_key": "some_internal_key", "some_other_field": 50000 }

Before

{ "internal_key": "some_internal_key", "some_other_field": 23434 }

Request

{ "some_other_field": null }

After

{ "internal_key": "some_internal_key" }

Before

{ "internal_key": "some_internal_key", "prefs": { "email": true, "sms": false } }

Request

{ "prefs": { "sms": true } }

After

{ "internal_key": "some_internal_key", "prefs": { "sms": true } }

The whole prefs object is replaced, so email is dropped. To keep it, send the full object: { "prefs": { "email": true, "sms": true } }. Arrays behave the same way.

Before

{ "internal_key": "some_internal_key", "some_other_field": 23434 }

Request

null

Send "customData": null in the request body, rather than an object.

After

null

Filter on custom data

Coming soon

Patterns

Reference

Get Started

Update custom data

Examples

Filter on custom data

​Get Started

​Update custom data

​Examples

​Filter on custom data

Get Started

Update custom data

Examples

Filter on custom data