How To Best Use The Test Buyer Tool When Setting Up New Buyers

Building out the buyer payload and configuration may seem like the most important part of buyer setup, but the step that often gets overlooked — and is just as critical — is testing the buyer before going live. The Test Buyer Tool lets you catch common mistakes and configuration issues before they become real problems, including:

Buyer payload errors
Incorrect response mapping
Real-time price settings
Other buyer response information

We highly recommend running a handful of tests, downloading the results, and forwarding them to your buyer before going live. This ensures there are no issues when you eventually set the buyer live.

Check for Test Parameters First

The first thing you should do after building your buyer — and before running a test — is review your API specs and any messages from the buyer for test parameters. These could include:

Test or staging URLs
Staging API keys or tokens
Specific zip code values to signify a successful test

Always make sure that if the buyer has a way to test, you configure your buyer to use those test attributes. The last thing you want is to miss the test parameters, spend time debugging why you can't get a successful test, and then discover you weren't sending "tests" — you were sending real leads, and that's why they were all rejected.

Understanding the Payload Area

When you open the Test Buyer Tool, the first thing you see is the Payload area. This area contains each and every campaign field that exists in your campaign. The tool checks the type, format, and allowed values of each field and automatically generates dummy data to match your campaign field settings. The goal is to emulate — as closely as possible — the data a real live lead would include.

This means:

First name and last name fields are populated with real names
Email address and phone number are properly formatted based on campaign settings
Date fields are properly formatted
Dummy addresses (address, city, state, zip) are generated
Legitimate formatted dummy values are generated for ip_address, user_agent, landing_page_url, jornaya_leadid, and trustedform_cert_url
Campaign fields set to Allowed Values are always populated with values from your list of allowed values

Every one of these fields is editable before you run the test. This allows you to review the generated dummy data and tweak values to increase the likelihood of the buyer accepting the test.

Keep in mind that every buyer's system can behave differently. Some buyers see a test parameter and accept those every time. Others have systems that evaluate tests as if they were live leads, checking that the data matches all criteria for filtering and what they consider a lead worth purchasing.

Example: Home Services — home_owner

If you have any campaigns set up for Home Services — whether Roofing, Windows, Gutters, Bathroom Remodels, or anything else — nearly every campaign will collect a field for home_owner, which asks "Are you the home owner?" and if not, "Are you authorized to make changes?" Contractors don't want to purchase leads where the consumer is not the homeowner, since that person may never be able to approve any quoted work.

In your campaign field settings, you likely have home_owner set up as a List of Allowed Values with the options Yes and No, and you should be filtering to block leads where the answer is No — because the likelihood of selling those leads to buyers is highly unlikely.

The reason this matters for testing: if you generate dummy data and see a field with a value that would cause the lead to be disqualified or not purchased — such as home_owner = No — edit the value before running the test. When testing home services leads, always make sure the home_owner field is set to Yes.

Example: Legal Leads — have_attorney and incident_date

Similar to Home Services, there are common universal requirements for legal leads. The most common is the question "Do you have an attorney?" Buyers don't want leads where the person is already working with an attorney, so you will almost always get a rejection when have_attorney = Yes.

If you are running a test on any type of legal lead buyer — whether MVA, Personal Injury, or any other legal vertical — check the have_attorney field before running the test. If the dummy data populated Yes, replace it with No.

The same logic applies to date fields. In MVA law, the statute of limitations for a motor vehicle accident is 2 years from the time of the incident. Buyers want to be sure the leads they purchase have an incident date less than 2 years old — the newer, the better. The Test Buyer Tool generates dummy dates but does not have rules for time frames. Check the incident_date and make sure whatever date was generated is adjusted so the age is less than 2 years old.

TrustedForm and Jornaya Validation

The dummy data generated for TrustedForm Cert URL and Jornaya LeadiD follows the format of a legitimate cert URL and LeadiD, but they are not real. Your buyer may check the validity of those values, even when you are sending tests. This will likely return some sort of error related to TCPA failed validation, invalid TrustedForm Cert URL, or similar. This is expected.

Using Search & Fill

When you encounter validation issues with TrustedForm or Jornaya — and you have existing live leads that have already been ingested — you can use the Search & Fill option. Enter the lp_lead_id value to populate the Test Buyer Tool fields with real data from that lead, including the real TrustedForm and Jornaya values. When you hit test, it will let you test with a real lead to avoid hiccups with validations. If you're concerned about privacy, you can obfuscate the PII by manually changing the phone number, email, and names.

Search & Fill is also valuable when testing buyers in campaigns with a large number of campaign fields, most of which are required by the buyer. Auto Insurance, for example, can have buyer setups that require data from 50+ campaign fields. Going through all of the dummy data in those cases to make sure everything matches can be daunting. The easier approach — if you have leads available — is to grab a real lead and use Search & Fill to populate and test with that data. It saves a tremendous headache of having to review every batch of dummy data to ensure everything checks out and matches what a real lead would look like.

Running the Test

Once your test payload fields are populated and ready, hit RUN TEST.

If everything goes right, you'll see a green ACCEPTED response. This means the request was processed and the ACCEPTED response mapping was successful.

Even with a successful response, you may still see an alert for test parameters. This means the word "test" was found somewhere in the request body, URL, or headers. The alert highlights these instances so you can review them. You may also see campaign field shortcodes highlighted in the payload(s), which indicates a field shortcode in your payload that either doesn't exist, has a typo, or has another error.

Errors and Warnings

Here is a list of potential errors and warnings that may appear, along with what they mean and how to address them.

"Potential test parameters were found in request payload body, URL or headers"

