Examples

import { createSync } from 'nango';

const githubIssueDemoSchema = z.object({ ... });
type GithubIssueDemo = z.infer<typeof githubIssueDemoSchema>;

export default createSync({
  description: `Fetches the Github issues from all a user's repositories.`,
  version: '1.0.0',
  endpoints: [{ method: 'GET', path: '/example/github/issues', group: 'Issues' }],
  frequency: 'every hour',
  autoStart: true,
  syncType: 'full',

  metadata: z.void(),
  models: {
    GithubIssueDemo: githubIssueDemoSchema
  },

  exec: async (nango) => {
    // Fetch issues from GitHub.
    const res = await nango.get({
        endpoint: '/repos/NangoHQ/interactive-demo/issues?labels=demo&sort=created&direction=asc'
    });

    // Map issues to your preferred schema.
    const issues: GithubIssueDemo[] = res.data.map(({ id, title, html_url }: any) => {
        return { id, title, url: html_url };
    });

    // Persist issues to the Nango cache.
    await nango.batchSave(issues, 'GithubIssueDemo');

    // Delete records that don't exist anymore
    await nango.deleteRecordsFromPreviousExecutions('GithubIssueDemo')
  },
});

Read more about integration scripts to understand what role they play in Nango.

Configuration

`createSync`

description

string

required

The description of the sync.

endpoints

object[]

required

The endpoints of the sync. You can call this endpoint to fetch records synced by the sync. You need one endpoint per model.

endpoints: [{ method: 'GET', path: '/github/issues' }],

Which you can then call like this:

const res = await fetch('https://api.nango.dev/github/issues');

exec

function

required

The function that will be called when the sync is triggered.

frequency

string

required

The frequency of the sync.

frequency: 'every 1 minute',
frequency: 'every hour',
frequency: 'every 2 days'
frequency: 'every 3 week'

models

object

required

The models that will be synced by this script. You need one endpoint per model.

models: {
    GithubIssue: z.object({
        id: z.string(),
    }),
},

syncType

'full' | 'incremental'

required

The type of the sync.

autoStart

boolean

If true, automatically runs the sync when a new connection is created. Otherwise, it needs to be triggered via the API or Nango UI.

metadata

object

default:"z.void()"

The connection’s metadata of the action.

metadata: z.object({
    userId: z.string(),
});

onWebhook

function

The function that will be called when a webhook is received.

scopes

string[]

The integration’s scopes required by the action. This field is for documentation purposes only and currently not enforced by Nango.

scopes: ['read:user', 'write:user'],

trackDeletes

boolean

deprecated

[DEPRECATED] Instead use await nango.deleteRecordsFromPreviousExecutions('modelName') inside the sync exec function.When trackDeletes is set to true, Nango automatically detects deleted records during full syncs only and marks them as deleted in each record’s metadata (soft delete). These records remain stored in the cache.When set to false, Nango does not mark missing records as deleted, even if they weren’t returned in the latest full sync—they simply remain in the cache unchanged.Defaults to false.

version

string

The version of the sync. Use it to track changes to the sync inside Nango’s UI.

webhookSubscriptions

string[]

default:"undefined"

The webhook subscriptions of the sync. Specify the types of webhooks the method onWebhook will handle. If a webhook type is not on the list, it will not be handled.

webhookSubscriptions: ['*'],

`createAction`

description

string

required

The description of the sync.

endpoint

object

required

The endpoints of the sync. You can call this endpoint to fetch records synced by the sync. You need one endpoint per model.

endpoint: { method: 'POST', path: '/github/issues' },

exec

function

required

The function that will be called when the action is triggered.

input

object

required

The input required by the action when triggering it.

input: z.object({
    title: z.string(),
});

output

object

required

The output of the action.

output: z.object({
    issueId: z.string(),
});

version

string

The version of the sync. Use it to track changes to the sync inside Nango’s UI.

metadata

object

default:"z.void()"

The connection’s metadata of the action.

metadata: z.object({
    userId: z.string(),
});

scopes

string[]

The integration’s scopes required by the action. This field is for documentation purposes only and currently not enforced by Nango.

scopes: ['read:user', 'write:user'],

`createOnEvent`

description

string

required

The description of the sync.

event

'post-connection-creation' | 'pre-connection-deletion' | 'validate-connection'

required

The event that will trigger this script.

exec

function

required

The function that will be called when the action is triggered.

version

string

