Lead Routing
The Lead Routing and Click Routing portions of custom endpoints will likely be where you spend the most amount of time when building out campaigns, at least from the distribution side of things.
The lead routing component of your custom endpoint is the guts of your connection between the lead data from your offer --> where the lead data is being sent, Hence the term "endpoint". This lead data is sent via API (Application Programming Interfaces)
As mentioned in earlier articles, custom endpoints can represent a few different things such as lead buyers in your campaign, CRM's, databases, and anywhere else you'd send lead data. This
A lead buyer 🤝 A custom endpoint. Virtually the same thing in many contexts.
3rd Party API Documentation
When sending lead data via API from one server to another there are few pieces of information one would need. Most of this information should be contained in some sort of document provided to you by the party of who's ingesting this incoming data. These are typically referred to as "API Specs" or "Posting Specs".
Not all API specs are made the same. Some contain all of the information you could need with detailed explanations and more and some are the closer to the bare bones minimum.
Regardless of how extensive their doc is, there should be a baseline of information provided in order to successfully integrate their endpoint.
Endpoint URL (or Posting URL)A breakdown of the parameters, values they accept and how they're structured. This is necessary for when you map the fields from Pingtree to their system.Which parameters are required and which are optionalRequest Types: The two primary methods for sending lead data would be through a GET request and a POST request.Posting Formats: In addition to a GET and POST request, there are also different posting formats used to deliver the data from one server to another. By default, Pingtree uses JSON, however you have the option to change to XML (8 or 16 bit),
x-www-form-urlencoded, and form-data. The acceptable posting format(s) should be listed in the documentation.Authorization Tokens: Some systems implement certain tokens or keys used to enhance security protocols by authenticating where the source of the data transfer is coming from. This will typically be provided as a key:value pair which you will either install in your "Set Headers" or "Static Fields" section in lead mapping.Sample API response: An example of what the 3rd party's API response looks like after an accepted request as well as a rejected request.Test token: Some systems may have the capability to use a test token which can be helpful when working on the initial endpoint configuration.
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 recipients 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 has a number of system fields that are native to your offers and the application. These fields, by default, are available in your campaigns. Please visit Pingtree System Fields for more detailed information on avaialble parameters Pingtree offers.
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 lefthand 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
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.
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"}
Integer - This data type represents a whole (non-fractional) number. ex: {"25"}
Number - A number data type includes integer values as well as fractional numbers. ex: {"25"} or {"25.353"}
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.