Field Mapping
Configure the data fields each lead carries in a Lead Distro AI campaign — system fields, custom fields, 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
| Type | Examples | Notes |
|---|---|---|
| System fields | `first_name`, `last_name`, `email`, `phone`, `state`, `zip_code`, `source` | Always available. Standard contact fields used in routing, suppression, de-duplication, and reporting. |
| Custom fields | `incident_date`, `case_type`, `service_type`, `roof_age`, `solar_quote_size` | Defined per campaign based on vertical. Used in inbound filters, buyer filters, and the buyer-facing payload. |
Vertical-Specific Examples
| Vertical | Custom fields typically used |
|---|---|
| Personal injury / MVA | `incident_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` |
| Solar | `monthly_electric_bill`, `home_ownership`, `roof_type`, `shading`, `state_incentive_program` |
| Insurance | `current_carrier`, `policy_renewal_date`, `coverage_type`, `vehicle_year`, `home_value` |
| B2B SaaS | `company_size`, `industry`, `current_solution`, `decision_timeline`, `budget_range` |
| Debt / credit repair | `debt_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
| Transform | Input | Output options |
|---|---|---|
| Phone Formatter | Any phone format | 7 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 Formatter | Any date format | US (`MM/DD/YYYY`, `MM-DD-YYYY`), UK/EU (`DD/MM/YYYY`, `DD-MM-YYYY`, `DD.MM.YYYY`), AU, MX, ISO (`YYYY-MM-DD`) |
| To Number | String numbers (`"1500"`, `"$1,500"`) | Integer (`1500`) — strips formatting |
| Trim Whitespace | Text with leading/trailing spaces | Cleaned 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.
Frequently Asked Questions
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 suppliers to validate campaign setup before going live. Test leads flow through the full distribution path with is_test flag, excluded from billing and Meta CAPI.
If you have any questions, send us an email at support@leaddistro.ai