Customer-configurable integrations let each tenant map its own fields and custom objects from a CRM or ERP into your product. The design needs a stored mapping per tenant, schema discovery from the source system, validation before a mapping goes live, versioned configuration, and a build-or-buy decision based on how much customisation your customers truly need.
If you sell a SaaS product, your first CRM or ERP connector is easy: one fixed mapping that you own. The trouble starts with customer number five, who has twelve custom fields, a custom object that models projects, and a different idea of what "status" means. This guide is for CTOs and engineering leads in that position, asking how to let customers map their own custom fields and custom objects into a data model you control. It stays vendor-neutral: product names appear only as examples of a category, and it gives you criteria for evaluating platforms rather than a ranking. For the building blocks beneath this, read system integration approaches and the enterprise integration patterns decision guide. If you want an engineering team to design the layer, see our systems and API integration service.
Key takeaways
- Separate four things that teams mix up: connection (credentials), configuration (mappings), state (cursors, ID maps) and data (records).
- Choose a mapping model deliberately: fixed schema with a flexible extension area is the usual starting point.
- Discover the customer's schema at setup and on a schedule, compare it with the last snapshot and degrade gracefully when fields change.
- Validate a mapping with sample data before it goes live, and show the customer exactly which records failed and why.
- Version every mapping so each sync run is explainable and a bad change can be rolled back.
- Evaluate build versus buy against your five most demanding customers, not against a feature list.
Why are customer-configurable integrations harder than a normal integration?
Because the schema is not yours. Each tenant's CRM or ERP has its own custom fields, custom objects, picklist values and relationships, and these change without telling you. Your integration must learn the tenant's schema, store the tenant's choices and cope with drift, while your own data model stays consistent.
A fixed connector assumes a known schema and breaks when it differs. A configurable integration treats the schema as data: it asks the source what exists, lets an administrator decide how it maps onto your model, and checks continuously that the mapping still holds. That adds five concerns to the usual sync problems: discovery, mapping, validation, versioning and per-tenant isolation.
What does the architecture look like?
Think in layers: a connection layer that holds authorised access, a discovery layer that reads the source schema, a mapping layer that holds the tenant's choices, a transform and validation layer, a sync engine, and observability per tenant. Keep each layer separately testable.
| Layer | Responsibility | Key decision |
|---|
| Connection | OAuth or key storage, token refresh, per-tenant revocation | Secrets vault; never store credentials in mapping config |
| Discovery | Reads objects, fields, types, relationships, picklists | How often, and what happens on change |
| Mapping | Stores source-to-target rules per tenant | Mapping model and storage format |
| Transform and validate | Converts types, applies rules, rejects bad records | Declarative rules versus code |
| Sync engine | Reads changes, writes in order, retries, tracks cursors | Webhooks, polling or both |
| Observability | Per-tenant logs, failure queue, replay, alerts | What the customer's admin can see |
Which mapping model should you use?
Start with a fixed core schema plus a controlled extension area, and let tenants map source fields to either a core field or an extension attribute. Move to a fully dynamic schema only if customers must create new entity types in your product, because it costs more in querying, reporting and support.
| Model | How it works | Strength | Weakness | Fits when |
|---|
| Fixed schema | Source fields map to your columns | Simple, fast queries | No room for customer fields | Few, uniform customers |
| Fixed core plus extension attributes | Core columns plus a typed key-value or JSON area | Flexible and queryable enough | Needs typed, indexed extension design | Many SaaS products |
| Canonical model with adapters | Every source maps to your internal model through an adapter per system | Adding the next connector is adapter work | Canonical model needs governance | Many source systems |
| Dynamic, metadata-driven schema | Customers define entities and fields in your product | Maximum flexibility | Complex reporting, permissions, migrations | Platform-style products |
| Custom code per tenant | Scripts or expressions run for each tenant | Handles any quirk | Security, support and upgrade burden | Only with a sandbox and strict limits |
Keep transformations declarative (rename, convert type, combine, look up a value, default, filter) so you can validate and version them. If you must allow expressions, run them in a restricted sandbox with time and memory limits.
How do you bring custom objects into a hierarchical data model?
Map by identity and relationship, not just by field. Store each record's source ID and source system against your own ID, resolve parent references through that map, load parents before children, and decide how to flatten, nest or reject relationships your model does not support.
Your model might be a tree such as Account, Project, Task, while the customer's CRM has an Engagement object linked to Accounts and a many-to-many link to Contacts. Work through the questions below.
- Identity map. A table keyed by tenant, source system, object type and source ID, holding your internal ID. Without it you cannot update, delete or resolve a relationship.
- Relationship resolution. A child that arrives before its parent is parked and retried, or the parent is fetched on demand.
- Cardinality. Many-to-many links in the source need a junction in your model, or a decision to keep only the primary link.
- Level mismatch. If the source has three levels and yours has two, define which level collapses and keep the original reference in an extension attribute.
- Deletes. Decide whether a source deletion removes, archives or ignores the record. Many APIs do not report hard deletes through simple "modified since" queries, so plan for tombstones, change events or periodic comparison.
Where do you store per-tenant configuration?
Store each tenant's mapping as a versioned, schema-validated document scoped by tenant ID, separate from credentials and from sync state. The document says what to sync and how; the vault holds access; a state table holds cursors and ID maps.
A mapping document typically contains: the connection reference, the enabled objects, field rules (source path, target field, transform, required flag, default), filters, direction (read only, write back or both), conflict rule (which side wins), and schedule. Keep these rules:
- Config is not state. Cursors and last-run times change every minute; mappings change rarely. Mixing them breaks versioning.
- Credentials are not config. Reference a secret by ID; never embed it.
- Draft versus published. An administrator edits a draft, tests it, then publishes. The engine reads only published versions.
- Audit. Record who changed what and when, since a mapping change alters business data.
- Tenant isolation. Every query and every worker task carries the tenant ID, and rate limits and queues are per tenant. Our guide on integration SLAs and vendor accountability covers what to ask a shared-platform vendor about isolation and per-account service levels.
How do you discover a customer's schema, and keep up with changes?
Call the source system's metadata interfaces at setup and on a schedule, store a snapshot, compare it with the previous one and classify the change. Many major CRMs expose metadata for objects and fields; ERPs vary, so check the vendor's current documentation.
Examples of what exists: Salesforce provides describe operations for objects and fields, HubSpot provides properties and custom-object schema APIs, and Microsoft Dataverse (behind Dynamics 365 sales and service apps) publishes metadata through its Web API. Business Central exposes standard APIs and OData services, and custom fields usually need an extension to appear in an API, so confirm with the customer's administrator. Zoho and Pipedrive expose field metadata for their records through their APIs.
| Change detected | Safe response |
|---|
| New field | Ignore until an administrator maps it; notify |
| Field removed | Pause that mapping only; alert the administrator; keep the rest running |
| Label renamed, internal name unchanged | No action; update the display label |
| Type changed | Revalidate; pause the mapping if no conversion exists |
| Picklist values added or removed | Flag unmapped values; send affected records to a review queue |
| Object removed or access revoked | Pause the object; alert; do not delete local data automatically |
Drift in one field should never stop the whole sync.
How do you validate a mapping before it goes live?
Validate in layers: structure (the field exists and the types are compatible), semantics (required fields, lengths, picklist values, date and time zone, currency, empty versus null) and behaviour (a dry run on sample records). Show the administrator a preview and per-record errors in plain language.
Checks worth building:
- Source and target type compatibility, with the allowed conversions listed.
- Required target fields mapped or defaulted.
- Picklist values mapped one by one, with a default or rejection rule for the unmapped.
- Dates and times: source time zone, target storage convention.
- Numbers: precision, currency, thousands separators.
- A "test mapping" run on a handful of real records with before-and-after shown.
- A hard stop on a mapping that would overwrite data on the source side unless write-back was explicitly enabled.
How should mappings be versioned?
Treat every published mapping as an immutable version. Each sync run records the mapping version it used, so any result can be explained, and rollback means republishing an earlier version. Plan a migration path for the day your own canonical data model changes.
Pin the source API version you call and test before upgrading, since providers retire old versions on published schedules. When your model changes, either migrate stored mappings automatically with a tested script or support the previous model version for a stated period. Keep a changelog customers can read.
Evaluate on the work your hardest customers need: custom-object and custom-field access, an embeddable mapping interface, schema discovery, per-tenant isolation, real-time events and observability. Test each candidate with three real, messy customer environments. Claims of deep coverage are not evidence.
The market has several categories: embedded integration platforms (an iPaaS you place inside your product), unified APIs that normalise many systems into one common model, workflow-automation connectors, and in-house builds. Unified APIs can trade coverage of unusual customisation for speed, so check whether custom objects and fields pass through. Use a weighted scorecard with weights you choose.
| Criterion | What to verify | Example weight (illustrative) |
|---|
| Custom objects and fields | Read and write access, relationships, picklists | 20% |
| Mapping interface | Embeddable, white-labelled, customer-administrator friendly | 15% |
| Schema discovery and drift handling | Scheduled discovery, change events | 15% |
| Real-time and reliability | Webhooks or change events, retries, replay | 15% |
| Tenant isolation and observability | Per-tenant limits, logs, alerts | 15% |
| Data handling | Where customer data is processed and stored, sub-processors | 10% |
| Commercial fit | Pricing unit and how it scales with customers, exit options for mappings | 10% |
For the question of adding a Business Central integration without building it in-house, apply the same table. Confirm how the provider reaches Business Central's APIs, whether it supports your customers' custom fields through extensions, how authentication is handled, and whether the same platform covers the next five systems on your roadmap. For comparing a CRM connector roadmap across Salesforce, HubSpot, Dynamics, Pipedrive and Zoho, score each platform on your five target systems separately, because "supports CRM" can hide large differences in depth.
Which CRM is best for custom objects?
No ranking holds across editions and plans, so compare each CRM on the questions below instead. Ask how custom objects are defined and limited by edition, whether the API reads and writes them and their associations, whether metadata discovery and change events cover them, and what rate limits apply to your tenants' plans.
Answer those from current documentation, then compare. The full criteria checklist is in CRM customization depth checklist.
Worked example: a project-management SaaS reading customer engagements
This example is illustrative; the field names are invented.
A SaaS product holds Clients, Projects and Milestones. Customer A uses a CRM with a custom object called Engagement. Customer B uses a different CRM with a similar custom object called Contract Work.
| Source field | Target | Transform | Validation |
|---|
| Engagement name | Project name | Trim | Required, 200 characters |
| Account (lookup) | Client | Resolve via identity map | Parent must exist |
| Stage (picklist) | Project status | Value map: Proposal to Draft, Won to Active, Closed to Archived | All values mapped (a "Lost" value would be flagged as unmapped) |
| Start date | Start date | Convert to UTC date | Not later than end date |
| Budget class (custom) | Extension: budget_class | None | Optional |
Two months later Customer A's administrator deletes "Budget class". Discovery detects the removal. Only that mapping pauses, a notice goes to the administrator and the other four mappings keep running. They republish a new version without the field, and the sync log shows which version each run used.
Customer B's Contract Work object has a "Phase" picklist with different values. Its administrator maps them to the same Project status through a separate value map; the core model and the sync engine do not change, which is the reason for the fixed-core-plus-extension design.
When is this the wrong approach?
If you have three customers with the same needs, build a fixed connector and add a second one when you need it; a mapping interface is premature. If customers need arbitrary transformations, a services engagement may serve better than a self-service tool. If source data is dirty, a mapping tool will carry the dirt faster, so fix it at source. And do not build a fully dynamic schema if an extension area covers the requests.
Glossary: custom object, a customer-defined record type in a CRM or ERP; schema discovery, reading which objects and fields exist; canonical model, your internal common representation; identity map, a table linking source IDs to your IDs; tenant, one customer account in a multi-tenant product.
How Timeline Digital approaches configurable integrations
For configurable integrations, Timeline Digital uses the Plan step to scope the connection, mapping, validation and monitoring layers you need, with your own five most demanding customer environments as the test cases. Timeline Digital was founded in 2013, is based in Islamabad and delivers remotely. A free pilot of 2 to 3 key modules lets you test the result before the final agreement, schedules are set from your requirements in the Plan step, and the code is handed over on full payment. See our API development services.