CRM integration data mapping: a practical checklist

Short answer

Data mapping for a CRM integration is a document stating, for every field, where it goes between two systems, in what form and under what rule. A good mapping table has one row per field and nine columns: source field, target field, type and format, transformation, required or not, direction, system of record, conflict rule and a sample value. Statuses and pick lists get their own correspondence table. Before go-live, the integration is tested with 20 real records. Most of the mapping is a business decision rather than a technical one, so IT and sales should write it together.

Why mapping is where integrations go wrong

The technical part of an integration — connecting the API — often takes a few days. The problems come later: numbers are written with +994 in one system and with 0 in the other, and duplicates appear; the "Interested" status has no counterpart in the target and lands as "New"; dates slip by a day because of a time-zone difference; two systems overwrite the same field in turn and nobody knows which value is the latest.

None of these are code bugs — they are decisions that were never written down. A mapping document forces those decisions before the integration is built.

The nine columns of a mapping table

1. 1Source fieldThe field's exact name and location in the source system: "lead.phone".
2. 2Target fieldIts counterpart in the target: "Contact → Phone (work)".
3. 3Type and formatText, number, date, list; for phones a format such as +994XXXXXXXXX.
4. 4Transformation"055 234 56 78" → "+994552345678"; "tomorrow" → a concrete date; manats → a number.
5. 5RequiredIf required in the target, what happens when the source is empty: skip, a default value, or an error?
6. 6DirectionOne-way (A → B) or two-way.
7. 7System of recordWhere the "truth" for this field is kept.
8. 8Conflict ruleIf it changed in both systems, which value wins.
9. 9SampleA real but anonymised value — to be checked in testing.

System of record: one owner per field

This is the most important decision: for each field, which system is the source of truth? For example, the need and summary coming from a conversation have the AI platform as their system of record; contract value and payment status belong to accounting or the main CRM. A field with no system of record creates "ping-pong" in two-way sync: each system overwrites the other's value.

Mapping statuses and lists

Two systems' statuses are never the same. Write a separate small table: which target value each source value becomes. For example, "Interested" → "Qualified", "Unreachable" → "Attempted to contact". For a value with no counterpart, decide: create a new value in the target, map it to the nearest one, or not send it. How the statuses themselves are set up is covered in CRM lead statuses.

The identity key and duplicates

The target system must know whether an incoming record is new. Choose one key for that: a normalised phone number, an email, or the source system's record ID. Without a key, every sync creates a new record. The most reliable approach is to store the source ID in its own field in the target: even if the phone changes, the link is not lost. Cleaning up existing duplicates is shown in CRM duplicate records.

Formats: phone, date, time zone, currency

• Phone: one international format, no spaces. If the source has variants, a transformation rule is written.
• Date: ISO format (2026-10-06) with the time zone stated — the gap between Baku time and UTC can shift a date.
• Currency: amount as a number, currency in its own field.
• Name: one field, or first and last name separately? If the target splits them, write the splitting rule.
• Text length: if the target field holds 255 characters, a long summary gets cut — know this in advance.

Empty values and defaults

How should a field that is empty in the source reach the target? There are three options, and one is chosen per field: not sent (the target keeps its old value), sent empty (the old value is cleared), or a default value is written. The most dangerous outcome is an empty value wiping a correct one in the target: a budget the manager typed in by hand disappears at the next sync.

A 20-record test

1. 1Pick a sample20 real records: complete, partial, with unusual numbers, with long text, arriving twice.
2. 2Send themTo a test environment or to records flagged as tests.
3. 3Check field by fieldCompare each row's sample column with the result in the target.
4. 4Send againWhen the same record arrives again, no duplicate should appear.
5. 5Make a changeEdit a field in the target by hand and check that the conflict rule works.

An illustrative example

This is an illustrative example. A training centre wants to pass leads from conversations into its existing CRM. The mapping table has 14 fields. Testing exposes three problems: the target CRM only accepts numbers starting with 0, two values in "Course type" have no counterpart, and a long summary is cut at 255 characters.

Decisions: a transformation rule is written for the number, the two course types are created in the target, and the summary goes to a separate "note" field. The second test passes all 20 records and the integration goes live.

Common mistakes

• Leaving the mapping to the technical team alone — business decisions get guessed.
• Syncing every field both ways.
• Not choosing an identity key.
• Ignoring time zones.
• Forgetting test records in the live report.

Limitations

A mapping document can only be as precise as both systems allow: if the target API does not accept certain fields, the table will not change that. Systems change their fields when they are updated, so the document must be kept alive and changes recorded with dates. Passing personal data to another system may also need its own legal assessment.

CRM integration in Vexvon

Vexvon can pass the leads it collects into a company's CRM: in Bitrix24 a record is created as soon as a number is found — with contact details, a one-sentence summary of the conversation and the channel. For other systems, events such as a new lead, a completed call or a status change are passed to the company's own system by webhook. When uploading a file, columns are matched to fields in the system and repeated numbers are cleaned. Which field goes where we write together, based on your system. More on integrations.

Next step

Before the integration, open the nine-column table as a blank template and fill in the first five fields with your head of sales: phone, name, source, status, summary. The plan for connecting a voice agent to a CRM is covered separately in AI call agent CRM integration. More articles are in the AI CRM section, and we can prepare the mapping together during a demo.