Campaign Distribution

​

Custom Endpoints

The term “endpoint” at its highest level, is a URL generated by an external server which can be used to facilitate data transfer, updates, or execute similar actions from web browsers and other applications referred to as “clients”.

In Pingtree’s case, the “custom endpoint” casts a wide net when it comes to use-case, functionality and capabilities.

Below are a few common examples for how custom endpoints are used in Pingtree.

1. Lead Buyers: Sending lead data to buyers will generally be facilitated through a custom endpoint (Advertiser would be the alternative which would provide the buyer with their own advertiser portal)
2. CRMs: Sending lead data to your own CRM or the CRM of a third party is a common use-case.
3. Databases/Data Lakes: Another potential use-case would be any sort of data warehouse or visualization tool where lead data may be stored.
4. Dialers: Similar to CRMs, dialers can also be a common practice for Pingtree users to facilitate lead data transfers.

Custom Endpoints are at the heart of the lead distribution segment of your campaign, so needless to say it’s important.

Now that we’ve touched on common examples of how custom endpoints can be used in practice, below you find some of the different features and capabilities custom endpoints have and what will be covered in the following articles.

Lead Routing/Click Routing

• Field Mapping
• Transformer Tool
• API Request Formats & Languages
• Posting Formats
• Endpoint CAPs, Filters & Plugins
• Dynamic Response Mapping
• Testing Endpoint Feature
• Minimum Pricing

Click Listings

• Click Listing Build
• Click Listing Filters & Routing

There are a number of ways to configure an endpoint properly. Depending on your campaign framework, your buyers, the type of traffic you’re running can all play roles in determining the actual set up.

This article will detail the steps for setting up an endpoint successfully. Some of these steps may or may not be required and some steps may require additional set up for full accuracy.

Some of the factors to consider prior to making your endpoint include:

1. What function do these endpoints serve? Are they direct buyers, your CRM, a dialing system, a database etc..
2. Which routing methodology will this campaign be based on? Form or Click Routing, Ping+Post Routing, Pingtree Routing.
3. Which filters and rules are you going to want to assign for your endpoint?
4. Have you received the API specs for the server in which you will be sending the data to?

Endpoint Configuration and Distribution Setup

Step 1
Endpoint Creation: Create the endpoint by selecting “Add Custom Endpoint” in your Distribution —> Custom Endpoint view. Apply a name and a parent endpoint which can be one in the same.

Step 2
Lead Routing: Inside of your lead routing section is where you will manage the bulk of your build. Add your endpoint URL, a backup URL(if applicable), **minimum price(if applicable) and map your parameters.

This includes headers and/or static fields.

**Minimum Price feature applies if the endpoint’s server is including a price value in their API response AND you want to only sell the lead to the endpoint if that price that’s returned is greater than or equal to the value you set.

Step 3
Determine your HTTP method (Pingtree supports both GET and POST). This should be in the API specs for the server you’re sending this data to.

Step 4
Determine your POST format. If sending your data via a POST method, you will need to confirm the format. By default, Pingtree is formatted to send POST as JSON. (Pingtree also supports sending POST requests as x-www-form-urlencoded, form-data, XML-16 and XML-8). This information should be in the API specs for the server you’re sending this data to.

Step 5
Add Response Mapping: When you send a lead to an endpoint in this way, you are calling an API. This API transmits your data from Pingtree’s server to the endpoint’s server. That initial delivery of data is called the API request. As a result the server that’s ingesting this data will send back an API response. Response Mapping allows you to create logic surrounding this API response and the data the endpoint’s server just received. With this API response, you can configure rules or dynamically capture data for reporting purposes as well as other features.

Each of these response mapping fields allow you to capture this data in either JSON or XML which is determined by the endpoint’s server and how they send their responses.

API Response Mapping: In this field, you will be mapping the endpoints response so that you can determine if a lead was actually accepted by the endpoint’s server. You are mapping this from their API response so this would typically be included in their API specs.

*Below is a common mapping you may see.

Amount Mapping: In this field, you will be mapping the price that the lead was purchased for. This would be indicated in the endpoint’s API response. Once mapped properly, it will attribute the value as revenue for that lead assuming the lead was successfully sold. *Not all endpoint setups will need this function

