Sync data from an API

Step-by-step guide on how to continuously sync data from an API (using a sync template).

Pre-requisite: creation of an integration and at least one connection (step-by-step guide).

Activate a sync template

Nango uses syncs to read data from APIs continuously. For common use cases, templates are available to let you get started fast.

Select your integration in the Integrations tab, and navigate to the Scripts tab. Available sync templates will appear in the Sync Scripts section. Select the relevant one and enable it with the toggle.

Nango will automatically sync the corresponding records in the background for each relevant connection.

Is there no template for your API? Or none matching your exact use case?

Learn more about how to build a custom integration, extend a template or request custom integrations from Nango experts.

Listen for webhooks from Nango

Nango sends webhook notifications to your backend whenever new data is available.

To set this up, go to the Environment Settings tab and configure a Webhook URL to which Nango will send notifications.

The webhook from Nango is a POST request with the following body (reference):

{
    "connectionId": "<string>",
    "providerConfigKey": "<string>",
    "syncName": "<string>",
    "model": "<string>",
    "responseResults": { "<DataModel>": { "added": 123, "updated": 123, "deleted": 123 } },
    "syncType": "INITIAL" | "INCREMENTAL",
    "queryTimeStamp": "<timestamp>", // Null for initial sync runs.
}

Webhooks with non-2xx responses are retried with exponential backoff.

Before using webhooks in production, verify their origin (step-by-step guide).

Fetch the latest data

Upon receiving a webhook notification, the time cursor queryTimeStamp from the webhook body is used to fetch only the updated data.

Fetch records using the backend SDK (reference) or API (reference).

cURL (standard endpoint)

curl -G https://api.nango.dev/records \
  --header 'Authorization: Bearer <ENVIRONMENT-SECRET-KEY>' \
  --header 'Connection-Id: <string>' \
  --header 'Provider-Config-Key: <string>' \
  --data-urlencode 'model=<string>'  # The model of the records to fetch.
  --data-urlencode 'delta=<queryTimeStamp-from-webhook>' \  # Time cursor to only fetch the updated data.
  --data-urlencode 'limit=<number>' \  # Number of records returned (default: 100).
  --data-urlencode 'cursor=<string>' \  # For pagination: use the "next_cursor" property in the previous page's response.
  

Node SDK

import { Nango }  from '@nangohq/node';

const nango = new Nango({ secretKey: '<ENVIRONMENT-SECRET-KEY>' });

const result = await nango.listRecords({
    providerConfigKey: '<string>',
    connectionId: '<string>',
    model: '<string>', //The model of the records to fetch.
    delta: '<queryTimeStamp-from-webhook>', // Time cursor to only fetch the updated data.
    limit: <number>, // Number of records returned (default: 100).
    cursor: '<string>' // For pagination: use the "next_cursor" property in the previous page's response.
});

If you consume the API (vs. the SDK), you can use the standard endpoint (above) or a unique generated endpoint described in the API Reference tab of your integration in the Nango UI.

This returns an array of records conforming to the specified data model. Each record contains useful metadata.

{
    records:
        [
            {
                id: 123,
                ..., // Fields as specified in the model you queried
                _nango_metadata: {
                    deleted_at: null,
                    last_action: 'ADDED',
                    first_seen_at: '2023-09-18T15:20:35.941305+00:00',
                    last_modified_at: '2023-09-18T15:20:35.941305+00:00'
                }
            },
            ...
        ],
    next_cursor: "Y3JlYXRlZF9hdF4yMDIzLTExLTE3VDExOjQ3OjE0LjQ0NyswMjowMHxpZF4xYTE2MTYwMS0yMzk5LTQ4MzYtYWFiMi1mNjk1ZWI2YTZhYzI"
}

Write back to APIs (2-way syncing)

Write back to APIs with actions (step-by-step guide) or proxy requests (step-by-step guide).

Troubleshoot errors & monitor

Navigate to the Activity tab to inspect potential errors & monitor sync executions.

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