Lead Distro AILead Distro AI
DocsCampaignsField Mapping

Field Mapping

Configure the data fields each lead carries in a Lead Distro AI campaign — system fields, custom fields, sub IDs, vertical-specific patterns, field transforms (Phone Formatter, Date Formatter), and validation.

Last updated:

What is Field Mapping?

Field mapping defines the schema of leads in a campaign — which fields are required, which are optional, what format each field expects, and how fields are validated and transformed on ingest. It's the contract between your suppliers (sending leads) and your buyers (receiving leads).

System vs Custom Fields

TypeExamplesNotes
System fieldsfirst_name, last_name, email, phone, state, zip_code, sourceAlways available. Standard contact fields used in routing, suppression, de-duplication, and reporting.
Custom fieldsincident_date, case_type, service_type, roof_age, solar_quote_sizeDefined per campaign based on vertical. Used in inbound filters, buyer filters, and the buyer-facing payload.

Vertical-Specific Examples

VerticalCustom fields typically used
Personal injury / MVAincident_date, case_type, at_fault_party, injury_type, medical_treatment, attorney_representation, police_report, vehicle_type, preferred_language
Home services (roofing)roof_age, roof_material, damage_type, insurance_claim, home_ownership, service_zip
Solarmonthly_electric_bill, home_ownership, roof_type, shading, state_incentive_program
Insurancecurrent_carrier, policy_renewal_date, coverage_type, vehicle_year, home_value
B2B SaaScompany_size, industry, current_solution, decision_timeline, budget_range
Debt / credit repairdebt_amount, debt_type, monthly_income, credit_score_range

Configuring Field Mapping

  • Go to your Campaign and open the Field Mapping section.
  • Each system field is already present — mark required vs optional as appropriate.
  • Click Add Custom Field to add vertical-specific fields. Set name, data type (text, number, date, phone, email, boolean), and required/optional.
  • (Optional) Apply a transform to normalize incoming data — e.g., Phone Formatter to convert any phone format to E.164, Date Formatter for international date formats, To Number to coerce string numbers.
  • (Optional) Set a validation pattern (regex) for fields that need strict format checking.
  • Save — the schema applies to all incoming leads from the next ingest onward. Existing leads keep their original field set.

Field Transforms

TransformInputOutput options
Phone FormatterAny phone format7 outputs: E.164 (+15551234567), +1 (555) 123-4567, 10-digit (5551234567), dashes (555-123-4567), parens ((555) 123-4567), dots (555.123.4567), local (123-4567)
Date FormatterAny date formatUS (MM/DD/YYYY, MM-DD-YYYY), UK/EU (DD/MM/YYYY, DD-MM-YYYY, DD.MM.YYYY), AU, MX, ISO (YYYY-MM-DD)
To NumberString numbers ("1500", "$1,500")Integer (1500) — strips formatting
Trim WhitespaceText with leading/trailing spacesCleaned text

Transforms run on ingest, before inbound filters. So a filter rule like phone matches E.164 format will pass after the Phone Formatter transform regardless of how the supplier originally formatted the phone number. Combine transforms with strict validation for clean buyer-facing payloads.

Sub IDs

A sub ID is a tag your source sends along with the lead so you can see exactly where it came from. One publisher inside an affiliate network, one ad creative, one landing page variant. Without it, every lead from that source looks the same. With it, you can tell which slice is actually selling and which is burning money.

Sub IDs are ordinary custom fields, so there is nothing special to turn on. Open your campaign, go to Fields, click Add New Field, then Quick Add and pick from the Sub IDs group. You get 5 slots (sub_id_1 through sub_id_5). They are opt-in on purpose: campaigns that do not use sub IDs stay clean instead of carrying empty fields.

How the source sends itExample
URL parameter (hosted forms and tracking links)https://go.leaddistro.ai/f/your-form?sub_id_1=google_search&sub_id_2=headline_a
Hidden form field
API post body{ "sub_id_1": "taboola", "sub_id_2": "creative_red_v2" }

Once a sub ID is mapped, it works everywhere a field works: it shows on the lead detail page, you can filter and route on it with inbound filters and destination filters, you can pass it through to your buyers in the delivery payload, and you can group any report by it under Reports to compare accept rate, cost, revenue, and profit per sub ID.

Pick a naming convention with your sources before you launch and write it into the insertion order. sub_id_1 for the publisher or traffic source, sub_id_2 for the creative or landing page. Sub IDs are only as useful as they are consistent.

