Field mapping

How mapping works#

When Zero Bad Leads receives a lead via webhook, it analyzes each submitted field and attempts to map it to one of the native fields. If the field is not recognized, it is automatically saved as a custom field.

This process happens in three steps:

Exact match: the field name exactly matches a native field
Aliases: the field name matches one of the 100+ recognized variations
Custom field: if there is no match, the field is saved as a custom field

Native fields#

The platform has 8 native fields that are used in qualification checks and outbound integrations:

Field	Description	Used in qualification
`email`	Lead email	Yes (full validation)
`phone`	Lead phone	Yes (E.164 format)
`first_name`	First name	No
`last_name`	Last name	No
`company`	Company name	Yes (AI scoring)
`job_title`	Job title	Yes (AI scoring)
`source`	Lead source	No
`tags`	Tags/labels	No

Alias system (100+ variations)#

Zero Bad Leads automatically recognizes over 100 field name variations in Portuguese, English, and Spanish. This means you don't need to rename the fields in your form.

Email aliases#

Recognized aliases
`email`, `e-mail`, `email_address`, `emailaddress`, `correo`, `correo_electronico`, `endereco_email`, `e_mail`, `mail`

Phone aliases#

Recognized aliases
`phone`, `telefone`, `celular`, `whatsapp`, `mobile`, `phone_number`, `phonenumber`, `tel`, `telephone`, `mobile_phone`, `personal_phone`, `cell_phone`, `numero_telefone`, `telefono`, `movil`

Name aliases#

Field	Recognized aliases
First name	`first_name`, `firstname`, `nome`, `primeiro_nome`, `name`, `given_name`, `nombre`
Last name	`last_name`, `lastname`, `sobrenome`, `family_name`, `surname`, `apellido`

Company aliases#

Recognized aliases
`company`, `empresa`, `company_name`, `companyname`, `razao_social`, `razaosocial`, `organization`, `organizacao`, `org`, `nombre_empresa`

Job title aliases#

Recognized aliases
`job_title`, `jobtitle`, `cargo`, `title`, `position`, `role`, `funcao`, `puesto`, `titulo`

Source aliases#

Recognized aliases
`source`, `fonte`, `origem`, `utm_source`, `lead_source`, `fuente`, `canal`

Aliases are case-insensitive. This means Email, EMAIL, and email are all recognized the same way. Spaces and hyphens are also normalized automatically.

Automatic custom fields#

When the platform receives a field that doesn't match any alias, it automatically creates a custom field. For example:

{
  "email": "john@company.com",
  "name": "John Smith",
  "annual_revenue": "$500,000",
  "employee_count": "50"
}

In this case:

email → mapped to the native Email field
name → mapped to the native First Name field (via alias)
annual_revenue → saved as a custom field
employee_count → saved as a custom field

Custom field limits#

The number of custom fields depends on your plan:

Plan	Field limit
Starter	10 fields
Pro	25 fields
Scale	Unlimited

When the limit is reached, new unrecognized fields are silently ignored. The lead data in native fields is still saved normally. Check your field usage under Settings → Custom Fields.

Configuring custom mappings#

In addition to automatic mapping, you can create manual mapping rules for specific cases:

Access field settings

Go to Settings → Custom Fields in the sidebar.

Create or edit a field

Click "New field" or edit an existing field. Configure:

Field name: how it appears on the platform
Type: text, number, date, or boolean
Additional aliases: add alternative names that should map to this field

For example, if you create a "Revenue" field and add the alias "faturamento", any webhook that sends the faturamento field will be automatically mapped to "Revenue".

Test the mapping

Send a test lead via webhook with the fields you configured and check the lead detail page to verify the mapping is correct.

Special platform formats#

Some platforms send data in non-standard formats. Zero Bad Leads automatically recognizes the following formats:

Platform	Format	Support
Elementor	Fields inside `fields` with `{id, value}` objects	Automatic
RD Station	Fields inside `leads[0]`	Automatic
Standard JSON	Fields at the root level of the JSON	Automatic
Form-encoded	`application/x-www-form-urlencoded`	Automatic

If your platform sends data in a format that is not recognized, contact support. We are always adding new formats.

Best practices#

Use Portuguese or English names: the platform recognizes both automatically
Avoid special characters: use underscores (_) instead of spaces or accented characters in field IDs
Be consistent: use the same field names across all your forms
Review fields periodically: go to Settings to see which custom fields are being used and remove unnecessary ones