Skip to main content

Documentation Index

Fetch the complete documentation index at: https://nango.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

Functions have access to storage that is scoped to the connection they run for. Use it to keep integration behavior tied to the customer, account, workspace, or tenant that authorized the connection. For the product-level workflow, see Customize per customer.

​
Connection metadata

Connection metadata is the default blob storage for Nango Functions. It is a JSON object stored on a Nango connection and available to action functions, sync functions, webhook functions, and event functions. Use metadata for:
  • Customer-specific settings, such as field mappings, filters, folders, projects, account IDs, or feature flags.
  • Function configuration values that should persist across executions.
  • Values discovered during setup, such as provider webhook subscription IDs or tenant-specific identifiers.
  • Configuration shared across multiple functions for the same connection.
Do not use metadata for synced datasets or large lists of records. For data replicated by sync functions, use the records cache.

​
Set and update metadata from your app

Set metadata after the customer chooses integration settings during onboarding or in your app’s settings UI. 
await nango.setMetadata(
    '<INTEGRATION-ID>',
    '<CONNECTION-ID>',
    {
        accountRegion: 'eu',
        syncArchived: false,
        fieldMapping: {
            companyName: 'Account_Name__c'
        }
    }
);
setMetadata replaces the metadata object. updateMetadata merges the provided fields into the existing object. For exact parameters and response shapes, see the set metadata API, update metadata API, Node SDK set metadata method, and Node SDK edit metadata method.

​
Read metadata from your app

Read metadata from your app when you need to render saved settings, pre-fill a configuration UI, or decide whether a connection is ready for syncs: 
const metadata = await nango.getMetadata('<INTEGRATION-ID>', '<CONNECTION-ID>');
You can also fetch the connection with the REST API: 
curl --request GET \
  --url 'https://api.nango.dev/connection/<CONNECTION-ID>?provider_config_key=<INTEGRATION-ID>' \
  --header 'Authorization: Bearer <ENV-SECRET-KEY>'

​
Read metadata inside a function

Define a metadata schema on the function, then call nango.getMetadata():
crm/syncs/contacts.ts
import { createSync } from 'nango';
import * as z from 'zod';

const Metadata = z.object({
    accountRegion: z.string().optional(),
    syncArchived: z.boolean().default(false)
});

export default createSync({
    description: 'Sync contacts',
    frequency: 'every hour',
    metadata: Metadata,
    exec: async (nango) => {
        const metadata = await nango.getMetadata();

        await nango.get({
            endpoint: '/contacts',
            params: {
                region: metadata.accountRegion,
                archived: metadata.syncArchived
            }
        });
    }
});
Inside a function, nango.getMetadata() automatically reads metadata for the connection being executed.
When a sync function reads metadata with nango.getMetadata(), metadata can be cached for up to 60 seconds during that execution. The next execution always reads the latest metadata.

​
Customer configuration pattern

A common customer configuration pattern is to ask the customer how their external custom fields map to your product model, then store that mapping as connection metadata. 
{
  "fieldMapping": {
    "internal_customer_id": "External_Customer_ID__c",
    "plan": "Plan__c"
  }
}
Use an action function to fetch available custom fields from the provider, save the customer’s choices as metadata, then read the mapping inside the sync function that fetches records. If a sync function should start only after the required configuration exists, start it after saving metadata: 
await nango.startSync('<INTEGRATION-ID>', ['contacts'], '<CONNECTION-ID>');

​
Records cache

The records cache is the storage layer for sync output. Sync functions write records with nango.batchSave(), nango.batchUpdate(), and nango.batchDelete(). Your app reads changed records through the records API or SDK. Use the records cache for synced external data, not for function configuration. See Records cache.