The version of the onEvent script. Use it to track changes to the onEvent script inside Nango’s UI.

metadata

object

default:"z.void()"

The connection’s metadata of the script.

metadata: z.object({
    userId: z.string(),
});

HTTP requests

Makes an HTTP request inside an integration script:

import type { ProxyConfiguration } from 'nango';

const config: ProxyConfiguration = { endpoint: '/some-endpoint' };

await nango.get(config); // GET request
await nango.post(config); // POST request
await nango.put(config); // PUT request
await nango.patch(config); // PATCH request
await nango.delete(config); // DELETE request

Note that all HTTP requests benefit from automatic credential injection. Because scripts are executed in the context of a specific integration & connection, Nango can automatically retrieve & refresh the relevant API credentials.

Parameters

Show child attributes

config

object

required

Hide config

endpoint

string

required

The endpoint of the request.

headers

Record<string, string>

The headers of the request.

params

Record<string, string | number>

The query parameters of the request.

data

unknown

The body of the request.

retries

number

The number of retries in case of failure (with exponential back-off). Optional, default 0.

retryOn

number[]

Array of additional status codes to retry a request in addition to the 5xx, 429, ECONNRESET, ETIMEDOUT, and ECONNABORTED

baseUrlOverride

string

The API base URL. Can be omitted if the base URL is configured for this API in the providers.yaml.

decompress

boolean

Override the decompress option when making requests. Optional, defaults to false

responseType

The type of the response.

Response

Show child attributes

    {
        data: {}, // the response provided by the server
        status: 200, // the HTTP status code
        headers: {}, // the HTTP headers
        config: {}, // the config provided for the request
        request: {} // the request that generated this response
    }

The response object is an Axios response.

HTTP request retries

To configure retries when HTTP requests fail, use the retries and retryOn parameters in your HTTP requests. The following will apply:

By default, retries are performed when:
- HTTP Status: >= 500, 429
- Network error: ECONNRESET, ETIMEDOUT, and ECONNABORTED.
- Pre-configured headers for providers in (providers.yaml).
Use the retryOn parameter to specify an array of additional status codes to retry on.
By default, no retries are performed: retries default to 0
The retry starting delay is 3000ms, the delay between attempts is multiplied by 2 each time (exponential backoff) and is capped at 10 minutes.

Logging

You can collect logs in integration scripts. This is particularly useful when:

developing, to debug your integration scripts
in production, to collect information about integration script executions & understand issues

Collect logs in integration scripts as follows:

await nango.log("This is a log.");

Logs can be viewed & searched in the Nango UI. We plan to make them exportable in the future as well.

Environment variables

Integration scripts sometimes need to access sensitive variables that should not be revealed directly in the code. For this, you can define environment variables in the Nango UI, in the Environment Settings tab. Then you can retrieve these environment variables from integration scripts with:

await nango.getEnvironmentVariables();

Parameters No parameters. Response

Show child attributes

[
    {
        "name": "MY_SECRET_KEY",
        "value": "SK_373892NSHFNCOWFO..."
    }
]

Trigger action

Integration scripts currently do not support importing files, which limits the ability to share code between integration scripts. As a temporary workaround, you can call action scripts from other integration scripts with:

await nango.triggerAction('<ACTION-NAME>', { 'custom_key1': 'custom_value1' });

Parameters

Show child attributes

actionName

string

required

The name of the action to trigger.

input

unkown

required

The necessary input for your action’s exec function.

Response

Show child attributes

{
    "your-properties": "The data returned by the action"
}

Paginate through API responses

Nango provides a helper to automatically paginate endpoint responses. Similar to HTTP requests, the nango.paginate() method takes in a ProxyConfiguration parameter. Use the paginate field to of the ProxyConfiguration to specify how the endpoint’s pagination work. Here’s an example for a Jira endpoint:

const config: ProxyConfiguration = {
    // https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-search-get
    endpoint: `/ex/jira/${cloud.cloudId}/rest/api/3/project/search`,
    params: {
        properties: properties
    },
    paginate: {
        type: 'offset',
        offset_name_in_request: 'startAt',
        response_path: 'values',
        limit_name_in_request: 'maxResults',
        limit: 50,
        on_page: async ({ nextPageParam, response }) => {
            await nango.log(`Next offset value = ${nextPageParam}`);
            await nango.log(`Fetched ${response.data.total} records`);
        },
    },
    headers: {
        'X-Atlassian-Token': 'no-check'
    },
    retries: 10
};

