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 (step-by-step guide)
  • 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 with the SDK (reference) or API (reference):

  • Node


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


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 (step-by-step guide).

Questions, problems, feedback? Please reach out in the Slack community.