Payload field transformers

A very important feature in Lead Prosper is the ability to modify or transform the data passed by the suppliers before it's sent to the buyer.

This is needed in most multi buyer setups, where your supplier is passing data in a format that your buyer might not accept. Take for example a phone number. Your supplier might send it as 1 (313) 249-2384. However, your buyer wants it as 3132492384. No spaces, no extra characters, no country code.

For this purpose, Lead Prosper created a couple of handy modifiers that you can use when building your payloads to help you transform the data.

How To
Practical Example
Available Transformers
Important Notes
Appendix A - Special Characters
Appendix B - Valid Date Formats
Appendix C - Output Date Formats

How to use Field Transformers

To use any transformer on any dynamic field, all you need to do is add the || symbol inside the merge tag. Example: {{Field||Transformer:Parameter}}

Some transformers need parameters, like date, where you can pass the format in which you want to get the date. Consult the table bellow for all the available transformers and their parameters.

You can use more than 1 modifier for 1 string. Example: {{Field||Transformer1||Transformer2||Transformer3}} {{field||replace:Male@@M||replace:Female@@F}}

Some transformers will need more than 1 parameter. Parameters are delimited by @@. Example: {{Field||chars:0@@4}}.

Field transformers can be use in the following places:

real-time and webhook payload builder, for both HTTP or Email delivery
direct post and ping/post URLs
direct post and ping/post headers

Practical Example

Let's assume we have the following multi buyer campaign:

Our supplier generates the following lead:

first_name: David
dob: 02/12/1967
phone_number: 1 (619) 267-4352
income: $100,000
email: david@company.com

Our buyer John would like to receive the first name in upper case, lead's age instead of dob and income as a number.

On the other hand, Jane would like to receive the first name lower case, email as md5 hash, and phone as a 10-digit phone number.

To make this possible, we have to apply the following transformers to our campaign fields before we send the data to the buyer:

to get the upper case name, we will use {{first_name||upper_case}}
to get the lower case name, we will use {{first_name||lower_case}}
to get the age for John, we will use {{dob||age}}
to get the income as number, we will use {{income||number}}
to get the md5 hash of the email, we will use {{email||encode:md5}}
to get the phone as a 10 digit number, we will use {{phone_number||phone:10}}

Here is the final payload for John

Available transformers

camel_case	number	append
kebab_case	phone	prepend
lower_case	age	pad_left
upper_case	date	pad_right
pascal_case	encode	pad_both
snake_case	decode	trim
upper_first	escape	replace
lower_first	chars	fallback
slug	remove_chars	us_state
title	first	to_bool
mask	last	from_bool
if_else	if_else_between	height
math_add	math_multiply	math_ceil
math_sub	math_divide	math_floor
math_modulo	date_add	date_sub
date_diff	timezone

# camel_case

Transforms the given input to camel case format.

Examples

Given your input is My name is John, applying ||camel_case will transform it to myNameIsJohn

# kebab_case

Transforms the given input to kebab case format.

Examples

Given your input is my name is john, applying ||kebab_case will transform it to my-name-is-john

Given your input is MY name IS John, applying ||kebab_case will transform it to m-y-name-i-s-john

# lower_case

Transforms the given input to lower case format.

Examples

Given your input is MY NAME IS JOHN, applying ||lower_case will transform it to my name is john

# upper_case

Transforms the given input to upper case format.

Examples

Given your input is my name is John, applying ||upper_case will transform it to MY NAME IS JOHN

# pascal_case

Transforms the given input to pasca case format.

Examples

Given your input is my name is john, applying ||pascal_case will transform it to MyNameIsJohn

Given your input is MY name IS John, applying ||pascal_case will transform it to MYNameISJohn

# snake_case

Transforms the given input to snake case format.

Examples

Given your input is my name is john, applying ||snake_case will transform it to my_name_is_john

Given your input is MY name IS John, applying ||snake_case will transform it to m_y_name_i_s_john

