use-custom-field-mappings.mdx

title	sidebarTitle	description
Use custom field mappings	Use custom field mappings	Step-by-step guide on how to support custom fields using 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 (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):

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" }'

Start the sync for each connection

Start the sync schedule programmatically for this connection with the SDK (reference) or API (reference):

```typescript await nango.startSync('', ['hubspot-sync'], ''); ``` ```bash curl --request POST \ --url https://api.nango.dev/sync/start \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "connection_id": "", "provider_config_key": "", "syncs": [ "hubspot-sync" ] }' ```

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](https://nango.dev/slack).