for await (const projects of nango.paginate<JiraProjectResponse>(config)) {
    const projectsToSave = toProjects(projects, cloud.baseUrl);
    await nango.batchSave(projectsToSave, 'Project');
}

As shown in the example above, use a for loop to iterate through the paginated results.

Nango has pre-configured the pagination settings for some popular APIs, so you don’t have to specify them in scripts.You can view the pre-configured pagination settings for all APIs in the providers.yaml file.Please note that some APIs have diverging pagination strategies per endpoint, so you might still need to override pre-configured pagination settings at times.

The pagination helper supports 3 types of pagination: cursor, link or offset with the following settings:

Show child attributes

config

object

required

Hide config

paginate

object

required

Hide paginate

limit_name_in_request

string

required

For all pagination types.The name of the parameter containing the number of items per page, in the request. Inserted in the query parameters for GET/DELETE, in the body for POST/PUT/PATCH.

limit

number

For all pagination types.The maximum number of items per page. If omitted, no limit will be sent to the external endpoint, relying on the endpoint’s default limit.

response_path

string

For all pagination types.The path of the field containing the results, in the response. If omitted or empty string, it defaults to the root. Use . for nested fields, e.g. "results.contacts".

type

'cursor' | 'link' | 'offset'

required

For all pagination types.The pagination strategy.

cursor_path_in_response

string

For cursor pagination only (required).The path of the field containing the cursor for the next page, in the response. Use . for nested fields, e.g. "pagination.cursor".

cursor_name_in_request

string

For cursor pagination only (required).The name of the parameter containing the cursor for the next page, in the request. Inserted in the query parameters for GET/DELETE, in the body for POST/PUT/PATCH.

link_rel_in_response_header

string

For link pagination (required unless link_path_in_response_body is specified).The header containing the link to the next page, in the response.

link_path_in_response_body

string

For link pagination (required unless link_rel_in_response_header is specified).The path of the field containing the link to the next page, in the response. Use . for nested fields, e.g. "pagination.link".

offset_name_in_request

string

For offset pagination only (required).The name of the parameter containing the offset for the next page, in the request. Inserted in the query parameters for GET/DELETE, in the body for POST/PUT/PATCH.

offset_start_value

number

For offset pagination only (optional).The initial offset. Defaults to 0, but some APIs start at 1.

offset_calculation_method

'per-page' | 'by-response-size'

For offset pagination only (optional).The offset calculation method. by-response-size (default) means the offset is incremented by the number of results. per-page means the offset is incremented by one for each page.

on_page

(paginationState: { nextPageParam?: string | number | undefined; response: AxiosResponse }) => Promise<void>

For all pagination types (optional).A callback function that is called after each page is fetched. Useful for logging or tracking pagination progress. The callback receives the next page parameter and the full Axios response object, which includes the response data, status, headers, and request configuration.

You can find details on the pagination types and logic in the code.

Get Integration

Returns the current integration information

await nango.getIntegration();

With credentials

await nango.getIntegration({ include: ['credentials'] });

Parameters See GET /integrations/{uniqueKey} query parameters: documentation Response See GET /integrations/{uniqueKey} response: documentation

Manage connection metadata

Get connection metadata

Returns the connection’s metadata.

await nango.getMetadata();

Better, you can specify the type of the metadata;

interface CustomMetadata {
    anyKey: Record<string, string>;
}
const myTypedMetadata = await nango.getMetadata<CustomMetadata>();

Parameters No parameters. Example Response

Show child attributes

{
    "custom_key1": "custom_value1"
}

Set connection metadata

Set custom metadata for the connection (overrides existing metadata).

await nango.setMetadata({ 'CUSTOM_KEY1': 'CUSTOM_VALUE1' });

Parameters

Show child attributes

metadata

Record<string, any>

required

The custom metadata to store in the connection.

Response Empty response.

Edit connection metadata

Edit custom metadata for the connection. Only overrides & adds specified properties, not the entire metadata.

await nango.updateMetadata({ 'CUSTOM_KEY1': 'CUSTOM_VALUE1' });

Parameters

Show child attributes

metadata

Record<string, any>

required

The custom metadata to store in the connection.

Response Empty response.

Get the connection credentials

Returns a specific connection with credentials.

await nango.getConnection();

The response content depends on the API authentication type (OAuth 2, OAuth 1, API key, Basic auth, etc.).