# slug

Transforms the given input to a URL slug format.

Examples

Given your input is My name is John, applying ||slug will transform it to my-name-is-john

# title

Transforms the given input into a title.

Examples

Given your input is my name is john, applying ||title will transform it to My Name Is John

# number

Strips the given input of any characters that are not decimal.

Params

DECIMALS: Optional. If provided, the output will contain the configured number of DECIMALS, without rounding.

Examples

Given your input is $12,345.67, applying ||number will transform it to 12345.67

Given your input is $12,345.67, applying ||number:0 will transform it to 12345

Given your input is $12,345.67, applying ||number:1 will transform it to 12345.6

# phone

Strips the given input of any characters that are not decimal.

Params

LENGTH: Optional. If provided, the output will contain only the last LENGTH characters.

Examples

Given your input is 1 (543) 221-6734, applying ||phone will transform it to 15432216734

Given your input is 1 (543) 221-6734, applying ||phone:10 will transform it to 5432216734

# age

Converts a valid formatted date to a number, representing the age.

Params

DECIMALS: Optional. If provided, the output will contain the configured number of DECIMALS.

Examples

Given your input is 1965/07/22 and the current date is 2021/03/31, applying ||age will transform it to 55

Given your input is 1965/07/22 and the current date is 2021/03/31, applying ||age:2 will transform it to 55.73

# mask

Replaces any input with ***

Examples

Given your input is a random text, applying ||mask will transform it to ***

# upper_first

Converts the first character of an input to upper case.

Examples

Given your input is my name is john, applying ||upper_first will transform it to My name is john

# lower_first

Converts the first character of an input to upper case.

Examples

Given your input is My name is John, applying ||lower_first will transform it to my name is John

# encode

Encodes a given input to a specified format. Available formats are: base64,md5,sha1,url,sha256,sha512

Examples

Given your input is my name is john, applying ||encode:base64 will transform it to bXkgbmFtZSBpcyBqb2hu

Given your input is my name is john, applying ||encode:md5 will transform it to bc6c896afca1a6f10af0fade0fa4d251

Given your input is my name is john, applying ||encode:sha1 will transform it to 22018acc5659c6946f43e574db7635f1f3861fc7

Given your input is my email is john@doe.com, applying ||encode:url will transform it to my+email+is+john%40doe.com

Given your input is my name is john, applying ||encode:sha256 will transform it to 96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a

Given your input is my name is john, applying ||encode:sha512 will transform it to b7fcc6e612145267d2ffea04be754a34128c1ed8133a09bfbbabd6afe6327688aa71d47343dd36e719f35f30fa79aec540e91b81c214fddfe0bedd53370df46d

# decode

Decodes a given input from a specified format. Available formats are: base64,url

Examples

Given your input is bXkgbmFtZSBpcyBqb2hu, applying ||decode:base64 will transform it to my name is john

Given your input is my+email+is+john%40doe.com, applying ||decode:url will transform it to my email is john@doe.com

# escape

Escapes single quote ', double quote " and backslash \ characters

Examples

Given your input is my name is "john", applying ||escape will transform it to my name is \"john\"

Given your input is my name is 'john', applying ||escape will transform it to my name is \'john\'

Given your input is my name is \john\, applying ||escape will transform it to my name is \\john\\

# trim

Remove whitespaces from start and end of the input.

Examples

Given your input is my name is john , applying ||trim will transform it to my name is john

# chars

Extracts a given number of characters from the input begging from a starting position.

Params

START: Required. First letter is 0. Can also be negative.
LENGTH: Optional. Total number of characters to extract

Examples

Given your input is 1234 is your code, applying ||chars:0@@4 will extract 4 characters from position 0, returning 1234

Given your input is your code is: 1234, applying ||chars:-4 will extract the last 4 characters, returning 1234

Given your input is use 123456 to login, applying ||chars:4@@6 will extract 6 characters from position 4, returning 123456

