Build a District Roster Sync with Events

Build a server-side Secure Sync integration that imports a district’s roster and keeps it current with the Events API.

Prerequisites

Configure Clever Secure Sync for your application.
Choose an account-matching strategy before onboarding districts.
Enable Events in Settings > Integrations > Enable events if you will use delta syncing.

1. Store district access

Store the Clever district ID, the district-app token, or both. You can retrieve the active token programmatically with:

GET https://clever.com/oauth/tokens?district=<id>

Storing the district ID lets your app retrieve the active token after a token rotation.

2. Match the district and existing records

Match a new Clever connection to the correct account in your product. Supported approaches include MDR number matching, SSO-based matching, a Log in with Clever flow with state, manual selection, or Matchmaker.

Review uncertain matches before applying them. Store Clever IDs after matching so future updates remain connected to the right records.

3. Perform an initial full sync

Use the Data API to retrieve the data your product needs. Handle multi-role users, multi-school enrollments, non-unique section names, and missing optional fields.

Sync at least daily and provide an on-demand sync path for urgent district updates.

4. Start Events-based updates

Save the current event ID, then complete the initial non-Events sync:

GET https://api.clever.com/v3.0/events?ending_before=last&limit=1

Retrieve later events with:

GET https://api.clever.com/v3.0/events?starting_after=<event_id>

Process events in the order Clever returns them. Make processing idempotent because the same event can be processed more than once.

5. Retain full-resync capability

Events are available for 30 days. Keep a full Data API resync available for recovery and rollover periods, when a full sync can be more efficient than replaying events.