Utilizing The Buyer Payload Builder When Setting Up Your Buyers In Lead Prosper

The Payload Builder is the tool used to construct the API request bodies that gets sent to your buyer. Every buyer in Lead Prosper — whether it is a Direct Post buyer, a Ping Post buyer, a Google Sheets buyer, or an Email buyer — requires a payload that defines what lead data is sent and how it is formatted. For Direct Post and Ping Post buyers, the payload takes the form of an API request sent to the buyer's endpoint. For Google Sheets buyers, the payload maps your campaign field values to each header column in the sheet. For Email buyers, the payload builds the plain-text message body and maps campaign field values into the email content. Regardless of buyer type, the Payload Builder is where you configure exactly what gets sent.

Request Configuration

When configuring a Direct Post or Ping Post buyer, the Payload Builder is organized into several sections. The first is the Request section, where you configure the details of the actual API request sent to your buyer.

Request Type — Select the HTTP method for the request: GET, POST, or PUT.

Posting URL — Enter the API endpoint URL where the request will be sent. This is the buyer's URL that will receive the lead data.

Headers — Add any custom headers that the buyer requires for the request. Some buyers require authorization headers, content-type headers, or other custom headers to accept incoming requests.

Timeout — Adjust the connection timeout settings if the default is not sufficient. This controls how long Lead Prosper will wait for a response from the buyer's endpoint before timing out.

Payload Body — This is the actual payload configuration that will be sent in the API request. See the Payload Body section below for full details on building this out.

Response Configuration

The Response section is where you define how Lead Prosper should interpret the buyer's API response. This determines whether a lead is marked as Accepted, Duplicated, or Rejected based on what the buyer sends back.

Response Format — Set the format in which the buyer's API response will be returned. Options are JSON, XML, or Text.

Accepted Condition — Map what constitutes an Accepted response, meaning the lead has been sold to the buyer.

Duplicated Condition — Map what constitutes a Duplicated response, meaning the buyer has flagged the lead as a duplicate.

Condition Types

When setting up Accepted or Duplicated conditions, you have four options for how Lead Prosper evaluates the buyer's response:

key equal with — Set the exact key name and the exact value to match. The response must contain that key with that exact value for the condition to be met.

key contain — Set the key name and a value to search for. The condition is met if the specified value exists anywhere within the value of that key.

response contains — Search for a value anywhere in the full response body. This option is very relaxed. For example, if you set the value to "accepted" and the buyer's API response contains the word "unaccepted", the condition will still be met because the string "accepted" exists within "unaccepted." Keep this behavior in mind when using this condition type.

HTTP status code is — Match a specific HTTP status code returned with the API response, such as 200.

Additional Response Fields

Key — The key or field name in the response where Lead Prosper should look for the mapped value. Applies to JSON and XML response formats.

Value — The value to look for within the key specified above. Applies to JSON and XML response formats.

Real-Time Price — If your buyer returns a price in the PING or POST response, you can configure this option to dynamically set the bid or sell price based on the value the buyer returns in a specific key. This allows pricing to be determined in real time by the buyer's response rather than being set to a static value.

Response Parser Tool

The Response Parser Tool allows you to take an actual API response from your buyer and visually configure all response mappings by clicking values directly in the response. Instead of manually typing out keys and values, you click on the relevant parts of the response and assign them to the appropriate mapping (Accepted, Duplicated, Real-Time Price, etc.).

The Response Parser Tool also supports setting response variables. Response variables let you capture a value returned in the PING response and insert it into the POST body. This is useful when the buyer returns a unique identifier or token during the PING that must be included in the subsequent POST request.

Payload Body

The Payload Body is where you build the actual data structure that gets sent in the request. The payload can be configured in one of three formats: JSON, XML, or FORM. Each format has its own structure and styling requirements. The buyer's API specs will indicate which format they require, so always refer to those specs when building the payload.

If you build your entire payload in one format and need to convert it to another — for example, you built it in FORM but the buyer requires JSON — you can change the format by selecting the new format from the dropdown. The Payload Builder will automatically convert whatever you have already built into the new format.

Important Guidelines for Building Payloads

Field names must be exact. This includes spacing and capitalization. It is best to copy and paste the exact field names from the buyer's API specs to avoid typos or other errors.

Field values can be case sensitive. Follow any capitalization requirements specified in the buyer's API documentation for text values.

Formatting must match the buyer's requirements. The buyer's system will not be able to read data that does not conform to their expected format. For example, if the buyer's API specs say they collect date_of_birth in the format MM/DD/YYYY and you send YYYY-MM-DD, the request will return an error. Formats must be exact.

Allowed values must be sent exactly as specified. If the buyer provides a list of allowed values for a specific field, you must send those exact values. Sending a value not on the list will result in an error.

Your campaign field names do not need to match the buyer's field names. If the buyer expects the consumer's date of birth in a field called "dob" and your campaign collects it in the field {{date_of_birth}}   , that is fine. When the payload is sent, Lead Prosper replaces your campaign field name with the actual lead value. The buyer only sees the value, not your internal field name.

Computed Fields can transform lead data to meet buyer requirements. Computed Fields allow you to modify the data you are collecting so that it matches what the buyer expects. This can range from basic find-and-replace operations to converting a date from one format to another. You can also use Computed Fields creatively for more complex transformations. For example, if you collect values for an incident timeframe and your buyer requires an incident date, you can use Computed Fields combined with payload transformers to convert that text into a relative date, then use a date transformer to produce the exact date format and value the buyer requires.

System fields provide additional data points for every lead. System fields are values generated automatically for every lead processed in your campaign. Examples include lp_lead_id, the lead date, the current date, and the lead supplier who sent the lead. There are many system field data points available that you can include in your buyer payloads.

Testing Your Payload

Once the payload has been fully built, you can use the Test Buyer Tool to send a test and see how the buyer responds. This is useful both for confirming that the buyer can accept leads and for troubleshooting errors with data formats or values in real time.

If you run into any issues during testing, you can select the Contact Support button to generate and submit a ticket to the Lead Prosper support team. The ticket automatically includes everything related to the test — request bodies, responses, buyer URL, and more — so the support team has the full context needed to help resolve the issue quickly. This feature is highly recommended when troubleshooting buyer issues.

You can also access the Response Parser Tool directly from the Test Buyer area. When you open the Response Parser Tool from this screen, the PING and/or POST responses from your test are automatically populated in the tool. From there, you can find and click the values in the response and map them to fix any configuration issues. After making corrections and selecting Apply Configuration, you can send another test to confirm whether the issue has been resolved.

The Payload Builder is the central tool for configuring how lead data is delivered to your buyers in Lead Prosper. Whether you are building an API request for a Direct Post or Ping Post buyer, mapping campaign fields to a Google Sheet, or constructing an email body, the Payload Builder handles the formatting, field mapping, and structure of every outbound payload. Combined with the Response Parser Tool and the Test Buyer Tool, you have everything you need to build, validate, and troubleshoot your buyer integrations. If you have any questions or run into any issues while configuring your buyer payloads, reach out to the Lead Prosper support team — we are here to help.