Given your input is your login code is: X3G4, applying ||chars:19 will extract all characters from position 19 to the end, returning X3G4

# last

Extract the last given number of characters from the input.

LENGTH: Required. Total number of characters to extract

Examples

Given your input is your code is: 1234, applying ||last:4 will return 1234

# first

Extract the first given number of characters from the input.

LENGTH: Required. Total number of characters to extract

Examples

Given your input is 1234 is your code, applying ||first:4 will return 1234

# append

Add a given string/character at the end of the input.

STRING: Required. String/character to append

Examples

Given your input is my name is, applying ||append:john will transform it my name is john

# prepend

Add a given string/character at the end of the input.

STRING: Required. String/character to prepend

Examples

Given your input is John, applying ||prepend:Customer name is: will transform it Custom name is: John

# pad_left

Adds a given string/character sequence to the left (beginning) of the input, until the final output is of desired length. This can be useful to add leading 0 to numbers under 10, for example for days or months in the year.

LENGTH: Required. Final desired string length, after concatenation
STRING: Required. String/character to use

Examples

Given your input is 1, applying ||pad_left:2@@0 will transform it to 01

Given your input is my name is john, applying ||pad_left:20@@# will transform it to #####my name is john

# pad_right

Same as pad_left, but the string is added to right (end) of the input.

LENGTH: Required. Final desired string length, after concatenation
STRING: Required. String/character to use

Examples

Given your input is my name is john, applying ||pad_right:20@@# will transform it to my name is john#####

# pad_both

Same as pad_left and pad_right, but the string is added to both left (beginning) and right (end) of the input.

LENGTH: Required. Final desired string length, after concatenation
STRING: Required. String/character to use

Examples

Given your input is my name is john, applying ||pad_both:20@@# will transform it to ##my name is john###

# replace

Replaces a string/character with another string/character. This method is case sensitive. As a result, JOHN will not match john

SOURCE: Required. String/character to replace
DESTINATION: Optional. String/character to use as replacement. If empty, SOURCE will be removed.

Examples

Given your input is my_name_is_john, applying ||replace:_@@^ will transform it to my^name^is^john

Given your input is my name is john, applying ||replace:john@@jane will transform it to my name is jane

Given your input is my name is john, applying ||replace:JOHN@@jane will transform it to my name is john

Given your input is your code is 1234, applying ||replace:your will transform it to code is 1234

# remove_chars

Finds and remove a list of characters from the input. This method is case sensitive. As a result, J will not match j

This method will remove invididual characters, not strings. Use replace if you need to remove full words.

LIST: Required. List of characters to remove

Examples

Given your input is my name is john, applying ||remove_chars:mn will transform it to y ae is joh

Given your input is my name is john, applying ||remove_chars:MN will transform it to my name is john

# fallback

This method allows you to set a default value for an empty input parameter.

STRING: Required. String to return

Examples

Given your input is my name is john, applying ||fallback:this is a test will return my name is john, because your input field is not empty.

Given your input is , applying ||fallback:this is a test will return this is a test

# date

This method allows you to format a valid formatted date to another format. Check Appendix C for possible output formats.

OUTPUT FORMAT: Required. Valid date format
SOURCE FORMAT: Optional. The source format of the date value. IMPORTANT: This field is required when your date starts with the month (m/d/Y, m-d-Y, etc)

Examples

Given your input is 2015/07/21, applying ||date:Y-m-d\TH:i:s\Z will transform it 2015-07-21T00:00:00Z

Given your input is 2015-07-21 01:23:45 PM, applying ||date:Y-m-d H:i:s will transform it 2015-07-21 13:23:45

Given your input is 2020-02-03 23:45:23, applying ||date:Y-m-d h:i:s A will transform it 2020-02-03 11:45:23 PM