Frequently Asked Questions

Can Lead Distro AI handle sub IDs from sources?
Yes. Add them to the campaign as fields: Fields tab, Add New Field, Quick Add, then the Sub IDs group, which gives you sub_id_1 through sub_id_5. Your source can pass them as a URL parameter, a hidden form field, or a key in the API post body. After that they appear on the lead, work in inbound and destination filters, pass through to buyers in the delivery payload, and can be used as a group-by dimension in Reports.
Coming from LeadProsper: what happens to lp_subid1 and lp_subid2?
LeadProsper pre-adds two sub ID fields (lp_subid1, lp_subid2) to every campaign whether you use them or not. Lead Distro AI keeps them opt-in instead, and gives you 5 slots rather than 2. If you use the LeadProsper import, your existing lp_subid1 and lp_subid2 fields come across automatically as custom fields, so your sources keep posting the same payload with no change. If you are setting up by hand and do not want to change your posting URLs, just type lp_subid1 as the field name in the Add New Field dialog. Any field name works.
What's the difference between sub IDs and UTM parameters?
They solve the same problem from two directions. UTM parameters describe your own paid traffic (utm_source, utm_campaign, utm_content) and are the standard your ad platforms already speak. Sub IDs are free-form tags your sources control, which is what you want when the traffic is not yours, for example an affiliate network passing its own publisher ID. Both are added the same way under Quick Add, and both work as report dimensions. Use UTMs for your own media buying and sub IDs for third-party sources.
What's the difference between system fields and custom fields in Lead Distro AI?
System fields (first_name, last_name, email, phone, state, zip_code, source) are standard contact fields available in every campaign — used in routing, suppression, de-duplication, and reporting. Custom fields are defined per campaign based on the vertical — incident_date and case_type for legal, roof_age for roofing, etc. Custom fields appear in the buyer-facing payload nested under custom.
Can I add a new field to an existing campaign without breaking existing leads?
Yes. New fields apply to leads ingested from the change forward. Existing leads keep their original field set — they don't retroactively gain the new field. If you need backfill, export existing leads, enrich them externally, and re-import via CSV — but for most use cases just adding the field and going forward is fine.
Do field transforms run before or after inbound filters?
Before. Transforms normalize data on ingest so filters see consistent input. Example: Phone Formatter converts (555) 123-4567 to +15551234567, then a filter rule like phone starts with +1 works regardless of the supplier's original format. Without the transform, you'd need filter rules covering every possible phone format.
What happens when a required field is missing on a lead?
Lead Distro AI rejects the lead with status REJECTED and reason missing_required_field. The supplier's API call returns 400 with the specific field name(s) so they can fix the integration. Required-field rejections are logged in the dashboard for diagnostic visibility — common pattern is a supplier missed a custom field's required flag during their onboarding.
Can I have different field mappings on different campaigns?
Yes — every campaign has its own field mapping. A multi-vertical agency (e.g., personal injury + home services) configures one campaign per vertical with its own field set. Suppliers and buyers attached to each campaign automatically use that campaign's schema. Shared suppliers across campaigns adapt their payloads to each campaign's flo_campaign_id.
How does Phone Formatter handle international numbers?
Phone Formatter is US-centric by default — assumes 10-digit US numbers and normalizes to E.164 with +1. For international support, set the default country at the campaign level (e.g., MX for Mexico, UK for United Kingdom) so the formatter applies the right country code. International numbers with explicit country codes (+44...) are preserved correctly.
Can I validate phone numbers and emails on ingest?
Yes — Lead Distro AI runs format validation automatically on phone and email system fields. For deeper validation (e.g., email deliverability, phone line-type lookup), enable the Email Validation and Phone Validation integrations in Settings. These add ~200ms per lead but catch fake leads before they reach buyers.

Related Articles

Campaign Basics
Create and configure lead distribution campaigns in Lead Distro AI. Choose your routing method, set daily caps, map custom fields, and assign buyers with priority rules for every pipeline.
Inbound Filters
Use inbound filters to reject leads at the campaign level before distribution. State allowlists, custom field rules, AND/OR groups, scheduling, and FAQs for Lead Distro AI.
Test Mode
Use Test Mode on sources and destinations to validate campaign setup before going live. Test leads flow through the full distribution path, excluded from billing and Meta CAPI.

If you have any questions, send us an email at support@leaddistro.ai

Direct Post vs Ping-PostInbound Filters