DataWidget® Integration Guide

A complete reference for developers integrating the DataWidget® into a web-to-print application. Embed snippet, widget lifecycle, conclusion webhook, server-side fulfillment, list download, skinning, multi-tenant pricing, and the test environment. Read this once, then keep it open while you build.

1. What you need to get started

This guide is for a developer comfortable with JavaScript, HTML, and a server-side runtime (Node, Java EE, .NET, Ruby, Python — anything that can make HTTPS requests and parse XML). Before you start integrating, we'll provision the following for you:

• affiliatecode — the unique code that identifies your company or client
• username — specific to the affiliate code; used for server-side fulfillment
• password — specific to the affiliate code; used for server-side fulfillment

You'll also need a Host Server — your application's backend. The Host Server is responsible for:

• Receiving the Widget Conclusion notification (HTTP POST from us when a customer hits "Buy List")
• Sending List Fulfillment requests to the Widget Server (the LP backend)
• Downloading the resulting CSV file from the Widget Server

No need to pre-register the Host Server with us — your conclusionurl is set per request at widget initialisation, and outbound fulfillment calls auth via your username + password.

Glossary

Widget	The DataWidget® JavaScript loaded into your host page from the Widget Server.
Widget Server	The LeadsPlease® server hosting the widget JS, the count engine, and the list-fulfillment databases.
Host Server	Your application's backend. Listens for Conclusion POSTs and drives Fulfillment.
Host Webpage	The page in your application that embeds the widget.

2. Widget lifecycle

2.1 Initialisation

Drop two script tags into your audience-selection page and a target <div> for the widget to render into:

<script src="https://widget.datawidget.com/lp_widget_1.5.js"></script>
<script>
  var w = new LeadsPlease.Widget({
    widgetid:      'wid',
    affiliatecode: 'YOUR_CODE',
    conclusionurl: 'https://yourapp.com/api/dw-conclusion',
    sessionid:     'host-session-12345'
  });
</script>

<div id="wid"></div>
<a href="http://www.leadsplease.com" target="_new">Mailing Lists by LeadsPlease</a>

The trailing link to www.leadsplease.com must appear OUTSIDE the widget container, with the exact text "Mailing Lists by LeadsPlease". The widget styles it discreetly to blend in.

2.2 Constructor parameters

Parameter	Description	Required	Example
widgetid	HTML DOM element ID where the widget mounts.	Yes	'wid'
affiliatecode	Unique code identifying your company or client. Determines pricing, branding, security.	Yes	'banner'
conclusionurl	URL on your Host Server that we POST list criteria to when the customer hits "Buy List".	Yes	'https://app/api/dw'
sessionid	Your Host Server session ID. Echoed back at conclusion so you know which user just bought.	Yes	'sess-xyz-789'
callback	JS function called in the host page at "Buy List" time, with the same payload as the conclusion POST.	No	function(d){...}
onload	JS function called once the widget has finished loading.	No	function(){...}
skin	JS object with skinning properties (see 2.4).	No	{ buylistbtn: 'Add to Cart' }
datasetkey	Pricing/demographics config selector (see 2.5).	No	'customer-456'

2.3 Widget size & appearance

The widget renders as a rectangle approximately 900 × 570 pixels by default. The new three-panel widget (used on this microsite) is responsive and will adapt up to your container width — see the Try It tab for the live look.

2.4 Skinning

Pass a skin object to tune the widget per page (per-affiliate XML controls global branding; skin is for per-page overrides):

Property	Description	Example
buylistbtn	Custom text on the "Buy List" button.	buylistbtn: 'Add to Cart'
hideprices	Suppress all price display on the widget (useful when you mark up).	hideprices: true

2.5 Multiple price sets & demographics — the datasetkey

By default each affiliatecode has a single pricing/demographics configuration. But sometimes you want different configs under one code — for example, a web-to-print platform integrating the widget for many of its own clients, where each client has different retail pricing or different demographic visibility. We pre-configure each as a named datasetkey; you pass the right one at constructor time. If you omit it on a multi-config affiliate the first config is used as the default.

2.6 Widget interaction

Once initialised the customer interacts with the widget UI — tabs (Consumer / Business / New Mover / New Homeowner), location search, demographic filters, count display, polygon drawing, etc. The new three-panel widget adds an AI chat assistant on the left so customers can describe their audience in plain English ("homeowners earning $100K+ in Phoenix"). All of this is self-contained inside the widget DOM — you don't need to wire up any of the interactions yourself.

2.7 Widget conclusion — what fires when "Buy List" is clicked

Two things happen simultaneously:

1. The widget POSTs an XML payload to your conclusionurl from the Widget Server.
2. If you supplied a JS callback, it fires in the host page with the same data as a JS object.

XML payload to conclusionurl

POST https://yourapp.com/api/dw-conclusion
Content-Type: application/xml

<widget_conclusion>
  <list_criteria_id>123</list_criteria_id>
  <list_type>consumer</list_type>
  <qty>500</qty>
  <price_retail>50.00</price_retail>
  <price_wholesale>40.00</price_wholesale>
  <session_id>123456789</session_id>
</widget_conclusion>

JS callback payload

function myCallback(payload) {
  // payload object:
  //   criteriaid:  '123'
  //   listtype:    'consumer'
  //   price:       50.00          // retail price shown to user
  //   qtycount:    1247           // total available records
  //   qtydesired:  500            // how many user wants
  //   sessionid:   '123456789'    // your host session
  yourCart.attachAudience(payload);
}