Given your input is 07-23-2000 and your field date format is 01/15/2000 (m/d/Y), applying ||date:Y-m-d will fail, because the date starts with a month. Applying ||date:Y-m-d@@m/d/Y will transform the date to 2000-07-23. Please make sure the SOURCE FORMAT matches your campaign field date format, otherwise the transformer will ignore the date.

# date_add

This method allows you to add an interval of time to a date.

INTERVAL: Required. Valid interval. Possible values are: Y, M, W, D, h, m, s

Important notes:

The date might not start with the month. Please use the date transformer to format the date to a different format before applying date_add or date_sub transformers
The output value will always be in this format: Y-M-D H:M:S, regardless if the input date was just Y-M-D or any other format. As such, it might be required that, after applying this transfomer, you will need to use the date transformer to correct the output.
You can use any combination of the intervals, and omit the ones with 0. Ex: 1M 1m 10s will add 1month, 1minute and 10seconds. The only caveat is to not add the weeks before the month.

Examples

Given your input is 2015/07/21, applying ||date_add:1Y 1M 1D will transform it 2016-08-22 00:00:00

Given your input is 2015-07-21 01:23:45 PM, applying ||date_add:3h 10m 15s will transform it 2015-07-21 04:34:00

# date_sub

This method allows you to subtract an interval of time from a date.

INTERVAL: Required. Valid interval. Possible values are: Y, M, W, D, h, m, s

Please check date_add transformer for more info.

# date_diff

This method allows you to calculate the difference between a given date and today's date

INTERVAL: Required, interval in which the diff is calculated. Possible values are: days, months, years

Important notes:

The date might not start with the month. Please use the date transformer to format the date to a different format before applying this transformers

Combined with if_else_between transformer, you can easily transform a date to a text. Say we have the incident date and we need to send to our a buyer one of the following intervals: In the last month, More than a month ago, More than a year ago. To do so, we will apply the date_diff:months transformer and combine it with if_else_between to transform a number (the number of months since the incident) to the desired buyer interval.

Examples

Given your input is 2015/07/21, applying || date_diff:months will transform it 86, assuming today's date is 2022-10-10.

Given your input is 2015-07-21 01:23:45 PM, applying ||date_diff:years will transform it 7, assuming today's date is 2022-10-10.

# timezone

This method allows you to convert the timezone for a date

TIMEZONE: Required.

Timezone abbreviation must be one of the timezones listed here.

This transformer should only be used for UTC dates or dates that contain the timezone in the string. By default, this will treat every date as UTC. This transformer is mostly used with our system field keys: lp_date and lp_timestamp.

# us_state and us_state_long

Transforms a matching US state string between full text or 2 letter abbreviation

Examples

Given your input is Florida, applying ||us_state will transform it to FL

Given your input is FL, applying ||us_state_long will transform it to Florida

# to_bool

Transforms 0 to 'false' and 1 to 'true'. Any other input will be ignored.

Examples

Given your input is 0, applying ||to_bool will transform it to false

Given your input is 1, applying ||to_bool will transform it to true

Given your input is test, applying ||to_bool will transform it to test

# from_bool

Transforms 'false' to 0 and 'true' to 1. Any other input will be ignored.

Examples

Given your input is false, applying ||from_bool will transform it to 0

Given your input is true, applying ||from_bool will transform it to 1

Given your input is test, applying ||from_bool will transform it to test

# if_else

Transforms values based on a configuration map and simple conditions. This is very useful on text fields that receive fixed values from suppliers, but have to be mapped to different buyer values.

The format of this transformer is: if_else:[FIND->REPLACE@@FIND->REPLACE@@fallback->REPLACE]. fallback is optional. There is no limit on how many FIND->REPLACE keys you can add See examples bellow on how to use.

Important: this transformer works on full input values, not on parts of the value. The conditions are evaluated in order. If any of them matches, the others are ignored and the input value is replaced with the value of the condition. The optional fallback condition can be added in case all if conditions are not met. If fallback and no conditions are met, the original input value will be preserved.

Examples