URL Mapping: In some situations, the API response from a server may include a URL that is expected to have the lead redirected to. In order to capture that URL value, you will need to map the field to the value stored in the API response. There are other steps involved in fully completing this redirect action, as this is simply mapping the value and storing it.

Reject Reason Mapping: In this field, you will be mapping the reasoning (if available) for a lead being rejected. By default, if a lead was attempted to sell to and endpoint, meaning it validated through all CAP, time, and state filters, as well as custom routing rules, and still did not sell to a buyer, Pingtree will store this reject reason as “Lead Rejected due to response mapping”. IF you map this portion of the endpoint’s server response, you may be able to capture a higher level of data as to why the lead was rejected i.e. duplicate, api error, invalid data etc…

Now that the reject reason is mapped and stored, you’ll be able to see this in your logs under “Reject Logs”. This added feature allows you to monitor these reject reasons and have more insight into your lead performance.

Assigning a Waiting Time: The Waiting Time field indicates how long Pingtree’s system will wait for the endpoint’s server to respond before timing them out. Typically API calls between servers are relatively instantaneous however there are, in some cases, reasons why the API call may take longer.
Sample Response Feature: Pingtree gives you the ability to preview the API response of an endpoint’s server without needing to look at their docs. Simply add an existing Pingtree transaction_id into this field, and click “Get Sample Response” to call their API and generate a response. Depending on their server or API setup, they may not provide all or any data in the response but utilizing this feature can be helpful.

Step 6
The third tab inside your Lead Setup and Routing section is “Filters”. In this section, you will determine the GENERAL rule logic for this endpoint.

Black List Alliance: You can enable this feature by toggling it on, and it will prevent any leads that were either rejected or unprocessed by Black List Alliance from being delivered to this endpoint. **In order to successfully use this feature, you will need to add in your Black List Alliance account code and token in your campaign settings
Geolocation Filters: Determine which states or zip codes should be excluded from being sent to this endpoint.
CAP: You may set CAP limits for this endpoint. Choose to set your CAP method as a global CAP, monthly CAP, weekly CAP or daily CAP. Additionally for daily CAPs you may also assign a daily payout CAP.
Time Filters: Also called day-parting, this filter will allow you to enter the days of the week as well as the time periods where you can attempt to sell leads to an endpoint. Simply add the start and end times in the appropriate days and activate the “Enable Time Settings” toggle.

Step 7
Price Settings: You can assign a fixed price which will be attributed to an endpoint anytime a lead is sold to them. You can bifurcate this by source type: (Media Channel, Marketing Partner or Custom Source).
If you choose to configure with this option, be sure to enable the “Override Campaign Settings” toggle

Step 8
Testing: Once these steps have been completed, you have the option to test the server to server connection and ensure your field parameters are mapped to the endpoint’s parameters correctly. Select the “Test Endpoint” button which will prompt a dialog box which includes any fields you have mapped and static fields added.

Begin adding the actual values these fields would contain (Not the fields themselves) as you are simulating an actual lead posting to this endpoint. Once finished, click “Submit” and this should generate an API response from the endpoint’s server. This is a great tool in ensuring your server to server connection is functioning as expected.

Step 9
Enable and activate your endpoint. Do this by toggling on the “Enable Endpoint” toggle and in the upper lefthand corner of your lead mapping view, select the drop down to “activate” if it’s not selected already.

Step 10
Routing Rules: Pingtree gives you the ability to create custom routing rules for your endpoints in order to bifurcate the lead data and distribute them to different places. Each rule is based on rule conditions structured as IF/THEN statements. They use lead and attribution data captured in the lead’s payload.

If any rules are applied, you will create them here, and in the “Action” field, you will select the endpoint that you wish to attribute this rule to. Only endpoints that are enabled and do not have a separate rule attributed to it will be available from the picklist. You can apply more than one routing rule condition per endpoint but only one rule can be attached to an endpoint at a given time.

Step 11
Routing Logic: Applying the routing logic puts your lead distribution into motion. Without adding your endpoint into the lead distribution section, you will not be able to get any data from your source, whether that be a Pingtree Offer or somewhere else, to your endpoint.
In form routing there are 3 basic models:

Base Routing: An endpoint can be added to this routing model if there IS NO custom routing rule logic applied. (This excludes general rule logic such as filters, CAP, response mapping etc..)
Conditional Routing: An endpoint can be added to this routing model if there IS any custom routing rule logic applied which was described in Step 10.
Failover Routing: And endpoint can be added to this routing model if there is NO custom routing rule logic applied, AND you want attempt to deliver leads to this endpoint only in the event in which it was unable to be sold to another endpoint in either Base Routing or Conditional Routing.

Step 12
Applying Routing Thresholds: Routing Thresholds give users the ability to apply weights and threshold parameters with the primary goal of evenly distributing leads to different endpoints who may have different CAP limits throughout the day.
———————————————————

​

​

​

Field Mapping

Fields, also commonly referred to as “parameters” or “keys”, are what’s used to define the structure in which certain values are ingested into a system/application. These fields represent an overlying data attribute such as First Name, Last Name, Email Address and Phone Number. Each of these attributes would contain a corresponding value.

Field mapping in this context of sending lead data via API involves the process of mapping data fields from the Pingtree system to another to ensure that the information is properly understood and processed by the receiving system.

Once the fields are identified, you will define a mapping between the fields in your lead routing section and the corresponding fields in the target system. This mapping specifies which data from the source system (Pingtree) should be sent to which fields in the target system (Custom Endpoint) and in what structure.

Example:
You are ingesting the following sets of data in your campaign offer that you wish to send to a buyer (i.e. custom endpoint). First Name, Last Name, Email Address, Phone Number, IP Address, Utm Source
You know that your field attributes for these pieces of data are structured as so:

first_name=Michael
last_name=Jordan
email=michaeljordan23@gmail.com
mobile=800-855-8555
utm_source=tiktok
You have received the API specs from your buyer which included their own field structure for each of these data points. They are as follows:
firstName={{Value}} lastName={{Value}} emailAddress={{Value}} phone={{Value}} sub\_1={{Value}}

If you take “Michael” which is clearly the first name value in this set of lead data. You will need to transfer that same value, into the recipient’s first name. While you aren’t touching the value itself in this example, you will provide the rules on how and where to deliver that value by mapping “first_name” with “firstName”.

With this information, you now know how you will map these fields from Pingtree’s system to your buyer’s system.

System Fields vs Custom Fields

Pingtree System Fields
Pingtree has two types of parameters that can be used. System Fields and Custom Fields. System fields are those that are innate to the Pingtree platform.

Some of these system fields are general and some are vertical specific. While it’s not required that some of these system fields be used for your offers, it’s highly recommended as there are a number of these fields which are molded to fit other certain components of the platform.

Pingtree’s General System Field Parameters

Pingtree has a number of system fields that are native to your offers and the application. These fields, by default, are available in your campaigns

Field Label	Pingtree Parameter
Pingtree Unique Lead ID Parameters
Transaction ID	transaction_id
Lead Data Parameters
First Name	first_name
Last Name	last_name
Email	email
Phone	mobile
State	state
Zip Code	zip_code
Country	country
Address	address
Date of Birth*	date_of_birth
SSN	ssn
3rd Party API Parameters
Debt Amount	debt_amount
Trusted Form Ping URL	trustedFormPingURL
Trusted Form Cert URL	trustedFormCertURL
Trusted Form Token	trustedFormToken
Jornaya	jornaya
Attribution Tracking Parameters
External Click ID	external_clickid
Sub 1	sub1
Sub 2	sub2
Sub 3	sub3
Sub 4	sub4
Sub 5	sub5
ADV 1	adv1
ADV 2	adv2
ADV 3	adv3
ADV 4	adv4
ADV 5	adv5
Campaign ID	campaign_id
Source ID	source_id
UTM Campaign	utm_campaign
UTM Source	utm_source
UTM Creative	utm_creative
UTM Medium	utm_medium
UTM Term	utm_term
UTM Content	utm_content
UTM Placement	utm_placement
Google Click ID	gclid
TikTok Click ID	ttclid
Facebook Click ID	fbclid
Financials & Performance Metric Parameters
Revenue	amount
Payout	payout
Cost	cost
Ad Spend	adSpend
Event Parameters
Event ID	event_id
Creative Library Parameters
Marketing Ad ID*	maid
Marketing Campaign ID	mcid
Ad Manager ID	amid
Marketing Ad Group ID	mgid
Marketing Channel ID	mid
Creative Ad ID	crid
Additional Common Parameters
Product	product
Product Type	product_type
Referral Code	referral_code
Gender	gender
Age	age
User Selected Debt	debt_selected