Field	Description	Example
list_criteria_id	Unique ID for the criteria the customer built. Save this — you need it for fulfillment.	123
list_type	One of: consumer, business, newhomeowner, newmover.	consumer
qty	Number of records the user requested.	500
price_retail	Total price in USD shown to the customer (you charge this).	50.00
price_wholesale	Total price you owe LeadsPlease® (retail − 20%).	40.00
session_id	Whatever sessionid you passed at constructor time.	123456789

3. List fulfillment

The conclusion event is just the audience handoff — no list file exists yet. When you're ready to actually place an order (typically right after your own checkout completes), call our server-side get_list endpoint with the list_criteria_id you saved at conclusion.

3.1 List creation request

POST https://api.leadsplease.com/YOUR_AFFILIATECODE/get_list?u=usr123&p=pwd123&list_criteria_id=123&order_ref=YOUR-INVOICE-456

Param	Description	Required
u	Your affiliate username	Yes
p	Your affiliate password	Yes
list_criteria_id	The ID returned at Widget Conclusion	Yes
order_ref	Your internal order/invoice reference. Echoed in our reporting.	No
test	Pass test=true for the sandbox (no charge, anonymized data).	No

3.2 Response shapes

Three possible outcomes — Pending (typical first response), Ready (file generated, download URL inside), or Error. The first call usually returns Pending; you poll the same URL no more than every 30 seconds until you see Ready.

Pending — keep polling

<get_list>
  <list_criteria_id>123</list_criteria_id>
  <status_code>PENDING</status_code>
</get_list>

Ready — download the file

<get_list>
  <list_criteria_id>123</list_criteria_id>
  <status_code>READY</status_code>
  <list_download_url>https://api.leadsplease.com/.../uploaded_12345.csv</list_download_url>
</get_list>

Error

<get_list>
  <list_criteria_id>123</list_criteria_id>
  <status_code>ERROR</status_code>
  <message>List criteria has expired. You must rerun the Count.</message>
</get_list>

Common error messages: "List criteria has expired", "Invalid list criteria ID", "Permission denied", "Payment failure", "Too many queries".

3.3 Downloading the CSV

Once you have a Ready response, GET the list_download_url. The file is a standard Excel-compatible CSV and stays available for 14 days from creation. After 14 days you'll need to re-create the list (which will re-charge if non-test).

3.4 File format — sample CSVs

Each list type has its own column set. Reference samples:

• Consumer database sample
• Business database sample
• New Mover database sample
• New Homeowner database sample

3.5 Charging

List creation triggers an actual mailing-list file being generated and made available for download. The wholesale price (retail − 20%) is charged to your pre-registered card at the moment of fulfillment. You charge the customer the retail price on your own platform; the difference is your margin. No reconciliation, no invoice cycle, no per-customer billing decisions — the widget enforces it.

4. Testing — the test=true sandbox

While integrating, append &test=true to your fulfillment URL to use our test service:

POST https://api.leadsplease.com/YOUR_CODE/get_list?u=usr123&p=pwd123&list_criteria_id=123&order_ref=test-001&test=true

Test-mode features:

• List file generated and available via list_download_url exactly as in production
• No charge for list creation
• No requirement for a pre-registered credit card
• Anonymized list contents (PII fields masked) so test data can never be misused as real leads
• Pass an invalid list_criteria_id to trigger the error response shape for negative-path testing
• Can be exercised in a browser tab — no special tooling needed

5. Database updates & criteria expiry

We refresh the underlying mailing-list databases regularly. If a database is updated between widget conclusion and list fulfillment, one of two things can happen:

• The list fulfills successfully but the records may differ slightly from the preview (typically by <5%)
• The Widget Server rejects the request with "List criteria has expired. You must rerun the Count."

If you see the expired-criteria error, send the customer back through the widget — their selections (location, demographics, qty) are not preserved across the criteria rebuild today, but recovering is fast.

6. Versioning

Current stable widget version: v1.5 — loaded from https://widget.datawidget.com/lp_widget_1.5.js. The version number is embedded in the file path so bug fixes apply immediately to all integrations without a code change on your end. Breaking API changes ship under a new file path (lp_widget_1.6.js etc.) so existing integrations keep running unchanged until you opt in.

7. 3rd-party integrators — configurable fields per client

If you're a platform integrating the widget for many of your own clients (web-to-print SaaS, multi-location franchise tools, etc.), you'll want to expose certain widget config fields to your clients. The fields most commonly surfaced:

• affiliatecode
• username / password (server-side only — never in the browser)
• Widget version number
• buylistbtn skinning property (custom CTA text per client)
• Multiple price sets via datasetkey

Talk to us when you onboard — we'll provision a parent affiliate code for your platform plus per-client datasetkeys for differentiated pricing.

8. Compliant browsers & Terms of Service

Modern browsers (Chrome 90+, Firefox 80+, Safari 14+, Edge 90+) are fully supported. The new three-panel widget uses modern React + Leaflet; older versions degraded gracefully but the new widget targets evergreen browsers exclusively.

Terms of service

• Test data may be used only for testing your integration. Reselling or mailing to test data is a TOS violation.
• You must sign the LeadsPlease® Mutual Non-Disclosure + Confidentiality Agreement before integration. We email these on first signup.
• Full Terms of Service on leadsplease.com.