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

Position	Name	Type	Required	Default Value	Description
0	reveal_bin	bool	false	false	Whether to reveal the card BIN or not
1	reveal_last4	bool	false	false	Whether 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
  }
}

Expression	Result
{{ 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"
}

Expression	Result
{{ 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

Position	Name	Type	Required	Default Value	Description
0	reveal_first_length	int	false	0	The number of characters to reveal from the beginning of the value
1	reveal_last_length	int	false	0	The number of characters to reveal from the end of the value

Examples

Given a token with the data:

{
  "id": "<expression>",
  "type": "token",
  "data": "ABC12345DEF67890"
}

Expression	Example 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

Position	Name	Type	Required	Default Value	Description
0	reveal_first_length	int	false	0	The number of characters to reveal from the beginning of the value
1	reveal_last_length	int	false	0	The number of characters to reveal from the end of the value

Examples

Given a token with the data:

{
  "id": "<expression>",
  "type": "token",
  "data": "ABC12345DEF67890"
}

Expression	Example 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

Position	Name	Type	Required	Default Value	Description
1	separator_char	string	false	``	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
  }
}

Expression	Result
{{ 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

Position	Name	Type	Required	Default Value	Description
1	date_expression	string	true	``	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
  }
}

Expression	Result
{{ 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

Position	Name	Type	Required	Default Value	Description
0	reveal_bin	bool	false	false	Whether to reveal the card BIN or not
1	reveal_last4	bool	false	false	Whether to reveal the last 4 digits or not
2	mask_char	char	false	X	The masking character
3	preserve_char	string	false	``	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
  }
}

Expression	Result
{{ 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"
}

Expression	Result
{{ 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

Position	Name	Type	Required	Description
0	json_path_expression	string	true	A 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
    }
  }
}

Expression	Result
{{ 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
  }
}

Expression	Result
{{ 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

Position	Name	Type	Required	Description
0	length	int	true	The number of characters in the resulting string
1	pad_char	char	true	A padding character

Examples

Given a token with the data:

{
  "id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
  "type": "token",
  "data": "1234"
}

Expression	Result
{{ 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

Position	Name	Type	Required	Description
0	length	int	true	The number of characters in the resulting string
1	pad_char	char	true	A padding character

Examples

Given a token with the data:

{
  "id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
  "type": "token",
  "data": "1234"
}

Expression	Result
{{ 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

Position	Name	Type	Required	Default Value	Description
0	reveal_first	int	false	0	The number of characters to reveal at the start
1	reveal_last	int	false	0	The number of characters to reveal at the end
2	mask_char	char	false	X	A masking character
3	preserve_chars	string	false	``	The characters to preserve

Examples

Given a token with the data:

{
  "id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
  "type": "token",
  "data": "3622-7206-2716-5567"
}

Expression	Result
{{ 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

Position	Name	Type	Required	Default Value	Description
0	length	int	true	null	The number of characters to reveal
1	mask_char	char	false	X	A masking character

Examples

Given a token with the data:

{
  "id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
  "type": "token",
  "data": "36227206271667"
}

Expression	Result
{{ 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
      }
    ]
  }
}

Expression	Result
{{ 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"
  }
}

Expression	Result
{{ 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"
  }
}

Expression	Result
{{ 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"
  }
}

Expression	Result
{{ data.numeric_value | to_string }}	"3.14159"
{{ data.boolean_value | to_string }}	"true"
{{ data.string_value | to_string }}	"foo"