When you fetch the connection with this API endpoint, Nango will check if the access token has expired. If it has, it will refresh it.We recommend not caching tokens for longer than 5 minutes to ensure they are fresh.

Parameters

Show child attributes

forceRefresh

boolean

Defaults to false. If false, the token will only be refreshed if it expires within 15 minutes. If true, a token refresh attempt will happen on each request. This is only useful for testing and should not be done at high traffic.

refreshToken

boolean

Defaults to false. If false, the refresh token is not included in the response, otherwise it is. In production, it is not advised to return the refresh token, for security reasons, since only the access token is needed to sign requests.

Example Response

Show child attributes

{
    "id": 18393,
    "created_at": "2023-03-08T09:43:03.725Z",
    "updated_at": "2023-03-08T09:43:03.725Z",
    "provider_config_key": "github",
    "connection_id": "1",
    "credentials": {
        "type": "OAUTH2",
        "access_token": "gho_tsXLG73f....",
        "refresh_token": "gho_fjofu84u9....",
        "expires_at": "2024-03-08T09:43:03.725Z",
        "raw": { // Raw token response from the OAuth provider: Contents vary!
            "access_token": "gho_tsXLG73f....",
            "refresh_token": "gho_fjofu84u9....",
            "token_type": "bearer",
            "scope": "public_repo,user"
        }
    },
    "connection_config": {
        "subdomain": "myshop",
        "realmId": "XXXXX",
        "instance_id": "YYYYYYY"
    },
    "account_id": 0,
    "metadata": {
        "myProperty": "yes",
        "filter": "closed=true"
    }
}

Sync-specific helper methods

Sync scripts persist data updates to the Nango cache, which your app later fetches (cf. step-by-step guide).

Save records

Upserts records to the Nango cache (i.e. create new records, update existing ones). Each record needs to contain a unique id field used to dedupe records.

const githubIssues: GitHubIssue[] = ...; // Fetch issues from GitHub API.

await nango.batchSave(githubIssues, 'GitHubIssue');

Parameters

Show child attributes

recordList

Model[]

required

The list of records to persist.

modelType

string

required

The model type of the records to persist.

Delete records

Marks records as deleted in the Nango cache. Deleted records are still returned when you fetch them, but they are marked as deleted in the record’s metadata (i.e. soft delete). To implement deletion detection in your syncs, follow this guide. The only field that needs to be present in each record when calling batchDelete is the unique id; the other fields are ignored.

const githubIssuesToDelete: { id: string }[] = ...; // Fetch issues to delete from GitHub API.

await nango.batchDelete(githubIssuesToDelete, 'GitHubIssue');

Parameters

Show child attributes

recordList

{ id: string }[]

required

The list of records to delete.

modelType

string

required

The model type of the records to delete.

Detect deletions automatically

Automatically detects and marks records as deleted by comparing the current sync execution with the previous one.

await nango.deleteRecordsFromPreviousExecutions('ModelName');

This function should be called at the end of your sync execution, after all records have been saved with batchSave. Nango will compare the records saved in the current execution with those from the previous execution and mark any missing records as deleted. Parameters

Show child attributes

modelType

string

required

The model type to detect deletions for.

Important considerations:

Only use within syncs that fetch the complete dataset
Call this function only after successfully saving all records
If your sync fails or doesn’t fetch the complete dataset, avoid calling this function as it may cause false deletions
Records are soft deleted (marked with _metadata.deleted = true) and remain in the cache

For more details on deletion detection strategies, see the detecting deletes guide.

Update records

Updates records in the Nango cache by merging the given data into the existing record. The id field is required in each record and used to determine what existing record to merge into. batchUpdate is primarily useful in webhook sync scripts, where you receive partial updates from a webhook and want to merge them into the existing records. The merge algorithm used is a deep merge. Nested objects are merged recursively, while arrays always use the new value for the array. Any fields not present in the update record are left unchanged.

// Create partial GitHub Issue update records with only id and state.
const githubIssues: Pick<GitHubIssue, "id" | "state">[] = ...;

await nango.batchUpdate(githubIssues, 'GitHubIssue');

Take special care when using batchUpdate with records containing arrays. The merge algorithm does not attempt to merge arrays, but rather always uses the value of the new array.

// given a an existing record:
// { id: '1', tags: [{id: 12, name: 'Dev'}, {id: 13, name: "QA"}] }
const updates: Pick<Issue, "id" | "tags">[] = [
    { id: '1', tags: [{id: 14, name: 'UX'}] }
];

