Many integrations need customer-specific behavior: custom field mappings, record filters, or feature toggles. Larger customers often run custom schemas in CRMs, ERPs, or productivity tools, so a one-size-fits-all approach won’t work.
Per-customer configuration lets you adapt without forking code. The core logic stays the same, while each connection supplies the rules that shape requests, transformations, and validations.
How Nango helps:
- Store customer configuration on the connection as metadata—it lives alongside the integration instance for each customer
- Access metadata from any function to read mappings, filters, and flags at runtime
Best practices
-
Start with defaults. Only add configuration when real needs recur across customers.
-
Design a minimal, typed schema. Mirror actual use cases (field mappings, record filters, feature flags). Avoid open-ended key/value bags.
-
Build UI in your app to capture config, persist it on the connection, and reference it in your functions.
-
Roll out incrementally and version the schema when it changes.
-
Monitor and refine. If a rule becomes universal, fold it back into default behavior to reduce configuration surface area.
Store customer-specific data
Connection metadata can be set, updated, and retrieved with the SDK (reference) and API (reference). You can also view it in the Nango UI: Connections tab > Select Connection > Authorization tab.
await nango.setMetadata(
'<INTEGRATION-ID>',
'<CONNECTION-ID>',
{ any_key: 'Any Value' }
);
curl --request POST \
--url https://api.nango.dev/connection/<CONNECTION-ID>/metadata \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--header 'Provider-Config-Key: <INTEGRATION-ID>' \
--data '{ "any_key": "Any Value" }'
await nango.updateMetadata(
'<INTEGRATION-ID>',
'<CONNECTION-ID>',
{ any_key: 'Any Value' }
);
curl --request PATCH \
--url https://api.nango.dev/connection/<CONNECTION-ID>/metadata \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--header 'Provider-Config-Key: <INTEGRATION-ID>' \
--data '{ "any-key": "Any Value" }'
await nango.getMetadata('<INTEGRATION-ID>', '<CONNECTION-ID>');
curl --request GET \
--url 'https://api.nango.dev/connection/<CONNECTION-ID>?provider_config_key=<INTEGRATION-ID>' \
--header 'Authorization: Bearer <TOKEN>'
When accessing metadata from within a sync using nango.getMetadata(), the metadata is cached for up to 60 seconds. Changes made while a sync is running may not be visible until the cache expires.The next sync execution will always have access to the latest metadata.
Use custom field mappings
Field mappings are necessary when a sync needs to access information stored in external custom fields.
1. Prompt your customers for field mappings
In your app:
- Fetch the list of custom fields from the external API using an action
- Display the full list of external custom fields to the user
- Prompt the user to associate your data fields to the relevant external custom fields
The output should be a field mapping object:
{
"internal_field_1": "custom_field_1",
"internal_field_2": "custom_field_2"
}
await nango.setMetadata('<INTEGRATION-ID>', '<CONNECTION-ID>', { internal_field_1: 'custom_field_1' });
curl --request PATCH \
--url https://api.nango.dev/connection/<CONNECTION-ID>/metadata \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--header 'Provider-Config-Key: <INTEGRATION-ID>' \
--data '{ "internal_field_1": "custom_field_1" }'
3. Start the sync for each connection
Start the sync schedule programmatically with the SDK (reference) or API (reference):
await nango.startSync('<INTEGRATION-ID>', ['hubspot-sync'], '<CONNECTION-ID>');
curl --request POST \
--url https://api.nango.dev/sync/start \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"connection_id": "<CONNECTION-ID>",
"provider_config_key": "<INTEGRATION-ID>",
"syncs": [ "hubspot-sync" ]
}'