This means the string "test" was found in the request body, URL, or headers. The alert exists to warn you that test parameters may still be present in your buyer setup. Remove them before attempting to go live.

"The buyer server response doesn't match the configured response mapping"

This is a general error indicating that the response the buyer returned during the test does not match the Accepted response mapping for the buyer. It could be caused by a number of things, but the only thing it truly indicates is that something about the response does not match the buyer's accepted response mapping. Here are some scenarios to look for:

1. Buyer response shows a successful or accepted message, but the test shows as failed. 99.9% of the time, this indicates a response mapping error in the buyer setup, which is straightforward to fix. From the Test Buyer Tool, click Response Parser Tool — it will automatically insert the buyer responses from the test. From there, you can make a few clicks to update the response mapping to the proper configuration.

2. Failed or rejected test. If the buyer test fails for whatever reason, the buyer will return that it failed in the response, and this will trigger the above note. Review the buyer response for any key details that may help determine the issue. Keep in mind that Lead Prosper can only show you what the buyer chooses to return in their API response. If they return something like "Unmatched" or "Lead Rejected" with no explanation, there is nothing more that can be done on the platform side.

If the buyer does return a reason for the rejection, look at the error and work to troubleshoot the problem. Common causes of configuration errors that could cause a rejection include:

Incorrect values being sent for specific fields
Improperly formatted values for date fields or phone numbers
Missing required fields or data

Sometimes the error message gives enough detail to fix the issue right away. Other times, the response provides little to no useful information and you may need to dig and test further.

When the buyer returns a specific error message — such as an incorrect value or missing required field — you can edit the PING or POST configuration directly by selecting the Edit PING Configuration or Edit POST Configuration buttons. You'll be brought back to that section where you can review and fix whatever issues are needed. Once ready, hit SAVE and test again.

3. Unmatched errors. These come back when the buyer is signifying that the lead was not able to be purchased by any buyers on their end. In these cases, try a few different approaches:

Review the dummy values you used and tweak them
Try a different city, state, and zip_code combination
Try different lead details that may seem more attractive to a potential lead buyer
If the buyer requires credit_score values, change your test to include Good or Excellent credit score

Think creatively about what values would cause the buyer to accept the lead.

4. "No response received from buyer's server." This means the buyer's server took longer than the configured timeout for the request. The default timeout setting is 30 seconds. Look for the line above the request that starts with "Sent PING" or "Sent POST" — there will be a value at the end of the line after "request took" that shows how long the request took to either return a response or time out.

"We were unable to extract the price from the response based on your real time price key configuration: XXX"

This error indicates that real-time price rules are in place for the buyer, but the system was unable to extract the bid price. The reason is usually one of three things:

The buyer returned an error or rejection, and that response contained no price. Fix the errors if needed and run more tests until you get a success. See if the price is returned once accepted.
The buyer accepted the test and returned a price in the response. This would indicate an issue with the real-time price mapping. The Response Parser Tool can help troubleshoot and resolve this.
The buyer accepted the test but no price was returned in the API response. Some buyers require you to include a parameter in the payload to signify that you want the price returned in the API response. Double check your API specs to see if that is the case. If so, add that parameter to the setup and run another test. If the buyer should be returning a price by default and is not, reach out to them to see if they need to enable anything on their end or if something needs to be fixed.

"Invalid shortcodes were detected in the request payload body, headers or URL. Only fields defined in your campaign can be used as shortcodes"

This appears when there is an incorrect or missing shortcode in the payload body. Typical reasons include:

The shortcode field name has a typo
Incorrect number of curly brackets — proper shortcodes in Lead Prosper use 2 curly brackets per side: {{ }}
The shortcode field name doesn't exist as a campaign field — this is normally indicated in the payload builder by highlighting improper shortcodes in red, but the Test Buyer Tool will also flag it

If you have a Ping Post buyer and see this error on the POST related to the {{lp_ping_response:KEY}} shortcode, that means the KEY mapping in that shortcode is incorrect. Use the Response Parser Tool and Response Variables to troubleshoot and fix this issue.

Keep Running Tests

The Test Buyer Tool can be used over and over again to re-run tests, so run as many as you need to fix any issues. The goal is to run through all tests possible to prove the buyer is ready to go live.

Misconfiguration? Fix it and test again.
Invalid value sent? Fix it and test again.
Field name typo? Fix it and test again.

Test over and over until you get only accepted responses. Then test one more time for good measure.

Testing as much as possible is the most effective way to ensure your buyer setups are good to go before going live. If you go live with a buyer that is incorrectly set up, you can run into any number of issues:

Incorrect response mappings could cause a lead that sold to be erroneously flagged as unsold or rejected, allowing that lead to be sold to another buyer — accidentally selling the lead twice.
Misconfigurations or bad data being sent to a buyer could sour a working relationship. Every lead you send to their server costs them time, money, and resources.
Incorrectly mapped price rules could have a buyer incorrectly skipped over for leads due to a $0 bid price, putting them dead last in a highest bidder sort order.

All of these issues can be prevented through proper testing.

Final Steps Before Going Live

When you are satisfied with your testing, take the last successful test and hit the Download as File button on the Test Buyer Tool. This generates and downloads a text file containing the PING and/or POST body and headers for both the Request and the Response. Forward this file to your buyer for final approval. Ask them to review the test, make sure everything looks good on their end, and have them confirm.

Once confirmed, you are ready to go live:

Go back to your buyer configuration.
Find any and all test or staging parameters and values. Remove what needs to be removed and update staging parameters and values to the proper live/production values.
Double check the buyer filter, cap, and pricing settings.
If everything looks good, hit the Resume button and set that buyer live.