A long-standing customer suddenly appears as a new customer because the ward name on a purchase order differs from the existing record. An employee creates another account to process the order quickly, while outstanding balances, loyalty points, and warranty history remain attached to the previous customer ID. The location has not changed, but the business has unintentionally split one customer relationship across two records.
This illustrative scenario highlights a risk that businesses need to control when updating addresses after administrative reorganization. In a CRM, sales platform, or customer database, the task goes beyond replacing commune and ward names. Businesses need to preserve customer identities and transaction relationships while distinguishing original addresses, normalized addresses, and verification status.
Mapvina can support the address search and comparison layer: Search/Geocoding finds locations from address input, while Reverse Geocoding retrieves addresses from coordinates. The relevant APIs support old and new administrative boundaries according to the integration documentation.[1] Preserving customer IDs, managing versions, and approving updates must be implemented within the business's own systems. Combining these two layers properly creates a migration process that can be audited and rolled back.
Problems often arise when software treats an address string as part of a customer's identity. One entry uses Vietnamese diacritics, another uses abbreviations, and a third uses the new administrative name: the same person may be treated as several different customers. Conversely, two customers in the same building may be merged incorrectly if address similarity carries too much weight.
The implementation principle should be agreed from the outset: the customer ID is a stable identifier; the address is an attribute that can change and has a history. Where a customer has multiple delivery locations or branches, each address needs its own identifier linked to that customer. An administrative name change at one location should neither automatically create a new customer nor delete the previous address.
For example, the illustrative record KH-000128 is linked to 37 transactions and two warranty requests. Its customer ID remains unchanged when the address is normalized. The system adds a new address version for the correct delivery location and records the approver and effective date. These figures explain the data structure; they are not actual implementation results.
Administrative renaming must also be distinguished from relocation. If the customer actually moves, the business should create or update an address with its own validity period. The label “normalization” must not conceal a real change in physical location.
An old-to-new name lookup table is useful, but it cannot resolve every record. In the reorganization list published by the Vietnam Government Portal, the new An Phú commune in An Giang was formed from entire administrative units and portions of the territory and population of other communes. The remaining portions were subsequently assigned to other new communes.[4] This provides a concrete example of why one old commune name does not necessarily map to a single new commune.
If a record contains only a commune name, with no house number, street, hamlet, or reliable coordinates, the software may lack sufficient information to choose the correct destination. Filling a mandatory field anyway produces an address that looks complete but has not been substantiated. The safer approach is to leave the record pending verification and request additional information.
Administrative names also need to be associated with their applicable periods. A spreadsheet without effective dates or reference sources becomes difficult to audit after several update cycles. Businesses should version their migration rules and record lookup times and supporting references. This information supports internal traceability; an API lookup should not be interpreted as legal proof of a residential or registered business address.
According to Mapvina's documentation, Search accepts a full address and returns location information, while Reverse Geocoding returns the nearest address from a coordinate pair.[1] These two lookup directions help businesses build proposed address updates rather than modify original records directly through string replacement.
For Search v2, the documentation describes new_admin=true for returning addresses under the new administrative boundaries and include_old_admin=true for including old address information when the new-boundary mode is enabled. Responses may include formatted_address, old_formatted_address, address components, coordinates, and a partial_match indicator.[3] These are useful inputs for a comparison screen, but a documented field does not mean that every result is complete or accurate down to the house number.
Reverse Geocoding v1 also documents these two parameters, alongside fields such as label, old_label, distance, and coordinate information.[2] When a business already has a field-verified point, a reverse lookup can help compare its address under the new administrative boundaries. However, the nearest result does not by itself prove that the point belongs to the correct apartment, store, or customer.
Another important limitation concerns identifiers. The Search v2 documentation states that official_id is returned only when the result is an administrative unit; place_id identifies a place.[3] Businesses should not assume that every address includes an official administrative code or replace a CRM's customer_id with a provider's place identifier.
Mapvina therefore supplies the lookup and address-data layer for comparison. The business remains responsible for identity management, automatic acceptance criteria, personal data, record-merging decisions, and historical storage. This article proposes an integration architecture; it does not claim that Mapvina itself supplies all these CRM governance functions.
A single address field is unlikely to satisfy both current operations and historical review. A minimum viable model should separate customers, locations, and individual address versions. Engineering teams can adapt field names to existing software, but the following meanings should be preserved:
customer_id: the customer identifier used by CRM, accounts receivable, sales, and warranty systems; unchanged during normalization.address_id: an address or service-location identifier, allowing one customer to have multiple locations and address types.original_address: the original text captured at intake or before migration, protected from being overwritten by the normalization job.proposed_address: a system-generated suggestion that is not automatically treated as approved.normalized_address: the accepted version for a defined operational purpose.verification_status: pending processing, pending review, accepted under rules, verified by a responsible reviewer, or insufficient information.latitude, longitude, coordinate_source, coordinate_verified_at: location information with its source and verification time; nullable when unsupported.provider, api_version, queried_at, rule_version: traceability for the lookup and the business's decision rules.valid_from, valid_to, recorded_at, verified_by, verification_note: validity periods, recording time, and approval accountability.The recording time is not necessarily the address's effective date. If the business learns about a change after it took effect, both timestamps should be stored separately. The date a batch job runs must not be used to infer when a customer moved.
The business's original address also differs from the old address returned by an API. The old_formatted_address or old_label field is the provider's representation of an address under the old administrative boundaries, not a verbatim copy of what the customer originally supplied.[2][3] These two types of information must therefore be stored separately. Combining them may destroy the very input evidence the business intended to preserve.
Previously issued documents require their own business procedures. From a data-design perspective, businesses should preserve the address snapshot attached to a transaction when it occurred and make the current address available when reviewing the customer record. Updating the CRM should not automatically rewrite addresses across all invoices, contracts, or historical transactions.
Before calling an API, the data team exports the customers, addresses, and transaction relationships within the migration scope. The export should have a version or cutoff timestamp and be stored in an access-controlled location. Engineering checks customer ID counts, address counts, transaction counts, and reference relationships.
Reconciliation must go beyond total row counts. A transaction reassigned to the wrong customer may leave the total count unchanged. Checks should cover the set of transaction_id–customer_id pairs, orphaned records, and critical information such as balances attributed to each customer. This baseline becomes an acceptance condition after migration.
Records with coordinates previously verified at the physical location should be handled differently from records containing only address strings. Flag records with missing house numbers, missing street names, ambiguous place names, or notes such as “near the market.” Records with disputed locations should go to the responsible business owner.
Whitespace and formatting can be normalized in a working copy, but the original input must remain intact. Apartment numbers, floors, alley details, and delivery notes should be preserved in suitable fields even if search results do not return them.
For reasonably complete address strings, the integration sends the necessary address information to Search v2. It stores the output in a proposal area together with the lookup timestamp and API version. Where old and new boundaries need to be compared, the application uses the documented parameters.[3]
For coordinates from a reliable source, the system can use Reverse Geocoding to retrieve the corresponding address in the desired administrative-boundary mode.[2] It is not necessary to call both services for every record. Choosing the processing path according to the available input helps control request volumes and reduce results that are difficult to explain.
If there is no result, retain the data currently in use and record the reason. A network error is not evidence that an address does not exist. Similarly, a no-result response is not a reason to delete a customer or invent an address to satisfy a form.
Internal rules should consider house numbers, streets, place names, location details, and the specificity of the result. If a response represents only a ward, its coordinates should not be interpreted as the customer's home location. Where partial_match is present, the record needs an appropriate review rule rather than automatic acceptance.[3]
Proposed coordinates can be compared with a verified point, but distance is only one signal. A single threshold is unlikely to suit apartment buildings, industrial parks, and rural areas equally well. Businesses should calibrate criteria against checked address samples, rather than turn a confidence score or distance into a guaranteed accuracy rate.
Forward and reverse lookups against the same data source can reveal some inconsistencies, but they are not two independent pieces of evidence. Records with insufficient information still require confirmation from the customer, a responsible employee, or an appropriate business source.
The review screen should place the original address, proposed address, and comparison details side by side. Employees should be able to accept a proposal, correct missing information, request confirmation, or reject it, with a reason recorded for each action. They should not need to open a new customer record simply to enter a new ward name.
The system should distinguish “accepted under rules” from “verified by a responsible reviewer.” Both may be usable under internal policy, but their supporting evidence differs. Clear status labels help customer service staff recognize when further confirmation is needed.
An update must target the correct customer_id and address_id, create a change history, and leave transaction-linking keys unchanged. Version checks before writing help prevent a bulk job from overwriting information that a customer has just corrected while the lookup was running.
Each work item should have an idempotency key and a completion status. When processing resumes after an error, the system should recognize a proposal that has already been applied rather than create another identical address. If synchronization with the ERP or sales application has not succeeded, the record should expose that state for the operations team to resolve.
After each batch, recheck transaction relationships, customer IDs, original addresses, and change histories. Business reviewers should sample both automatically accepted records and exception cases, rather than inspect only easy, complete records.
Rollback needs to account for which address version is currently in use and what legitimate changes have occurred since migration. Restoring an entire old backup can erase newer customer information. Rollback should therefore use version history and batch-level logs, and the procedure should be rehearsed before a wider rollout.
A one-time cleanup is insufficient if forms continue creating new customers from address strings. When customer service receives an address that differs from the previous one, the application should retrieve the record using the business's managed identifiers, then update the appropriate location within that record. An address should support verification, not determine identity on its own.
Phone numbers are not universally reliable keys either: they may be shared or reassigned. Customer merging requires a separate process with supporting evidence and approval authority. An address-normalization project should not silently double as an identity-consolidation exercise.
On the address-entry screen, Search can help employees find a location to select.[1] Businesses should still allow apartment details, recipient information, and contact notes to be retained in separate fields, and show the completed address for confirmation. Customers should not be forced to choose an incorrect result simply because the suggestions omit their location.
The customer-data owner, typically CRM operations or customer service, approves status definitions and acceptance criteria. The data team prepares the reference sample, classifies records, and measures discrepancies. Engineering builds the Mapvina integration, version storage, idempotent processing, and synchronization controls.
Field staff or customer service teams resolve records that lack sufficient evidence. Information security reviews access permissions, logs, and connection configuration; legal or compliance staff assess personal-data processing in the applicable context. The service provider should be consulted about API versions, data coverage, quotas, and usage terms.
This division of responsibility avoids a common gap: engineering completes the job and reports that updates have been made, but nobody confirms whether the new addresses are reliable enough for business use.
The first criterion is identity and relationship preservation: no unauthorized customer ID changes, and no transactions lost or misassigned because of migration. Next comes traceability: every applied update must retain the original address, new version, status, and processing basis. These are proposed acceptance conditions, not achievements published by Mapvina.
To measure address quality, businesses need a reference sample confirmed independently of the automated job. Proposal accuracy equals the number of proposals matching that reference sample divided by the number checked. Coverage equals the number of records with proposals eligible for review divided by the number in scope. Report these metrics separately: receiving a result is not the same as receiving a correct result.
Operational efficiency can be measured through handling time per record, the share requiring customer follow-up, and the number of new duplicate records created. Reports should separate input-quality groups and geographic areas so that good results on complete addresses do not hide risks in incomplete records.
For example, a hypothetical business selects 5,000 addresses for a pilot. Before implementation, the team agrees that all transaction relationships must be preserved and that records missing critical information cannot be approved automatically. Speed and accuracy targets are finalized only after baseline measurement. The 5,000-record sample is an illustrative pilot assumption, not a mandatory recommendation or an actual customer result.
Costs extend beyond API calls. Budgets should include CRM/ERP integration, data design, reference-sample preparation, exception-review staff, monitoring, and synchronization-error handling. Where input data is sparse, verification effort may matter more than eliminating a few lookup requests.
One estimating method is to multiply record volume by expected calls per record, add retries and supplementary checks, and then apply the actual contracted rates. Do not assume every record requires the same number of calls. Terms for retaining responses, reusing results, and retention periods should be confirmed with the provider before designing a cache.
For personal data, the application should send only the location information needed for the lookup. Do not attach customer names, phone numbers, outstanding balances, or full transaction histories to address-search requests. Information unnecessary for searching should be separated from the input string within the business's own systems.
API keys should be managed through secure configuration, not placed in tutorials, customer exports, or shared logs. The Search and Reverse Geocoding documentation notes that the public key is limited and intended for testing; production deployments should use their own keys according to the service guidance.[2][3]
Records near boundaries, abbreviated addresses, duplicate place names, outdated coordinates, and insufficiently detailed results need a route to verification. Automation rate should not become the overriding objective. An unchanged record that is correctly flagged is more useful than an incorrectly updated record reported as complete.
During the first 30 days of this illustrative roadmap, the business inventories where addresses are stored, agrees on a versioning model, selects a sample, and measures the baseline. Engineering tests the Mapvina connection in a test environment, checks actual response fields, and confirms usage terms. No bulk production changes are made at this stage.
During the next 30 days, the workflow runs in proposal-only mode. Employees review a representative sample while the data team analyzes errors by area and input quality. The team also rehearses connection failures, job retries, update conflicts, and rollback. Automatic acceptance is enabled only for groups meeting validated criteria.
In the following phase, production updates proceed in limited batches, with reconciliation immediately after each batch and expansion only when acceptance criteria are met. The 30/60/90-day schedule is a reference framework; actual timing depends on existing systems, data scope, and verification capacity. If incorrect relationships or overwritten original addresses are detected, stop the batch and investigate instead of continuing merely to reach a volume target.
The value of address migration lies in continuing to serve the right person through the same record. Employees can see the current address format, retrieve the original input, and understand its verification level. Balances, transactions, loyalty points, and warranty history remain attached to a stable customer ID.
Mapvina supports address lookup and comparison through Search/Geocoding, Reverse Geocoding, and the documented ability to work with old and new administrative boundaries.[1][2][3] Turning that capability into business value requires a data-governance layer with versioning, exception controls, and identity reconciliation.
Before updating the entire CRM, select an address sample with unnecessary personal information removed and assign a responsible reviewer. Discuss suitable APIs, data coverage, and testing with Mapvina, while agreeing on customer-ID preservation criteria with your operations team. The pilot should establish which records can be updated, which need verification, and whether every change can be traced back to its original data.
This article describes a proposed implementation approach, not a completed project report. Customer identifiers, transaction counts, sample size, and timelines are illustrative. API capabilities are based on Mapvina's documentation; response coverage, individual address quality, quotas, costs, and service terms must be checked through testing and actual agreements. The administrative-reorganization example comes from a government source. This article does not provide a complete conversion table and does not replace address verification or legal advice.
[1] https://docs.mapvina.com/api-integration
[2] https://docs.mapvina.com/api-integration/reverse-geocoding/v1
[3] https://docs.mapvina.com/api-integration/search/v2
[4] https://xaydungchinhsach.chinhphu.vn/danh-sach-3321-don-vi-hanh-chinh-cap-xa-tai-34-tinh-thanh-sau-sap-xep-sap-nhap-119250710102358656.htm
Moving this industry forward requires not only skill, talent and expertise, but also imagination. All are welcome.
