Skip to main content

Filters

Oftentimes data may be tokenized in one format, but you wish to use this data in a different format within a request. Several pieces of data may be stored together in a single token (e.g., a user record containing first and last names and contact information), but you wish to only use a single piece of that data within a Proxy or Reactor request, or you may wish to reformat the data before indexing it for search (e.g., use only the last name, but normalize by uppercasing it).

To allow you complete flexibility, transformation functions called filters can be applied within any expression. Generally, a variable's value can be transformed by specifying a filter after the | symbol:

{{ <variable> | <filter> }}

You can effectively think of this as "piping" a variable into the filter in the same way you may be familiar with the "pipe" operator from Unix-like systems. Multiple filters can be chained together by "piping" the result of each filter into the next, applying in order from left to right:

{{ <variable> | <filter1> | <filter2> | ... }}

All standard Liquid filters are supported within expressions. For example, given a token containing a name object containing both first and last name properties:

{
"data": {
"name": "John Doe"
},
...
}

We can create an expression to return the upper-cased last name by splitting on the space character, grabbing the last element, and upper-casing:

{{ data.name | split: ' ' | last | upcase }}

This expression would evaluate to the value "DOE".

In addition to the standard Liquid filters, several custom filters are also available:

alias_card

Randomly generates a unique alias that preserves the format of the card number, optionally revealing the card's BIN and last 4 digits. If the card's length without the preserved character is less than 16 digits, the card BIN will be 6 digits long, 8 otherwise.

The special characters preserved are the traditional card number delimiters such as " " and "-". If the card number length is less than the revealed length, an error is returned.

Parameters

PositionNameTypeRequiredDefault ValueDescription
0reveal_binboolfalsefalseWhether to reveal the card BIN or not
1reveal_last4boolfalsefalseWhether to reveal the last 4 digits or not

Examples

Card token type

Given a token with the data:

{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "card",
"data": {
"number": "3622720627165567",
"expiration_month": 10,
"expiration_year": 2028
}
}
ExpressionResult
{{ data.number | alias_card }}"3292231249202291"
{{ data.number | alias_card: 'false', 'false' }}"2012232912901293"
{{ data.number | alias_card: 'true', 'false' }}"3622720629129014"
{{ data.number | alias_card: 'true', 'true' }}"3622720639185567"
{{ data.number | alias_card: 'false', 'true' }}"4024420198125567"
Card number with delimiters

Given a token with the data:

{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": "3622-7206-2716-5567"
}
ExpressionResult
{{ data | alias_card }}"3292-2312-4920-2291"
{{ data | alias_card: 'false', 'false' }}"2012-2329-1290-1293"
{{ data | alias_card: 'true', 'false' }}"3622-7206-2912-9014"
{{ data | alias_card: 'true', 'true' }}"3622-7206-3918-5567"
{{ data | alias_card: 'false', 'true' }}"4024-4201-9812-5567"

alias_preserve_format

Randomly generates a unique alias that preserves the format of the input string, optionally revealing a specified number of characters from the beginning and end of the value.

Alpha characters are replaced with randomized alpha characters, numeric characters are replaced with randomized numeric characters, and special characters and whitespace are preserved.

Parameters

PositionNameTypeRequiredDefault ValueDescription
0reveal_first_lengthintfalse0The number of characters to reveal from the beginning of the value
1reveal_last_lengthintfalse0The number of characters to reveal from the end of the value

Examples

Given a token with the data:

{
"id": "<expression>",
"type": "token",
"data": "ABC12345DEF67890"
}
ExpressionExample Result
{{ data | alias_preserve_format }}"xir83203hqn73599"
{{ data | alias_preserve_format: 3 }}"ABC83203hqn73599"
{{ data | alias_preserve_format: 0, 5 }}"xir83203hqn67890"
{{ data | alias_preserve_format: 3, 5 }}"ABC83203hqn67890"

alias_preserve_length

Randomly generates a unique alias that preserves the length of the input string, optionally revealing a specified number of characters from the beginning and end of the value.

All characters are replaced with randomized alphanumeric characters. The type of the character in each position is not preserved, e.g., alpha characters may be replaced with numeric characters and vice versa. Special characters and whitespace are not preserved and will be replaced with alphanumeric characters.

Parameters

PositionNameTypeRequiredDefault ValueDescription
0reveal_first_lengthintfalse0The number of characters to reveal from the beginning of the value
1reveal_last_lengthintfalse0The number of characters to reveal from the end of the value

Examples

Given a token with the data:

{
"id": "<expression>",
"type": "token",
"data": "ABC12345DEF67890"
}
ExpressionExample Result
{{ data | alias_preserve_length }}"v38anr9m2cx0giw7"
{{ data | alias_preserve_length: 3 }}"ABCanr9m2cx0giw7"
{{ data | alias_preserve_length: 0, 5 }}"v38anr9m2cx67890"
{{ data | alias_preserve_length: 3, 5 }}"ABCanr9m2cx67890"

card_bin

Returns the card's BIN, which is 6 digits for card numbers with less than 16 digits and 8 otherwise. If the card number contains a character separator like 4242-4242-4242-4242, it can be passed in so it is not part of the returned BIN.

