> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useparagon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync API

> Learn how to use and implement Sync API in your app.

## Usage

### Base URL

The Base URL for Sync API and Permissions API is:

```
https://sync.useparagon.com
```

<Accordion title="For on-premise instances">
  On-prem instances will use a different base URL based on the instance hostname.

  ```js theme={null}
  https://ms-sync.[On-Prem Base URL]
  ```
</Accordion>

### Authorization

The Sync API and Permissions API authorize with a [Paragon User Token](/getting-started/installing-the-connect-sdk#setup). Add this token to the Authorization header of your requests to the Sync API or Permissions API:

```
Authorization: Bearer {user_token}
```

For testing purposes, you can use our [Hosted Demo Environment](/demo) to generate and copy a Paragon User Token in your browser that you can use with Managed Sync.

**Required audience claim in token**

Ensure that your Paragon User Token includes an `aud` claim with your Paragon instance hostname and Project ID. While not required for other Paragon APIs, the `aud` claim is required for Managed Sync.

If you are using your existing Paragon User Token, update your JWT generation code to include the `aud` claim with your Paragon instance hostname and Project ID.

```json JWT Payload highlight={3} theme={null}
{
    "sub": "your-customer-id",
    "aud": "useparagon.com/{your-project-id}",
    "exp": 1752000000,
    "iat": 1751000000
}
```

<Tip>
  See code examples of encoding your JWT using your project's Signing Key in the [Connect SDK](/getting-started/installing-the-connect-sdk) documentation.
</Tip>

### Multi-Account Authorization

Managed Sync supports [Multi-Account Authorization](/apis/api-reference/multi-account-authorization). If a user has connected multiple accounts of the same integration type, you can specify which account to use when [enabling a sync](/managed-sync/api/enable-a-sync) by providing the `credentialId` parameter.

You can retrieve the list of connected credentials from the `allCredentials` array returned by the [/sdk/me](/apis/api-reference/multi-account-authorization#getuser) endpoint.

<Info>
  If `credentialId` is not specified and the user has multiple connected accounts for the same integration, the default credential (the oldest active credential) will be used.
</Info>

## Sync Lifecycle

After you [Enable a Sync](/managed-sync/api/enable-a-sync) for one of your users, Syncs run through the following lifecycle:

* **Initial sync**: When the sync is first enabled, Paragon will pull all data from the integration (limited by any sync-specific filters) and index the records for later retrieval and change detection.
  * You will receive a `sync_complete` [webhook](/managed-sync/webhooks) when the initial sync is complete.
  * The Sync status will have an `IDLE` status and a `lastSyncedAt` timestamp when the initial sync is complete.
* **Incremental syncs**: After the initial sync, Paragon will check periodically for changes to the data.
  * When records are created or updated, you will receive `record_created` or `record_updated` webhook events with metadata about the affected records.
  * The default frequency of incremental syncs is every minute. You can [configure this](#configuring-sync-frequency) per-sync with `incrementalAccumulatorFrequency`.
* **Periodic full sync**: Every 24 hours, Paragon will perform a full refresh of your users' data to detect any content drift or deletions that are not visible by incremental syncs.
  * After a periodic full sync runs, you may receive a batch of `record_deleted` webhook events for content that is no longer accessible by the Sync (meaning that the record was deleted or unshared from the connecting account).
  * The default frequency is every 24 hours. This can be configured down to 3 hours in [on-prem environments](/on-premise/hosting-paragon-on-premise) of Paragon.
  * The Sync status will have a `lastPeriodicFullSyncedAt` timestamp in `summary` once the first periodic full sync completes, separate from `lastSyncedAt`.

You can monitor these lifecycle phases in [Event Logs](/managed-sync/monitoring). Managed Sync emits logs when initial syncs, incremental syncs, and periodic full syncs start, complete, retry after recoverable warnings, or enter an errored state.

## Implementing Sync API

To implement Sync API in a production context, your application will need to handle initial and incremental sync phases, as illustrated below:

```mermaid theme={null}
sequenceDiagram
    participant App as Your Application
    participant Paragon as Paragon
    participant Integration as Integration

    %% Initial Sync
    App->>Paragon: Enable sync for user
    Paragon->>Integration: Pull all data (Initial Sync)
    Integration-->>Paragon: Index and normalize records
    Paragon-->>App: sync_complete webhook
    App->>Paragon: Paginate & pull records

    %% Incremental Syncs
    loop Incremental Sync
        Paragon->>Integration: Check for data changes
        Integration-->>Paragon: Return new/updated records
        Paragon->>Paragon: Detect changes
        Paragon-->>App: record_created / record_updated webhook
        App->>Paragon: Pull new/updated records
    end
```

**Initial sync:**

1. Enable the sync for a user.
2. Poll the Sync API to check on the status of the sync or wait for a `sync_complete` webhook.
3. Paginate through the records in the sync and pull them into your database or RAG pipeline.

**Incremental syncs:**

To handle ongoing updates, you can either:

* Poll the Sync API for new or updated records, using the `cursor` property to get records synced after the last record you pulled.
* Wait for `record_created` and `record_updated` webhooks to trigger when new or updated records are available.

## Configuring Sync Frequency

You can override the default frequency of the incremental sync when you [Enable a Sync](/managed-sync/api/enable-a-sync) or [Update an Existing Sync](/managed-sync/api/update-sync), using `incrementalAccumulatorFrequency`. This property determines how often Paragon will check for new or updated records from the integration.

Use a lower incremental frequency (longer time value) when freshness is less important than reducing API calls to the underlying integration.

Accepted values:

| Value | Description            |
| ----- | ---------------------- |
| `1m`  | Every minute (default) |
| `5m`  | Every 5 minutes        |
| `10m` | Every 10 minutes       |
| `30m` | Every 30 minutes       |
| `1h`  | Every hour             |
| `3h`  | Every 3 hours          |
| `6h`  | Every 6 hours          |
| `24h` | Every 24 hours         |

```bash Example: Enable a Sync with a 5-minute incremental sync frequency theme={null}
curl -X POST https://sync.useparagon.com/api/syncs \
  -H "Authorization: Bearer $PARAGON_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integration": "googledrive",
    "pipeline": "files",
    "incrementalAccumulatorFrequency": "5m"
  }'
```

You can change the incremental sync frequency at any time using [Update a Sync](/managed-sync/api/update-sync).