How sync works
The proxy model
The mobile app never talks to the directory provider directly. Every sync goes through RingSync's API routes, which authenticate server-side and stream results to the device:
- The app creates a sync job.
- The app loops, fetching one page of users at a time using a cursor (a delta link or a next link).
- RingSync authenticates server-side (Graph
client_credentials, or a Google service account / OAuth token), calls the directory, and streams the page. - The app applies each page to the native contacts, tagged to that directory.
- The app reports per-contact outcomes for logging and saves the new cursor.
Because RingSync only proxies pages, no contact is ever stored on the server.
Triggering
- Manual (v1) — the user taps a directory card in the mobile app to start a sync.
- Scheduled (v2) — a configurable scheduled task from the back office.
- Webhook (v2, out of initial scope) — Microsoft Graph change notifications.
Incremental sync (delta link)
- First sync — no delta link exists, so RingSync runs a full sync.
- Subsequent syncs — the delta link is stored on the device and backed up server-side, so only changes are fetched.
- Group-scoped sync — the provider does not support delta over group queries; RingSync does a full fetch and synthesizes removals for users who left the scope.
- Scope change (all ↔ groups) — the delta link is reset automatically, forcing a full sync.
Google has no delta
Google Workspace's Admin SDK Directory API has no delta. Google syncs are always full fetches; the device diffs against its local per-directory map to detect removals.
Deletion propagation and selective wipe
- When a user is deleted or disabled in the directory, they are returned as removed (or with
accountEnabled = false); the device removes the matching native contact and logs the action. - When a user's access is withdrawn — they are unassigned in Entra ID or taken out of the Google Workspace access scope, which the background pull detects within 15 minutes — RingSync sends a data-only push notification to the device. The device then purges only the contacts tagged for that directory — other synced directories stay intact.
Selective by directory
Each native contact is tagged to a directory via a local map. This is what makes per-directory wipe possible without touching contacts from other directories.
Pagination and limits
- The directory returns at most 999 users per page; RingSync streams one page at a time and the device paginates with the cursor.
- Each server-side directory call has a 60-second timeout.
- The device caps a sync at 200 pages as a safety guard against a corrupted cursor.
Key edge cases
| Case | Behavior |
|---|---|
| First run (no delta link) | Automatic full sync. |
| User removed in the directory | Background pull disables the grant, pushes a wipe (if enabled), removes the user's directory link. |
| User assigned but pull hasn't run yet | The mobile login inserts a grant on the fly (the directory has already filtered access). |
| Photo unavailable | Contact created without a photo, no error. |
| Empty field in the directory | Field skipped, existing value not overwritten. |
| Network loss during sync | Job marked as error, retry manually. |
| Guest user (Entra) | Always ignored. |
| More than 10,000 users | Delta pagination handled by the proxy, 200-page device cap. |
| Scope change (all ↔ groups) | Delta link reset to force a full sync. |
Was this page useful?
Report what is missing →