### v3 Contacts API Example

Source: https://dev.clever.com/docs/contacts-migrations-concept-guide

An example of the response structure for contacts in the v3 API, demonstrating distinct relationship types for each associated student.

```APIDOC
## GET /v3.0/users/{id}

### Description
Retrieves user (contact) information using the v3 API, including detailed student relationships.

### Method
GET

### Endpoint
/v3.0/users/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the user (contact).

### Response
#### Success Response (200)
- **data** (object) - Contains the user details.
  - **created** (string) - Timestamp of when the user was created.
  - **district** (string) - The ID of the district the user belongs to.
  - **email** (string) - The user's email address.
  - **last_modified** (string) - Timestamp of the last modification.
  - **name** (object) - The name of the user.
    - **last** (string) - The last name of the user.
  - **id** (string) - The unique identifier for the user.
  - **roles** (object) - An object containing role-specific information.
    - **contact** (object) - Contact-specific details.
      - **phone** (string) - The contact's phone number.
      - **phone_type** (string) - The type of phone number.
      - **sis_id** (string) - The SIS ID of the contact.
      - **student_relationships** (array) - An array of objects, each detailing a relationship with a specific student.
        - **relationship** (string) - The specific relationship type (e.g., "Parent", "Aunt/Uncle").
        - **student** (string) - The ID of the associated student.
        - **type** (string) - The general category of the relationship (e.g., "Family").
      - **legacy_id** (string) - The legacy ID from the v2 API.
- **links** (array) - An array of links related to the user.

#### Response Example
```json
{
    "data": {
        "created": "2024-12-02T18:25:30.470Z",
        "district": "62817af12d430f5d54001f99",
        "email": "salman_herzog@example.com",
        "last_modified": "2024-12-02T18:39:37.832Z",
        "name": {
            "last": "Salman Herzog"
        },
        "id": "674dfb9421346c4b2f36130d",
        "roles": {
            "contact": {
                "phone": "(688) 145-6088",
                "phone_type": "Other",
                "sis_id": "603",
                "student_relationships": [
                    {
                        "relationship": "Parent",
                        "student": "62817c88dc4dc002ea40b502",
                        "type": "Parent/Guardian"
                    },
                    {
                        "relationship": "Aunt/Uncle",
                        "student": "674dfb9421346c4b2f3512f5",
                        "type": "Family"
                    }
                ],
                "legacy_id": "674dfb9421346c4b2f3612ff"
            }
        }
    },
    "links": [
        {
            "rel": "self",
            "uri": "/v3.0/users/674dfb9421346c4b2f36130d"
        },
        {
            "rel": "district",
            "uri": "/v3.0/users/674dfb9421346c4b2f36130d/district"
        },
        {
            "rel": "sections",
            "uri": "/v3.0/users/674dfb9421346c4b2f36130d/sections"
        },
        {
            "rel": "schools",
            "uri": "/v3.0/users/674dfb9421346c4b2f36130d/schools"
        }
    ]
}
```
```

--------------------------------

### Fetch Attendance Records with Pagination

Source: https://dev.clever.com/docs/attendance-data-pagination

An example HTTP GET request demonstrating how to use the starting_after parameter to retrieve the next page of attendance records for a specific school and date.

```http
GET /v3.1/attendance/schools/{school_id}?date_range_start=2025-04-01&date_range_end=2025-04-01&limit=100&starting_after=MjAyNS0wNC0wMV82N2Y0MjE2OTJlZGEwZTNmYTE4ODBlNTNfNjdmNDIxNjkyZWRhMGUzZmExODgwZThkXzY3ZjQyMTY5MmVkYTBlM2ZhMTg4MGU0Zg==
```

--------------------------------

### Example Response from Clever API /userinfo Endpoint (JSON)

Source: https://dev.clever.com/docs/the-userinfo-endpoint

This is an example JSON response from the Clever API /userinfo endpoint. It contains various user-specific details such as user ID, type, district information, name, and email. Note that the 'schools' field is an empty array in this example.

```json
{
    "sub": "64f0e2926b100a053fc08e14",
    "user_id": "64f0e2876b100a053fbf9c6e",
    "multi_role_user_id": "64f0e2926b100a053fc08e14",
    "user_type": "teacher",
    "district_id": "64ef5e6c8d6b17762d094e48",
    "district": "64ef5e6c8d6b17762d094e48",
    "email": "john-paul.johnson.048393@example.com",
    "name": {
        "first": "John-Paul",
        "last": "Johnson",
        "middle": ""
    },
    "schools": [],
    "given_name": "John-Paul",
    "family_name": "Johnson",
    "email_verified": false,
    "authorized_by": "district"
}
```

