CRM field mapping is the rule that tells an integration which CRM property each incoming field fills. Each mapping is a pair: a source field key on one side, a CRM property on the other. Get the pair right and every lead lands in the correct column. Get it wrong and data goes to the wrong column or never arrives.
Most guides on this subject are about migrations: moving a whole database into a new CRM and matching the columns once. This one is about the mapping that runs every day between a lead capture form and the CRM, where a form filled in at a booth has to arrive as a proper lead with your custom questions intact. The same rules apply to a one-off import, and the FAQ covers where the two differ.
How a field mapping works
Picture the mapping as a two-column table inside the integration. The left column lists the fields your form collects, by their internal key: full-name, email, company-name, phone-mobile, and whatever custom questions you added. The right column names the CRM property each one fills. The integration reads that table on every sync.
Two things follow. The mapping doesn't care what the visitor saw on the form, only the key the answer was stored under. And a CRM property only receives data if a row in that table points at it. No row, no data, however carefully the visitor typed.
The three ways a mapping fails
A broken mapping shows up in one of three ways, and each points to a different cause. Naming which one you've got is most of the diagnosis.
Wrong column
The data arrives, in the wrong place. A job title lands under Company, or a mobile number ends up in the work phone field. Usually two similar fields were mapped the wrong way round. Easy to spot once you look, tedious to clean up, because every record looks complete at a glance.
Silent drop
The lead arrives and one field is empty, on every record. The visitor answered, the answer is sitting in the capture tool, and no mapping carried it across. Nothing errors, so nobody notices until a manager asks why the product interest column is blank for the whole show.
The whole record is rejected
Nothing arrives at all. The CRM refused the write because a required property had no value, or a value didn't fit the property's type. One bad field takes the whole lead down with it. This is the failure that makes people conclude the integration is broken, when it's doing exactly what it was told.
A scanned business card goes through the same mapping, with reading errors on top. What a business card scanner actually sends to the CRM covers that side.
Standard fields and custom fields
Every CRM has standard properties: first name, last name, email, phone, company, job title. Capture tools know these, so a built-in email field maps itself to the CRM's email property without anyone touching it. If a built-in field exists for what you want to collect, use it. A custom field labeled "Work Email" needs a mapping in every CRM you ever connect. The built-in email field doesn't.
Custom fields are everything else: "Which product line are you interested in?", "Budget this quarter", "Booth number". They have no standard meaning, so nothing can guess where they belong. Each one needs a mapping set by hand, to a custom property that already exists in the CRM. Which questions deserve a place on the form at all is a separate decision, covered in our guide to lead capture form design.
Create the CRM property first
A mapping can only point at a property the CRM already has, so the sequence is: create the property in the CRM, then open the mapping screen, then connect the two. Most integrations read the list of available properties from the CRM when the mapping screen loads. If you created the property a minute ago and can't find it, reload the page before assuming something failed.
Create it on the object the integration writes to. If your integration creates contacts, a property you added to companies or deals won't be offered as a target.
Match the types
Map text to text, dates to dates, numbers to numbers. The mismatch that bites most often is free text going into a dropdown property. The CRM only accepts values that exactly match one of the dropdown's options, so "enterprise" won't go into a property whose options are "Enterprise" and "SMB". Depending on the CRM, either that one field is dropped or the entire record is rejected.
If you want a dropdown in the CRM, give the visitor the same fixed options, spelled the same way. If the question has to be open-ended, map it to a text property and sort the answers out later.
Required CRM fields
Every CRM has properties it insists on. Salesforce's standard Lead object requires a Company. Zoho requires a Last Name on every Lead. HubSpot admins can mark contact properties as required, and Salesforce admins can add validation rules that demand a value in anything they like.
If the CRM requires a property, every synced record has to supply it, which means something on your form has to map to it. A required property with no mapping fails every single sync. In my experience it's the most common cause of "nothing is arriving at all", and it's invisible from the form side because the capture itself succeeds.
So check two things: each required CRM property has a mapping, and the form field feeding it is required too, because a mapping can't supply a value the visitor never gave. Salesforce will reject a lead with no company however well the company field is mapped. And if syncs stopped the day after an admin added a validation rule, you've found your cause.
Label vs key: why renaming is safe and recreating isn't
Every form field has two names. The label is what the visitor reads: "What's your work email?". The key is what the answer is stored under and what the mapping points at, something like work-email. The label is cosmetic. The key is structural.
That distinction explains most mysterious empty columns. Renaming a label is safe, because the key underneath doesn't move. Changing the key breaks every mapping that pointed at the old one, silently: the field keeps collecting answers, and they stop arriving in the CRM. The real trap is deleting a field and recreating it with the same label. The label matches, the key is new, and the old mapping now points at nothing.
Capture tools generate the key when the field is created, usually by slugifying the label. In Tap, for instance, two fields both labeled "Notes" get the keys notes and notes-1, and editing a label later leaves the key alone. So edit labels as much as you like, and never recreate a mapped field the night before an event. If someone did, re-map it before the doors open.
One name field, two CRM properties
Most forms ask for a full name in one box, because that's how people think of their own name. Most CRMs store first and last name separately. Something has to split it, and the usual rule is to split on the first space: "Mary Jane Watson" becomes Mary and Jane Watson.
That works for a lot of the world and badly for the rest. Arabic names often run to four parts with the family name last. Spanish and Portuguese naming puts two surnames after the given name. Some people write their family name first. If your market is one of these, collect first and last name as separate fields and map each directly, or you'll be fixing names in the CRM for months. Zoho makes the cost concrete: it requires a last name on every lead, so a visitor who types a single word as their whole name produces a record the CRM can refuse.
What happens to unmapped data
An unmapped field isn't lost. The answer stays on the lead in the capture tool, and you can usually include it in an export. It just never reaches the CRM. A "how did you hear about us" question your marketing team only reads in a monthly export can stay unmapped on purpose. The test is whether it's a choice or an oversight.
Changing a mapping mid-campaign
Say your team is three days into a trade show and someone notices that "Product interest" has been empty in the CRM since the doors opened. You add the mapping. From that moment, new leads arrive complete. The leads from the first three days don't change, because mappings apply to leads captured after the change. An edit doesn't go back and re-sync history.
Those earlier leads still have the answer stored on them, so history can be fixed two ways: re-sync them from the capture tool if it offers that, or export the affected leads and import them into the CRM, matching on email so you update rather than duplicate. Fixing it on day three is far cheaper than on day ten, which is the whole argument for checking one real lead in the CRM on the morning of day one.
Where the custom field gets created in each CRM
The mapping screen is in your capture tool, but the property has to exist in the CRM first. Here's where that happens, and what each CRM enforces on the way in.
| CRM | Where you create the custom field | What it enforces on write |
|---|---|---|
| HubSpot | Settings, Properties, Create property, on the Contact object | Required properties fail the whole sync; free text into a dropdown is rejected unless it matches an option exactly |
| Salesforce | Setup, Object Manager, Lead, Fields & Relationships, New | Company is required on standard Leads; validation rules reject the whole record |
| Zoho CRM | Setup, Customization, Modules and Fields, Leads, Create New Field | Last Name is mandatory; fields made mandatory in a layout are enforced too |
| Pipedrive | Settings, Data fields, Person, Add custom field | Custom fields carry internal keys rather than readable names; a good mapping screen shows you the label |
| Odoo | In your own Odoo, on the record type you chose (lead, opportunity or contact) | Your custom Odoo fields appear in the mapping list alongside the standard ones |
| Veeva Vault | Configured per organization by your Vault admin | Required fields, picklist values and validation rules differ per Vault and are enforced on write, so test against your own instance |
If you reach your CRM through Zapier instead, the mapping happens in the Zap's action step, and Zapier builds its field list from a real sample lead. A field left blank in the sample won't appear as a mapping option, so capture a test lead with every field filled in first.
A pre-event checklist
A website form can be fixed next week. A form filled in at a booth gets one chance, and the person who filled it in has walked off to the next stand. Run this the week before, while there's still time to change the CRM.
- Walk the mapping screen top to bottom. Every capture field has a mapping, or a deliberate reason not to.
- List the CRM's required properties. Each has a mapping, and the form field feeding it is required too.
- Check types on both sides, especially dropdowns and dates.
- Confirm the custom properties exist on the object the integration writes to.
- Capture one real test lead from a phone that isn't yours, open it in the CRM, and read every field, custom ones included.
- Write the mapping down outside the tool: one page, source key next to CRM property, so whoever added a field in March can check it in September.
- Agree who may change the form. Someone deleting and recreating a field the night before is how keys change.
How Tap handles CRM field mapping
In Tap, each CRM connection has a field mapping screen where every mapping pairs a capture field's name, which is its key and never its label, with a CRM field. Built-in fields with reserved keys such as email, full-name, company-name and phone-mobile map to the CRM's standard properties by default. Full-name is split on the first space, so in a market where that goes wrong you collect the parts as separate fields.
Custom fields are mapped by hand, in the order above: create the property in the CRM, reload the mapping screen so Tap re-reads the CRM's field list, then match the types. A captured field with no mapping is still stored in Tap, visible on the lead and included in exports. Mappings apply to leads captured after a change, so to correct history you export the affected leads and import them into the CRM. When a lead matches an existing contact, Tap merges: an empty incoming value never erases what the CRM already has, though a wrong value will replace it.
On the form side, Tap generates a custom field's key from its label when the field is created, so editing the label later leaves the mapping alone; the lead capture forms page lists the built-in keys. Enriched values and tags can be mapped like any other field. The connectors cover Salesforce, HubSpot, Zoho, Pipedrive, Veeva Vault and Odoo, with Zapier for anything else, and the integrations page has the list. The lead capture page covers the form itself, or you can book a demo and bring your field list.
FAQ
What is CRM field mapping?
CRM field mapping is the set of pairs that connects each incoming field, from a form, a capture tool or an import file, to the CRM property it should fill. Standard fields such as email and phone usually map automatically. Custom fields have to be mapped by hand to a custom property that already exists in the CRM.
What is the difference between data mapping and field mapping in a CRM?
People use the terms interchangeably. When there's a distinction, data mapping is the wider exercise done once during a migration or import: matching every column, converting types and translating values between two systems. Field mapping is the ongoing version, the fixed pairs an integration applies to every new record it sends to the CRM.
Why is my custom field empty in HubSpot or another CRM?
Check four things in order. The field has a mapping at all. The field's key hasn't changed, which happens when someone deletes and recreates it with the same label. The types match, since free text into a dropdown property is rejected. And the visitor actually filled it in: open the lead in the capture tool, and if it's empty there, the sync is working.
Can I change a field mapping after leads are captured?
Yes, and the new mapping applies to leads captured from then on. Leads captured before the change aren't re-synced by the edit. Their answers are still stored at the source, so you can re-sync them if the tool offers it, or export them and import into the CRM matching on email.
Do unmapped fields get lost?
No. An unmapped field's answer stays on the lead in the capture tool and can be exported. It just doesn't reach the CRM. Leaving a field unmapped is fine when it's a decision rather than an oversight.
Leave a comment
This site is protected by hCaptcha and the hCaptcha Privacy Policy and Terms of Service apply.