Let's consider we have a credit_score field that can receive the following values: 300-600, 600-700, 700-900
Your buyer needs the credit_score as: poor, fair, good
To achieve that, we have to transform the field: {{credit_score||if_else:[300-600->poor@@600-700->fair@@700-900->good]}}
If the supplier sends the value 600-700, the following will happen: we will first try to match 300-600. Because that was a no match, we continue to the next condition, which is 600-700. Because this matches, we will replace the credit_score field to fair
If you want to replace all other values with "unknown", you will need to add the fallback condition: {{credit_score||if_else:[300-600->poor@@600-700->fair@@700-900->good@@fallback->unknown]}}

# if_else_between

Transforms values based on a configuration map and a numeric value that is between a min and a max value. This is very useful on fields that receive a numeric value from suppliers, but have to be mapped to different buyer values depending on a value range.

The format of this transformer is: if_else_between:[MIN,MAX->REPLACE@@MIN,MAX->REPLACE@@fallback->REPLACE]. fallback is optional. There is no limit on how many MIN,MAX->REPLACE keys you can add. See examples bellow on how to use.

Important: ensure the value of the field is numeric. Multiple formats are accepted, like: 1234; 1,234; 1,234.56. Any other format most likely will fail. The conditions are evaluated in order. If any of them matches, the others are ignored and the input value is replaced with the value of the condition. The optional fallback condition can be added in case all if conditions are not met. If fallback and no conditions are met, the original input value will be preserved.

Examples

Let's consider we have a field that receives a number of miles a car is driven every year. Examples: 11,000, 5000
However, your buyer needs to know an approximate range, like: 1000, 5000, 10000, 15000
To achieve that, we have to transform the field: {{car_miles||if_else_between:[0,1000->1000@@1001,5000->5000@@5001,10000->10000@@10000,over->15000@@fallback->10000]}}
In this example, if the supplier passes 7000, the buyer will receive 10000. If the supplier passes 11256, the buyer will receive 15000. If supplier does not send this field, because we use fallback, buyer will receive 10000.
In the above example, we used 10000,over. The reserved key over can be used to define an unlimited max value for the range. This is the same as doing 10000,99999999999

# height

Transforms a given height (numeric value) into feet or inches.

UNIT: Required. Can be ft or in

Examples

Given your input is 67, applying ||height:ft will calculate the height in feet and return 5

Given your input is 67, applying ||height:in will extract the inches and return 7

# math_add

Transforms a field by permforming a mathematical addition. Only works if the input value is numeric. Maximum precision is 8 decimals.

NUMBER: Required. Must be numeric

Examples

Given your input is 24.78, applying ||math_add:10.015 will return 34.795

# math_sub

Transforms a field by permforming a mathematical subtraction. Only works if the input value is numeric. Maximum precision is 8 decimals.

NUMBER: Required. Must be numeric

Examples

Given your input is 24.78, applying ||math_sub:10.015 will return 14.765

# math_multiply

Transforms a field by permforming a mathematical multiplication. Only works if the input value is numeric. Maximum precision is 8 decimals.

NUMBER: Required. Must be numeric

Examples

Given your input is 24.78, applying ||math_multiply:10.015 will return 248.1717

# math_divide

Transforms a field by permforming a mathematical division. Only works if the input value is numeric. Maximum precision is 8 decimals.

NUMBER: Required. Must be numeric

Examples

Given your input is 24.78, applying ||math_divide:10.015 will return 2.47428856

# math_ceil

Transforms a value to the next highest integer value by rounding up if necessary. Only works if the input value is numeric.

Examples

Given your input is 24.78, applying ||math_ceil will return 25

# math_floor

Transforms a value to the next lowest integer value by rounding down if necessary. Only works if the input value is numeric.

Examples

Given your input is 24.78, applying ||math_floor will return 24

# math_modulo

This arithmetic operation calculates the remainder of a field value divided by the given argument. This function is very useful to convert height or months.

NUMBER: Required. Must be numeric and greater than 0