--------------------------------

### Cursor Key Structure Examples

Source: https://dev.clever.com/docs/attendance-data-pagination

Examples of the decoded composite key structure used within the pagination cursor, including standard format and the zero-padded placeholder format for missing identifiers.

```text
2025-04-01_67f421692eda0e3fa1880e53_67f421692eda0e3fa1880e8d_67f421692eda0e3fa1880e4f
```

```text
2025-04-01_67f421692eda0e3fa1880e53_000000000000000000000000_67f421692eda0e3fa1880e4f
```

--------------------------------

### v2 Contacts API Example

Source: https://dev.clever.com/docs/contacts-migrations-concept-guide

An example of the response structure for contacts in the v2 API, showing a single relationship type for all associated students.

```APIDOC
## GET /v2.1/contacts/{id}

### Description
Retrieves contact information using the v2 API.

### Method
GET

### Endpoint
/v2.1/contacts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the contact.

### Response
#### Success Response (200)
- **data** (object) - Contains the contact details.
  - **phone** (string) - The contact's phone number.
  - **district** (string) - The ID of the district the contact belongs to.
  - **phone_type** (string) - The type of phone number.
  - **relationship** (string) - The relationship type to the student(s).
  - **sis_id** (string) - The SIS ID of the contact.
  - **email** (string) - The contact's email address.
  - **students** (array) - An array of student IDs associated with the contact.
  - **name** (string) - The name of the contact.
  - **type** (string) - The general type of contact.
  - **id** (string) - The unique identifier for the contact.
- **links** (array) - An array of links related to the contact.

#### Response Example
```json
{
    "data": {
        "phone": "(688) 145-6088",
        "district": "62817af12d430f5d54001f99",
        "phone_type": "Other",
        "relationship": "Parent",
        "sis_id": "603",
        "email": "salman_herzog@example.com",
        "students": [
            "62817c88dc4dc002ea40b502",
            "674dfb9421346c4b2f3612f5"
        ],
        "name": "Salman Herzog",
        "type": "Parent/Guardian",
        "id": "674dfb9421346c4b2f3612ff"
    },
    "links": [
        {
            "rel": "self",
            "uri": "/v2.1/contacts/674dfb9421346c4b2f3612ff"
        },
        {
            "rel": "district",
            "uri": "/v2.1/contacts/674dfb9421346c4b2f3612ff/district"
        },
        {
            "rel": "students",
            "uri": "/v2.1/contacts/674dfb9421346c4b2f3612ff/students"
        }
    ]
}
```
```

--------------------------------

### GET /v3.0/{resource}

Source: https://dev.clever.com/docs/paging-and-limits

General endpoint documentation for paginated resources within the Clever API.

```APIDOC
## GET /v3.0/{resource}

### Description
Retrieves a collection of resources with support for pagination and result limiting. Note: Pagination is only available when using district bearer tokens.

### Method
GET

### Endpoint
/v3.0/{resource}

### Parameters
#### Query Parameters
- **starting_after** (string) - Optional - The ID of the last item from the previous page to fetch the next set of results.
- **ending_before** (string) - Optional - The ID of the first item from the next page to fetch the previous set of results.
- **limit** (integer) - Optional - Number of results to return per page (default: 100, max: 10000).

### Request Example
GET /v3.0/users?limit=30

### Response
#### Success Response (200)
- **data** (array) - The list of requested resources.
- **links** (array) - Navigation links containing 'next', 'prev', and 'self' URIs for pagination.

#### Response Example
{
  "data": [...],
  "links": [
    {
      "rel": "next",
      "uri": "/v3.0/users?starting_after=530e5961049e75a9262cffe4"
    }
  ]
}
```

--------------------------------

### Constructing Basic Authentication Header

Source: https://dev.clever.com/docs/classroom-with-oauth

Demonstrates how to generate the Authorization header by Base64 encoding the client credentials.

```pseudocode
basic_auth_header = "Authorization: Basic " + Base64.encode(client_id + ":" + client_secret)
```

--------------------------------

### Retrieve User Data with Access Token

Source: https://dev.clever.com/docs/getting-started-with-clever-sso

Fetches user profile information by sending a GET request to the Clever API /me endpoint. The request must include the access token in the Authorization Bearer header.