// after the update, the record will be:
// { id: '1', tags: [{id: 14, name: "UX"}] }
await nango.batchUpdate(updates, 'Issue');

Parameters

Show child attributes

recordList

Pick<Model, 'id' | ...>[]

required

The list of partial records to persist.

modelType

string

required

The model type of the records to persist.

Get records

Fetches records from the Nango cache by ID. Returns a Map where the keys are the requested IDs, and the values are the corresponding records. Any records that are not found will simply be absent from the map. Example usage:

const records = await nango.getRecordsById<string, Issue>(['1', '2', '3'], 'Issue');

if (records.has('1')) {
    const record = records.get('1');
    await nango.log(record.title);
} else {
    await nango.log('Record with id 1 not found.');
}

Fetching records by ID is useful when you need to update specific records with a more granular approach than nango.batchUpdate(), which performs a deep merge. Note that nango.batchUpdate() is more performant than using nango.getRecordsById(), followed by nango.batchSave().A common use case is when handling external webhooks, where only a partial update of a record is received from an API.

Variant

If you are using sync variants, you can access the current variant name via the nango.variant property.

export default createSync({
  exec: async (nango) => {
    await nango.log(`Running sync with variant: ${nango.variant}`);

    // Customize sync behavior based on variant
    const res = await nango.get({
        endpoint: `/spreadsheet/${nango.variant}`
    });

    // Rest of sync implementation...
  },
});

Action-specific helper methods

`ActionError`

You can use ActionError in an action script to return a descriptive error to your app when needed:


export default createAction({
  exec: async (nango) => {
    // Something went wrong...

    throw new ActionError({ any_key: 'any_value' });
  },
});

In this case, the response to the trigger action call will be:

{
  "error_type": "action_script_failure",
  "payload": {
    "any_key": "any_value"
  }
}

Relative imports in scripts

You can import relative files into your scripts to allow for code abstraction and to maintain DRY (Don’t Repeat Yourself) principles. This means you can reuse code across different scripts by importing it. The imported file must live in the nango-integrations directory and can be imported in the following way:

import { issueMapper } from '../mappers/issue-mappper';

export default createSync({
  exec: async (nango) => {
    // Fetch issues from GitHub.
    const res = await nango.get({
        endpoint: '/repos/NangoHQ/interactive-demo/issues?labels=demo&sort=created&direction=asc'
    });

    // Persist issues to the Nango cache.
    await nango.batchSave(issueMapper(res.data), 'GithubIssueDemo');
  },
});

Note that you cannot import third-party modules at this time. Additionally, if there is a compilation error in an imported file, the entry point file will also fail to compile.

Pre-included Dependencies

Some libraries are pre-included for usage in scripts:

Please reach out in the community if you would like to request additional ones.

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

Reference

Use Integrations - Reference

Build Integrations - Reference

Integration scripts

Examples

Configuration

`createSync`

`createAction`

`createOnEvent`

HTTP requests

HTTP request retries

Logging

Environment variables

Trigger action

Paginate through API responses

Get Integration

Manage connection metadata

Get connection metadata

Set connection metadata

Edit connection metadata

Get the connection credentials

Sync-specific helper methods

Save records

Delete records

Detect deletions automatically

Update records

Get records

Variant

Action-specific helper methods

`ActionError`

Relative imports in scripts

Pre-included Dependencies

Reference

Use Integrations - Reference

Build Integrations - Reference

​Examples

​Configuration

​createSync

​createAction

​createOnEvent

​HTTP requests

​HTTP request retries

​Logging

​Environment variables

​Trigger action

​Paginate through API responses

​Get Integration

​Manage connection metadata

​Get connection metadata

​Set connection metadata

​Edit connection metadata

​Get the connection credentials

​Sync-specific helper methods

​Save records

​Delete records

​Detect deletions automatically

​Update records

​Get records

​Variant

​Action-specific helper methods

​ActionError

​Relative imports in scripts

​Pre-included Dependencies

Examples

Configuration

`createSync`

`createAction`

`createOnEvent`

HTTP requests

HTTP request retries

Logging

Environment variables

Trigger action

Paginate through API responses

Get Integration

Manage connection metadata

Get connection metadata

Set connection metadata

Edit connection metadata

Get the connection credentials

Sync-specific helper methods

Save records

Delete records

Detect deletions automatically

Update records

Get records

Variant

Action-specific helper methods

`ActionError`

Relative imports in scripts

Pre-included Dependencies