> ## 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-%3E-paragonuser) 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_completed` [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 frequency of incremental syncs is every minute.
* **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).

## 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_completed 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_completed` 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.