```cURL
curl --request GET \
     --url https://api.clever.com/v3.0/me \
     --header 'Authorization: Bearer ENTER_TOKEN_HERE' \
     --header 'accept: application/json'
```

--------------------------------

### Constructing Authorization Header for Clever API (Example)

Source: https://dev.clever.com/docs/classroom-with-oauth

Demonstrates how to construct the Authorization header for making authenticated requests to the Clever API using a bearer token. This header is crucial for identifying the user and their associated permissions.

```http
GET https://api.clever.com/some_clever_resource
Authorization: Bearer jsfUI2131da2f
```

--------------------------------

### Redeem Authorization Code for Access Token

Source: https://dev.clever.com/docs/getting-started-with-clever-sso

Exchanges an authorization code for an OAuth 2.0 access token by sending a POST request to the Clever tokens endpoint. Requires a Basic Authorization header containing the base64-encoded client credentials.

```cURL
curl --request POST \
     --url https://clever.com/oauth/tokens \
     --header 'Authorization: Basic MDk1YjgyY2JiZDhjNjg3MTRkMWM6NGIzMzg0ODljZWI0YmVjMzYyNDYxYTdjOTZlM2FhNjA5ZWZmZjA0OQ==' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "code": "ENTER_CODE_HERE",
  "grant_type": "authorization_code",
  "redirect_uri": "https://localhost:3000"
}'
```

--------------------------------

### Submit Schoology attachments via PATCH request

Source: https://dev.clever.com/docs/submitting-schoology-submissions

A JSON payload example for the Clever LMS Connect PATCH request. It demonstrates how to submit a link by using the 'text' type, as Schoology does not support the 'link' attachment type.

```json
{
  "attachments": [
    {
      "type": "text",
      "text": "https://clever.com"
    }
  ]
}
```

--------------------------------

### Moodle: Handle Clever SSO with State Parameter

Source: https://dev.clever.com/docs/moodle-sso-integration-guide

This PHP code snippet modifies the /admin/oauth2callback.php file in Moodle to handle authentication requests initiated from the Clever Portal. It checks for a missing 'state' parameter, constructs a new SSO request URL including the 'state' parameter, and redirects the user to Clever for authentication. If the 'state' parameter is present, it processes the authorization code and redirects back to the appropriate Moodle URL.

```php
$state = optional_param('state', '', PARAM_RAW);
if ($state == '') {
    /*print_error('missing state');*/

    $stateparams['wantsurl'] = new moodle_url('/');
    $stateparams['sesskey'] = sesskey();
    $stateparams['id'] = $issuer->get('id');
//Include all relevant params for the new authentication request
    $params = array_merge(
        [
            'client_id' => $issuer->get('clientid'),
            'redirect_uri' => new moodle_url('/admin/oauth2callback.php'),
            'response_type' => 'code',
            'scope' => optional_param('scope', null, PARAM_RAW),
            'code' => optional_param('code', null, PARAM_RAW),
            'state' => new moodle_url('/auth/oauth2/login.php', $stateparams),
        ]
    );
 //Formulate a new SSO request URL with the necessary params
    $backtocleverurl = new moodle_url($clever_url, $params);
 
    error_log("*****************admincallback backtocleverurl redirect back to clever");
    error_log(print_r($backtocleverurl, true));
    redirect($backtocleverurl);
} else {
// The authorization code generated by the authorization server.
    $code = required_param('code', PARAM_RAW);
// The state parameter we've given (used in moodle as a redirect url).
    $state = required_param('state', PARAM_LOCALURL);
    error_log("admincallback state");
    error_log(print_r($state, true));

    $redirecturl = new moodle_url($state);
    $params = $redirecturl->params();

    if (isset($params['sesskey']) and confirm_sesskey($params['sesskey'])) {
        $redirecturl->param('oauth2code', $code);
        redirect($redirecturl);
    } else {
        print_error('invalidsesskey');
    }
}
```

--------------------------------

### Multi-Role User Example Response (Text)

Source: https://dev.clever.com/docs/best-practices-edge-cases

This JSON response illustrates the structure for a multi-role user in Clever's API. It shows how a user can have multiple roles (e.g., teacher, district_admin) associated with their account, each with a unique legacy ID.