*date_of_birth parameter used for Credit API call.

There may be a parameter which you need to store and/or pass that isn’t already in Pingtree’s database of system fields. In this instance you would need to create a custom field.

This is done by going into your Org Level “Database Source” selection on the left hand menu. Once in this view, navigate to the “Custom Field” header.

Select the following button to open up the Custom Field modal:

Once in here you will need to assign certain attributes to the custom field:

Field Name: This is the actual format of the parameter for when it’s mapped in the backend systems. It’s important to structure this correctly (SYNTAX MATTERS)

Pingtree uses all lower case characters and underscores ”_” as the standard format for system fields as this is the only special character permitted. While following this structure is not required, it is highly recommended to maintain a standardized format and field naming convention.

Field Label: Your field label is how you will see the field on the frontend in your data tables and reporting. While there’s no backend logic dependent on the Field Label, it’s recommended to use a naming convention that is clear and conspicuous.

Data Type: There are 5 primary data types Pingtree allows

1. String - This is the most versatile data type and is a sequence of characters used to represent text. Strings can include letters, numbers, symbols, and spaces.
2. Boolean - This data type is binary meaning there can only be 2 potential values. This could be represented as {"True" "False"}, {"1" "2"}, {"yes" "no"}
3. Integer - This data type represents a whole (non-fractional) number. ex: {"25"}
4. Number - A number data type includes integer values as well as fractional numbers. ex: {"25"} or {"25.353"}
5. Date - This data types refers to any specific date formatted values. **It is also acceptable to use a string data type if you are collecting a value that’s also formatted as a date.

Required: Choosing to enable this toggle will require this field and value in this field to be passed in your source API.

Campaign Selection: Lastly you will choose which campaign(s) you want to attribute your custom field to. In some cases, the custom field may be vertical or hyper specific in which case there may be some active campaigns which would never utilize this field. In this instance, it’s best to leave it unassigned to that particular campaign.

Data Transformer

Data Transformer Overview

ingtree’s data transformer refers to a mechanism or process used to manipulate or transform data between different formats, structures, or systems.

Specifically, in field mapping for lead generation, a data transformer may be employed to ensure that data collected from lead forms or other sources is transformed and mapped accurately to the desired fields in a database, CRM system, or other destination.

Ex: In certain verticals, buyers may only accept values that are formatted in a particular way, and are generally case-sensitive. For example, if you’re running a home services campaign, and one of your form questions is “Do you own the home” and the two values being passed on the backend are “yes” and “no”, by default, when you configure your lead mapping for that buyer in distribution, one of those two values
are going to be what is passed in the field you’ve mapped from Pingtree to the buyer’s system.

If this buyer ONLY allows ingestion of the values “Own” or “Rent” for this particular field, and you have sent that buyer “yes” or “no”, it will result in their API not properly collecting these values which can ultimately lead to the rejection of the lead, if the buyer requires this field.

If you only had a single buyer, you could simply modify the value from your form itself. If you have multiple buyers, all of whom require values in a different format, here would only be the issue. This is where Pingtree’s data transformer comes into play.

Applying the Data Transformer

The data transformer tool will be applied within a given endpoint, in the lead routing section.

When mapping fields you will see a + icon next to the field you’re mapping. Selecting this icon will open up the transformer tool underneath the field.

After determining the data type you intend to use in the transformer for this field, you will need to map each value.

In the left column you will input the value in the exact same structure as how your offer passes it (If using Webflow 2.0 form builder, this is configured in the element). In the right column, you will place the buyer’s corresponding value in the exact same structure as how they ingest it.

In the image below, the Pingtree user is passing the values in the field home_type in the following formats: single_family, duplex, townhome, modular, mobile_home. These values are then transformed into each corresponding value in the right side of the column.