Examples

Given your input is 65, applying ||math_modulo:12 will return 5. Useful when you have the height in inches, and you need to extract the inches left after converting to ft/in.

Given your input is 26, applying ||math_modulo:12 will return 2. Useful when you have the total numbers of month left in a lease. and you need to calculate the months left without the matching years.

Important notes

some characters will have to be converted when used as parameters for the modifier. Check Appendix A
for the transformers that allow configuration, ensure that the following chars are not passed as a parameter: || and @@
transformers with configuration errors, like invalid parameters or invalid modifiers, will be ignored. please run tests after adding a transformer to ensure your campaign can still receive and deliver the lead as you want.

Appendix A - special characters

Character	Replace with
"	%22
\	%5C
&	%26

Appendix B - valid format dates

A valid format date need to contain at least the year, month and day. Some valid formats are: 2020-02-03 23:45:23, 2015-07-21, 2015/07/21, 07-11-2015, 07-11-2015 14:23:08, 2015-07-21 01:23:45 PM, first day next month, +3d

These are just a few examples, but our system can parse a wide variety of dates. Always check and test your input and output to ensure your campaigns do not stop working and transmit the data as you expect

If you are using a standard format provided by the Date & time field when configuring your campaign, you do not need to worry about anything.

Appendix C - output date formats

Format	Description	Output
d	Day of the month, 2 digits with leading zeros	01 to 31
D	A textual representation of a day, three letters	Mon through Sun
j	Day of the month without leading zeros	1 to 31
l (lowercase 'L')	A full textual representation of the day of the week	Monday through Sunday
N	ISO-8601 numeric representation of the day of the week	1 (for Monday) through 7 (for Sunday)
S	English ordinal suffix for the day of the month, 2 characters	st, nd, rd, th. Works well with j
w	Numeric representation of the day of the week	0 (for Sunday) through 6 (for Saturday)
z	The day of the year (starting from 0)	0 to 365
W	ISO-8601 week number of year, weeks starting on Monday	42 (the 42nd week in the year)
F	A full textual representation of a month, such as January or March	January through December
m	Numeric representation of a month, with leading zeros	01 to 12
M	A short textual representation of a month, three letters	Jan through Dec
n	Numeric representation of a month, without leading zeros	1 to 12
t	Number of days in the given month	28, 29, 30, 31
Y	A full numeric representation of a year, 4 digits	1999, 2003
y	A two digit representation of a year	99, 03
a	Lowercase Ante meridiem and Post meridiem	am, pm
A	Uppercase Ante meridiem and Post meridiem	AM, PM
g	12-hour format of an hour without leading zeros	1 to 12
G	24-hour format of an hour without leading zeros	0 to 23
h	12-hour format of an hour with leading zeros	01 to 12
H	24-hour format of an hour with leading zeros	00 to 23
i	Minutes with leading zeros	00 to 59
s	Seconds with leading zeros	00 to 59
c	ISO 8601 date	2004-02-12T15:19:21+00:00
r	RFC 2822 formatted date	Thu, 21 Dec 2000 16:01:07 +0200
U	Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)	1607730067

These formats can be used to create virtually any date:

Format	Output
Y-m-d H:i:s	2007-10-12 14:33:56
Y-m-d\TH:i:sP	2005-08-15T15:52:01+00:00
l, d-M-Y H:i:s T	Monday, 15-Aug-2005 15:52:01 UTC
Y-m-d\TH:i:sO	2005-08-15T15:52:01+0000
D, d M y H:i:s O	Mon, 15 Aug 05 15:52:01 +0000
\O\\n Y-m-d \a\\t h:i:s A	On 2015-12-07 at 01:30:00 PM

If you wish to use your own words (like on, at), those characters have to be escaped by the help of \. Some (\e, \f, \n, \r, \t, \v) must be double-escaped (\\e, \\f, \\n, \\r, \\t, \\v). See last example in the table above.