```text
{
    "data": {
        "created": "2022-05-15T22:20:03.535Z",
        "district": "62817af12d430f5d54001f99",
        "email": "integrations+training@clever.com",
        "last_modified": "2024-07-10T16:22:11.422Z",
        "name": {
            "first": "PE",
            "last": "Bot"
        },
        "roles": {
            "teacher": {
                "schools": [],
                "legacy_id": "6298ef2e9e30ed3d9066e118"
            },
            "district_admin": {
                "legacy_id": "62817af1d65e86e415b6f68d"
            }
        },
        "id": "62817c88dc4dc002ea40b594"
    },
    "links": [
        {
            "rel": "self",
            "uri": "/v3.0/users/62817c88dc4dc002ea40b594"
        }
    ]
}
```

--------------------------------

### OAuth Flow

Source: https://dev.clever.com/docs/overview

Step-by-step guide for implementing the OAuth authorization code grant type for SSO with Clever.

```APIDOC
## OAuth Flow

### Description
This section outlines the authorization code grant type flow for Single Sign-On (SSO) with Clever.

### Steps
1.  **Initiate Login**: A user starts the login process.
2.  **Clever Redirect**: Clever redirects the user to your application's **redirect URI** with an **authorization code**. If the user is not authenticated, they will be prompted for credentials first.
3.  **Token Exchange**: Your application POSTs the **authorization code** to Clever's token endpoint along with appropriate credentials.
4.  **Access Token Response**: Clever responds with an **access token** to grant access to protected resources.
5.  **Access /me Endpoint**: Use the **access token** to call `https://api.clever.com/v3.0/me` to retrieve the resource owner's Clever ID. Ensure a version is specified in the endpoint call.
6.  **Access User Data**: With the **access token** and Clever ID, call `https://api.clever.com/v3.0/users/{id}` to get additional user information for authentication.
```

--------------------------------

### users.deleted Event Payload Example

Source: https://dev.clever.com/docs/events-api

An example JSON payload for a users.deleted event. This event is triggered when a user is removed from an SIS or unshared by a district, with the user type identifiable via the 'roles' node.

```json
{
	"data": {
		"created": "2021-11-30T17:09:15.000Z",
		"data": {
			"object": {
				"created": "2021-11-25T17:06:03.838Z",
				"district": "58da8a43cc70ab00017a1a87",
				"email": "wanell_schmeler@example.net",
				"id": "5fad6ba2b84acb058bf8dc22",
				"last_modified": "2021-11-25T17:06:03.838Z",
				"name": {
					"last": "Wanell Schmeler"
				},
				"roles": {
					"contact": {
						"legacy_id": "5f75fe4d64cf6b128cecda56",
						"phone": "",
						"phone_type": "Other",
						"relationship": "Other",
						"sis_id": "",
						"student_relationships": [],
						"students": [
							"58da8c65d7dc0ca0680006b6"
						],
						"type": "Family"
					}
				}
			}
		},
		"id": "61a65abb7d8210097c2d9046",
		"type": "users.deleted"
	},
	"uri": "/v3.0/events/61a65abb7d8210097c2d9046"
}
```

--------------------------------

### GET /oauth/authorize

Source: https://dev.clever.com/docs/il-implicit-grant

Initiates the OAuth 2.0 implicit grant flow by redirecting the user to the Clever authorization server.

```APIDOC
## GET /oauth/authorize

### Description
Redirects the user to Clever to authorize the application. Upon success, Clever redirects back to the provided redirect_uri with the access token in the URI fragment.

### Method
GET

### Endpoint
https://clever.com/oauth/authorize

### Parameters
#### Query Parameters
- **response_type** (string) - Required - Must be set to "token" for the implicit grant flow.
- **redirect_uri** (string) - Required - The URL to which Clever will redirect the user after authorization. Must match a registered URI.
- **client_id** (string) - Required - The unique identifier for your application.
- **state** (string) - Required - A random nonce value used to prevent CSRF attacks. This value is returned in the redirect fragment.

### Request Example
GET https://clever.com/oauth/authorize?response_type=token&redirect_uri=https%3A%2F%2Fflightschool.edu%2Foauth%2Fimplicit&client_id=anVpY2VqdWljZWp1aWNlCg&state=fb37f982-925b

### Response
#### Success Response (302)
- **Location** (header) - The user is redirected to the `redirect_uri` with the access token and state appended as a URI fragment (e.g., `https://flightschool.edu/oauth/implicit#access_token=...&state=...`).