As a result, when the buyer’s system receives these data values, they will only capture the values as they are structured in that right hand column, allowing their API to successfully visualize the data.

Once you have finished converting each of the values, you can click “Submit” at the bottom of your lead routing view, the transformed values will tuck back into the field and there is nothing more you need to do.
If you ever need to change these values, simply click on the + icon, and all of the values you’ve transformed for this field will collapse like in the image above.

Data Transformer > Date Formatting

While the overall concept is the same, in that some buyers may require their date-related values ingested in a specific format, there are some unique components to modifying a date field with the transformer tool in Pingtree.

There are a few things to note first about the initial format of any date-related field. Inside of the form builder in any field you’re collecting a date, you will need to apply one of Pingtree’s pre-set date masking formats.

If this masking is not applied, it can impact the functionality of the transformer tool. As you’ll see in the image below, there are 3 different formats you’re able to apply to your date field.

DD-MM-YYYY
MM/DD/YYYY
YYYY-MM-DD

Back inside of the lead routing you will navigate to the field where you are capturing this date value. In this example, we are using “date_of_birth” however this same logic can be applied with any relevant date field.
Once you have mapped the Pingtree field to the buyer’s field (“date_of_birth” mapped to “DOB”) you will need to select the + icon which will open up the transformer tool.

In the dropdown menu, instead of selecting String or Number as the option, you will need to select Date. Once selected, it will populate an additional dropdown menu directly underneath.

As seen in the image below, these are the various transformer formats you’re able to manipulate the values into. For the following formats:

• ISO 8601
• Short Date
• Unix Timestamp
• Custom Format

Once selected, the only thing left for you to do is to save your changes by clicking “Submit” in the bottom of your Lead Routing

IF you need to transform the date value into a different format such as YY/MM/DD or MM-DD-YY, you will need to select Custom Format. Doing this will populate an input box where you will add in the format you wish to transform the date value into.