Parameters

PositionNameTypeRequiredDefault ValueDescription
1separator_charstringfalse``The card number separator character

Examples

Given a token with the data:

{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "card",
"data": {
"number": "3622720627165567",
"expiration_month": 10,
"expiration_year": 2028
}
}
ExpressionResult
{{ data.number | card_bin }}"42424242"

card_exp

Returns the card's expiration date in a given format. The format can be specified using a combination of the following placeholders:

  • MM: 2-digit month
  • MMYY: 2-digit month, year
  • YYYY: 4-digit year
  • YYYY-MM: 4-digit year, 2-digit month
  • MM/YY: 2-digit month, 2-digit year
  • MM/YYYY: 2-digit month, 4-digit year
  • MM_YYYY: 2-digit month, 4-digit year
  • MM-YYYY: 2-digit month, 4-digit year

Parameters

PositionNameTypeRequiredDefault ValueDescription
1date_expressionstringtrue``The card number expiration expression

Examples

Card token type

Given a token with the data:

{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "card",
"data": {
"number": "3622720627165567",
"expiration_month": 10,
"expiration_year": 2028
}
}
ExpressionResult
{{ data | card_exp: 'MM' }}"10"
{{ data | card_exp: 'MMYY' }}"1028"
{{ data | card_exp: 'MM/YY' }}"10/28"
{{ data | card_exp: 'YYYY' }}"2028"
{{ data | card_exp: 'YYYY-MM' }}"2028-10"
{{ data | card_exp: 'YYYY/MM' }}"2028/10"

card_mask

Returns a masked version of the card number, optionally revealing the card's BIN and last 4 digits. If the card's length without the preserved character is less than 16 digits, the card BIN will be 6 digits long, 8 otherwise. If the resulting masked string equals the original unmasked value, the whole value is masked.

Parameters

PositionNameTypeRequiredDefault ValueDescription
0reveal_binboolfalsefalseWhether to reveal the card BIN or not
1reveal_last4boolfalsefalseWhether to reveal the last 4 digits or not
2mask_charcharfalseXThe masking character
3preserve_charstringfalse``The character to preserve

Examples

Card token type

Given a token with the data:

{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "card",
"data": {
"number": "3622720627165567",
"expiration_month": 10,
"expiration_year": 2028
}
}
ExpressionResult
{{ data.number | card_mask: 'false', 'false', 'X', '-' }}"XXXXXXXXXXXXXXXX"
{{ data.number | card_mask: 'true', 'false', 'X', '-' }}"36227206XXXXXXXX"
{{ data.number | card_mask: 'true', 'true', '#', '-' }}"36227206####5567"
{{ data.number | card_mask: 'false', 'true', 'X', '-' }}"XXXXXXXXXXXX5567"
Card number with delimiters

Given a token with the data:

{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": "3622-7206-2716-5567"
}
ExpressionResult
{{ data | card_mask: 'false', 'false', 'X', '-' }}"XXXX-XXXX-XXXX-XXXX"
{{ data | card_mask: 'true', 'false', 'X', '-' }}"3622-7206-XXXX-XXXX"
{{ data | card_mask: 'true', 'true', '#', '-' }}"3622-7206-####-5567"
{{ data | card_mask: 'false', 'true', 'X', '-' }}"XXXX-XXXX-XXXX-5567"

json

Evaluates a JSON Path expression (proposed spec) on the input object.

All standard JSON Path syntax is supported, provided that the expression resolves to a single value. If the expression resolves to multiple values, the request will result in a 400 error.

While Liquid supports a very similar syntax to JSON path when selecting properties within a JSON object (e.g., \{\{ data.bicycle.color }}), it does not support more complex JSON Path expressions (e.g., array filter expressions like $.books[?(@.price < 10)].title). The json filter provides further flexibility for evaluating complex JSON Path expressions.

Parameters

PositionNameTypeRequiredDescription
0json_path_expressionstringtrueA JSON Path expression

Examples

Given a token with the data:

{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": {
"books": [
{
"category": "fiction",
"author": "Herman Melville",
"title": "Moby Dick",
"isbn": "0-553-21311-3",
"price": 8.99
},
{
"category": "fantasy",
"author": "J. R. R. Tolkien",
"title": "The Lord of the Rings",
"isbn": "0-395-19395-8",
"price": 22.99
}
],
"bicycle": {
"color": "red",
"price": 19.95
}
}
}
ExpressionResult
{{ data.bicycle.color }}"red"
{{ data | json: '$.bicycle.color' }}"red"
{{ data | json: '$.bicycle.price' }}"19.95"
{{ data.bicycle }}{ "color": "red", "price": 19.95 }
{{ data | json: '$.books[0].author' }}"Herman Melville"
{{ data | json: '$.books[?(@.price < 10)].title' }}"Moby Dick"
{{ data.nonexistent }}null
{{ data | json: '$.book..author' }}<400 Error>

last4

Returns the last 4 characters of a string. If the string's length is less than 4, the whole value is returned.

Parameters

None

Examples

Given a token with the data:

{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "card",
"data": {
"number": "3622720627165567",
"expiration_month": 10,
"expiration_year": 2028
}
}
ExpressionResult
{{ data.number | last4 }}"1667"
{{ data.number | slice: 12, 2 | last4 }}"67"

pad_left

Returns a new string of the desired length by padding the input string on the left with the specified padChar.

Returns null when provided a null input value.

Parameters

PositionNameTypeRequiredDescription
0lengthinttrueThe number of characters in the resulting string
1pad_charchartrueA padding character

Examples

Given a token with the data:

{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": "1234"
}
ExpressionResult
{{ data | pad_left: 6, '0' }}"001234"
{{ data | pad_left: 6, 'X' }}"XX1234"
{{ data | pad_left: 4, '0' }}"1234"
{{ data | pad_left: 2, '0' }}"1234"

pad_right

Returns a new string of the desired length by padding the input string on the right with the specified padChar.

Returns null when provided a null input value.

Parameters

PositionNameTypeRequiredDescription
0lengthinttrueThe number of characters in the resulting string
1pad_charchartrueA padding character

Examples

Given a token with the data:

{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": "1234"
}
ExpressionResult
{{ data | pad_right: 6, '0' }}"123400"
{{ data | pad_right: 6, 'X' }}"1234XX"
{{ data | pad_right: 4, '0' }}"1234"
{{ data | pad_right: 2, '0' }}"1234"

reveal

Returns a masked version of the string revealing characters at the start and end whilst preserving others. If the string's length is less than or equal to reveal_first + reveal_last, or the resulting masked string equals the original unmasked value, the whole value is masked.

Parameters

PositionNameTypeRequiredDefault ValueDescription
0reveal_firstintfalse0The number of characters to reveal at the start
1reveal_lastintfalse0The number of characters to reveal at the end
2mask_charcharfalseXA masking character
3preserve_charsstringfalse``The characters to preserve

Examples

Given a token with the data:

{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": "3622-7206-2716-5567"
}
ExpressionResult
{{ data | reveal: 6 }}"3622-7XXXXXXXXXXXXX"
{{ data | reveal: 7, 5 }}"3622-72XXXXXXX-5567"
{{ data | reveal: 7, 5, '#' }}"3622-72#######-5567"
{{ data | reveal: 7, 4, '#', "-" }}"3622-72##-####-5567"
{{ data | reveal: 10, 9 }}"XXXXXXXXXXXXXXXXXXX"

reveal_last

Returns the last length characters of a string. If the string's length is less than or equal to length, the whole value is returned.

Parameters

PositionNameTypeRequiredDefault ValueDescription
0lengthinttruenullThe number of characters to reveal
1mask_charcharfalseXA masking character

Examples

Given a token with the data:

{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": "36227206271667"
}
ExpressionResult
{{ data | reveal_last: 6 }}"XXXXXXXX271667"
{{ data | reveal_last: 3, '#' }}"###########667"

stringify

Returns a JSON serialized string of the input object.

Returns null when provided a null input value.

Parameters

None

Examples

Given a token with the data:

{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": {
"books": [
{
"category": "fiction",
"author": "Herman Melville",
"title": "Moby Dick",
"isbn": "0-553-21311-3",
"price": 8.99
},
{
"category": "fantasy",
"author": "J. R. R. Tolkien",
"title": "The Lord of the Rings",
"isbn": "0-395-19395-8",
"price": 22.99
}
],
"bicycles": [
{
"color": "red",
"price": 19.95
},
{
"color": "blue",
"price": 24.95
}
]
}
}
ExpressionResult
{{ data.books[0].price | stringify }}"8.99"
{{ data.books[1].title | stringify }}"The Lord of the Rings"
{{ data.bicycles[1] | stringify }}"{\"color\":\"red\",\"price\":19.95}"
{{ data.bicycles | stringify }}"[{\"color\":\"red\",\"price\":19.95},{\"color\":\"blue\",\"price\":24.95}]"

to_boolean

Casts the input value to a boolean value.

Returns null when provided a null input value. Returns an error when the input cannot be cast to a boolean.

Parameters

None

Examples

Given a token with the data:

{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": {
"true_string": "true",
"false_string": "false"
}
}
ExpressionResult
{{ data.true_string | to_boolean }}true
{{ data.false_string | to_boolean }}false

to_number

Casts the input value to a numeric value.

Returns null when provided a null input value. Returns an error when the input cannot be cast to a number.

Parameters

None

Examples

Given a token with the data:

{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": {
"int_string": "42",
"decimal_string": "3.14159"
}
}
ExpressionResult
{{ data.int_string | to_number }}42
{{ data.decimal_string | to_number }}3.14159

to_string

Casts the input value to a string value.

Returns null when provided a null input value. Returns an error when the input cannot be cast to a string (e.g., for complex object values).

Parameters

None

Examples

Given a token with the data:

{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": {
"numeric_value": 3.14159,
"boolean_value": true,
"string_value": "foo"
}
}
ExpressionResult
{{ data.numeric_value | to_string }}"3.14159"
{{ data.boolean_value | to_string }}"true"
{{ data.string_value | to_string }}"foo"