Clever Secure Sync Quickstart Guide

❗️

Clever Complete Agreement Required

This feature is included with a Clever Complete subscription. Sign up here or email your Application Success Manager to learn more.

Table of Contents

Overview
Steps to Getting Started with Clever Secure Sync
Steps to Getting a Clever Secure Sync Integration Running

---

Clever Secure Sync

Welcome to the Clever Secure Sync Quickstart Guide! Clever Secure Sync is Clever’s rostering API, allowing your application to securely read district data (students, teachers, sections, schools, and enrollments) in a standardized format.

This guide will walk you through setting up a sandbox, obtaining an access token, and making your first API calls.

For more details on the process, see our additional Clever Secure Sync guides in the left side menu.

---

Steps to Getting Started with Clever Secure Sync:

Prerequisites

Before you begin, ensure you have:

• A Clever Developer Account: Sign up at apps.clever.com/signup
• A Sandbox District: When you create an app, Clever automatically provisions a sandbox district populated with synthetic, Clever-compliant data for testing.

---

Steps to Getting a Clever Secure Sync Integration Running:

Step 1: Get Your Sandbox API Token

To interact with the Clever API, you need an access token. While production environments use an OAuth 2.0 flow or district-specific bearer tokens, the fastest way to start testing is by grabbing your Sandbox District Token.

1. Log in to your Clever App Dashboard.
   • In the left sidebar, navigate to Data Sources > Sandbox District.
2. Under the API Token section, copy the Bearer Token. This token grants you read access to your sandbox district's data.

Step 2: Make Your First API Call

Clever’s Data API is a RESTful interface. Let’s verify your token works by fetching the basic details of your sandbox district.

We will use the /v3.0/districts endpoint.

Bash  
curl -X GET "<https://api.clever.com/v3.0/districts">  
     -H "Authorization: Bearer \<YOUR_SANDBOX_TOKEN>"  
Expected JSON Response:

JSON  
{  
  "data": [  
    {  
      "data": {  
        "id": "5f3e4b1c...",  
        "name": "Clever Demo District",  
        "state": "running"  
      }  
    }  
  ]  
}

Step 3: Explore the Core Endpoints

Clever Secure Sync normalizes complex Student Information System (SIS) data into a clean, relational structure. The core endpoints you will interact with are:

📘

Fetching Users

To get a list of students, you can query the /users endpoint and filter by role

Bash  
curl -X GET "<https://api.clever.com/v3.0/users?role=student">  
     -H "Authorization: Bearer \<YOUR_SANDBOX_TOKEN>"

Step 4: Handle Pagination

Clever limits API responses to 100 records per page. To ingest a full district's data, you must follow the links object provided at the bottom of the API response.

If a rel: "next" link is present, use that exact URI to fetch the next page of data.

Example Pagination Link:

JSON  
"links": [  
  {  
    "rel": "next",  
    "uri": "/v3.0/users?starting_after=5f3e4b1c..."  
  }  
]

❗️

URI matters!

Always use the exact URI provided in the links array rather than constructing pagination queries manually.

Step 5: Keep Data Up to Date (Events)

Once you have performed an initial full sync (downloading all schools, users, and sections), you need to keep your database in sync with Clever.

Instead of re-downloading everything, you have the option to use the Events API (/v3.0/events). Events are chronological records of every creation, update, or deletion that occurs in a district.

1. Query /v3.0/events.
2. Process the changes (e.g., users.created, sections.updated, enrollments.deleted).
3. Save the ID of the last event you successfully processed.
4. On your next sync, query /v3.0/events?starting_after=<LAST_EVENT_ID> to get only new changes.