Nango has a flexible approach to letting you customize integrations per customer:
  • Store customer-specific data in the connection metadata
  • Access customer-specific metadata in integration functions to customize the integration behavior

​
Store customer-specific data

Nango lets you store arbitrary metadata on individual connections. This is useful for customizing an integration’s behavior per end-customer. Connection metadata can be set, updated, and retrieved with the SDK (reference) and API (reference). It can also be retrieved on the Nango UI, in the Connections tab > Select Connection > Authorization tab: Set connection metadata
  • Node
  • REST API
await nango.setMetadata(
    '<INTEGRATION-ID>', 
    '<CONNECTION-ID>', 
    { any_key: 'Any Value' }
);
Update connection metadata
  • Node
  • REST API
await nango.updateMetadata(
    '<INTEGRATION-ID>', 
    '<CONNECTION-ID>', 
    { any_key: 'Any Value' }
);
Get connection metadata
  • Node
  • REST API
await nango.getMetadata('<INTEGRATION-ID>', '<CONNECTION-ID>');
When accessing metadata from within a sync using nango.getMetadata(), the metadata is cached for up to 60 seconds. Changes made to metadata while a sync is running may not be visible until the cache expires.The next execution of the sync 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. Nango provides dedicated tools to support complex field mappings.

​
Prompt your customers for field mappings

In your app:
  • Fetch the list of custom fields available from the external API using an action
  • Display the full list of external custom fields to the user
  • Prompt the user to associate the data you need to collect to the relevant external custom fields
The output of this step should be a field mapping object such as: 
 {
    "internal_field_1": "custom_field_1",
    ...
 }

​
Store field mappings in the connection metadata

Update the relevant connection’s metadata with the obtained field mapping object using the SDK (reference) or API (reference):
  • Node
  • REST API
await nango.setMetadata('<INTEGRATION-ID>', '<CONNECTION-ID>', { internal_field_1: 'custom_field_1' });

​
Start the sync for each connection

Start the sync schedule programmatically for this connection with the SDK (reference) or API (reference):
  • Node
  • REST API
await nango.startSync('<INTEGRATION-ID>', ['hubspot-sync'], '<CONNECTION-ID>');
The sync’s internal logic will use the field mappings to fetch the relevant data from custom fields.
Questions, problems, feedback? Please reach out in the Slack community.