IMPORTANT The table below references the Format (What needs to be input into the “Enter Custom Value” box and the Value Result which shows the corresponding formats for what the third party’s system will receive.

Transformed Value Result	Date Format in Enter Custom Value
2021	YYYY
202108	YYYYMM
2021-08	YYYY-MM
8/5	M/D
08/05	MM/DD
20210805	YYYYMMDD
2021-08-05	YYYY-MM-DD
2021_08_05	YYYY_MM_DD
2021.08.05	YYYY.MM.DD
8/5/21	M/D/YY
08/05/21	MM/DD/YY
08/05/2021	MM/DD/YYYY
05 Aug 21	DD MMM YY
05 Aug 2021	DD MMM YYYY
2021	YYYY
202108	YYYYMM
2021-08	YYYY-MM
8/5	M/D
08/05	MM/DD
05 August 2021	DD MMMM YYYY
Aug 5, 21	MMM D, YY
Aug 5, 2021	MMM D, YYYY
Aug 05, 2021	MMM DD, YYYY
August 5, 2021	MMMM D, YYYY
August 05, 2021	MMMM DD, YYYY
202108051315	YYYYMMDDHHmm
20210805_1315	YYYYMMDD_HHmm
2021.08.05.1315	YYYY.MM.DD.HHmm
2021-08-05-1315	YYYY-MM-DD-HHmm
2021-08-05_1315	YYYY-MM-DD_HHmm
2021.08.05.13.15	YYYY.MM.DD.HH.mm
2021-08-05-13-15	YYYY-MM-DD-HH-mm
2021-08-05 13:15	YYYY-MM-DD HH:mm
2021-08-05 1:15 PM	YYYY-MM-DD h:mm A
2021-08-05 01:15 PM	YYYY-MM-DD hh:mm A
2021-08-05 @ 1:15 PM	YYYY-MM-DD @ h:mm A
20210805131504	YYYYMMDDHHmmss
2021.08.05.131504	YYYY.MM.DD.HHmmss
2021-08-05-131504	YYYY-MM-DD-HHmmss
2021-08-05_131504	YYYY-MM-DD_HHmmss
2021-08-05_1315.04	YYYY-MM-DD_HHmm.ss
2021.08.05.13.15.04	YYYY.MM.DD.HH.mm.ss
2021-08-05-13-15-04	YYYY-MM-DD-HH-mm-ss
2021-08-05 13:15:04	YYYY-MM-DD HH:mm:ss
2021-08-05 13:15.04	YYYY-MM-DD HH:mm.ss
2021-08-05 1:15:04 PM	YYYY-MM-DD h:mm:ss A
2021-08-05 01:15:04 PM	YYYY-MM-DD hh:mm:ss A
2021-08-05 @ 1:15:04 PM	YYYY-MM-DD @ h:mm:ss A
We Aug 5 21	dd MMM D YY
Wed Aug 5 21	ddd MMM D YY
Wed Aug 5 2021	ddd MMM D YYYY
Wed Aug 05 2021	ddd MMM DD YYYY
Wednesday, Aug 5 2021	dddd, MMM D YYYY
Wednesday, August 5, 2021	dddd, MMMM D, YYYY
Wednesday, August 05, 2021	dddd, MMMM DD, YYYY
1:15 PM	h:mm A
01:15 PM	hh:mm A
@ 1:15 PM	@ h:mm A
Wed Aug 5 21 1:15 PM	ddd MMM D YY h:mm A
Wed Aug 5 2021 1:15 PM	ddd MMM D YYYY h:mm A
Wed Aug 05 2021 1:15 PM	ddd MMM DD YYYY h:mm A
Wednesday, Aug 5 2021 1:15 PM	dddd, MMM D YYYY h:mm A
Wednesday, August 5, 2021 1:15 PM	dddd, MMMM D, YYYY h:mm A
Wednesday, August 05, 2021 1:15 PM	dddd, MMMM DD, YYYY h:mm A
Wed Aug 5 21 01:15 PM	ddd MMM D YY hh:mm A
Wed Aug 5 2021 01:15 PM	ddd MMM D YYYY hh:mm A
Wed Aug 05 2021 01:15 PM	ddd MMM DD YYYY hh:mm A
Wednesday, Aug 5 2021 01:15 PM	dddd, MMM D YYYY hh:mm A
Wednesday, August 5, 2021 01:15 PM	dddd, MMMM D, YYYY hh:mm A
Wednesday, August 05, 2021 01:15 PM	dddd, MMMM DD, YYYY hh:mm A
Wed Aug 5 21 @ 1:15 PM	ddd MMM D YY @ h:mm A
Wed Aug 5 2021 @ 1:15 PM	ddd MMM D YYYY @ h:mm A
Wed Aug 05 2021 @ 1:15 PM	ddd MMM DD YYYY @ h:mm A
Wednesday, Aug 5 2021 @ 1:15 PM	dddd, MMM D YYYY @ h:mm A

String Sanitizer

The String Sanitizer transformer tool allows users to modify the value which may contain certain characters on the initial ingestion of data.

Objects & Arrays

Single Object

This is the most common format of data ingestion you will find. This is a collection of key value pairs where the key is a unique string and has a single layer of depth and flat structure. This is mapped normally - parameter to parameter

In the following example, you would map Pingtree’s field to the field below like:

Nested Object

While a Single Object only contains one object, a Nested Object is one that contains another object as one of its properties - in a hierarchy structure this is mapped with the “parent object” which would be “address” and “contactInfo” in the example below separated by a period and then the child object(s) “street”, “city”, “state”, and “zipCode”. In this case there is only one additional layer of child objects however it is very possible that there’s additional layers of child objects.

“userId” and “name” are both structured as their own objects so those parameters would be structured as you would with a single entity object. Notice the placement of the opening and curly brackets as well as indents to determine which properties are contained within the different objects.

In Pingtree you would structure a nested object by separating it with a period like:

Array

You may also encounter an array. Arrays are a collection of elements ordered that can be accessed by the index - These can also be nested as well. The Index in the example below would be “vehicle”
Pingtree has a standard mapping structure for data that needs to be posted into an array.

The index is first, followed by a period, followed by the sequence of the object (0,1,2,3…), followed by a period and finally the parameter.

In the following example, you would need to add the period in between the primary object and the nested objects, but since this is an array, you will also need to include a “0”. It would look like the following.

If there were another object separated by the curly brackets, but within the same flat bracket, you would map the integer as a 1. The integer values you insert would continue to increase by 1 for as many objects that you are trying to map.