#### Response Example
https://flightschool.edu/oauth/implicit#access_token=abc123token&token_type=bearer&state=fb37f982-925b
```

--------------------------------

### Install pyOpenSSL for Urllib3 in Python

Source: https://dev.clever.com/docs/updating-to-use-tls-12-on-connect-to-clever-api

To ensure Python 3.6 applications using the Urllib3 package can upgrade to TLS 1.2, install the pyOpenSSL package. This provides the necessary cryptographic support for newer TLS versions.

```python
python3 -m pip3 install pyOpenSSL
```

--------------------------------

### GET /teachers

Source: https://dev.clever.com/docs/users

Retrieves teacher information including district-provided identifiers and titles.

```APIDOC
## GET /teachers

### Description
Retrieves a list of teachers associated with the district, including their state and district-specific identifiers.

### Method
GET

### Endpoint
/teachers

### Parameters
#### Request Body
- **state_id** (string) - Required - State teacher identifier
- **teacher_number** (string) - Required - Teacher number provided by district
- **title** (string) - Required - Title provided by district

### Request Example
{
  "state_id": "ST12345",
  "teacher_number": "TCH-99",
  "title": "Math Teacher"
}

### Response
#### Success Response (200)
- **state_id** (string) - State teacher identifier
- **teacher_number** (string) - Teacher number provided by district
- **title** (string) - Title provided by district

#### Response Example
{
  "state_id": "ST12345",
  "teacher_number": "TCH-99",
  "title": "Math Teacher"
}
```

--------------------------------

### GET /v3.0/me

Source: https://dev.clever.com/docs/oauth-implementation

Retrieves information about the user associated with the provided access token.

```APIDOC
## GET /v3.0/me

### Description
Returns the user's Clever ID, district ID, and token type using the access token obtained from the authentication flow.

### Method
GET

### Endpoint
https://api.clever.com/v3.0/me

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer [access_token]

### Response
#### Success Response (200)
- **id** (string) - The unique Clever ID of the user.
- **district** (string) - The district ID associated with the user.
- **type** (string) - The type of user.
```

--------------------------------

### Query Teacher Accounts via API

Source: https://dev.clever.com/docs/api-v3-upgrade-guide

Demonstrates the transition from role-specific v2.1 endpoints to the consolidated v3.1 /users endpoint for querying teacher accounts.

```v2.1
GET /v2.1/teachers
Authorization: Bearer {district_app_token}
```

```v3.1
GET /v3.1/users?role=teacher
Authorization: Bearer {district_app_token}
```

--------------------------------

### GET /districts/{district_id}

Source: https://dev.clever.com/docs/api-reference

Retrieves the LMS integration status for a specific district.

```APIDOC
## GET https://api.clever.com/v3.1/districts/<district_id>

### Description
Includes LMS integration information in the District object.

### Method
GET

### Endpoint
https://api.clever.com/v3.1/districts/<district_id>

### Parameters
#### Path Parameters
- **district_id** (string, ObjectID) - Required - The unique identifier for the district.

### Response
#### Success Response (200)
- **lms_state** (string) - The current status of the LMS integration. Allowed values: ["success", "matching_in_progress", "disconnected", "error", ""]
```

--------------------------------

### Data Matching Strategies

Source: https://dev.clever.com/docs/onboarding

Guidelines for matching internal application records with Clever data entities.

```APIDOC
## Data Matching Strategies

### Description
Strategies for mapping internal database records to Clever IDs. Matching should be performed on unique, persistent fields.

### Students Matching Fields (Priority Order)
1. **sis_id / student_number** (Primary ID)
2. **state_id** (Secondary ID)
3. **dob** (Date of Birth)
4. **email**
5. **name**

### Teachers Matching Fields (Priority Order)
1. **email**
2. **sis_id / teacher_number** (Primary ID)
3. **state_id** (Secondary ID)
4. **name**

### Staff Matching Fields (Priority Order)
1. **email**
2. **staff_id**
3. **name**

### Schools Matching
- Use **MDR Number** or **NCES ID** where available for high-confidence matching.
```

--------------------------------

### GET /schools/{id}/sections

Source: https://dev.clever.com/docs/schools

Retrieves a list of sections associated with a specific school.

```APIDOC
## GET /schools/{id}/sections

### Description
Retrieves all sections associated with the specified school ID.

### Method
GET

### Endpoint
/schools/{id}/sections

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique Clever ID of the school.

### Response
#### Success Response (200)
- **data** (array) - List of section objects associated with the school.

#### Response Example
{
  "data": []
}
```