Edmodo Connect API Documentation

“Log in with Edmodo” Button

CSS

#edmodo-logo {
display: inline-block;
position: relative;
top: 6px;
right: 16px;
margin:0;
}
#vertical-divider {
position: relative;
width: 0px;
right: 7px;
display: inline-block;
border-left: 1px solid #2567a8;
border-right: 1px solid #4b8dce;
height:inherit;
}
#vertical-divider:after {
content: '.';
visibility: hidden;
}
#edmodo {
font-weight: 500;
font-family: "Helvetica Neue Light", "Helvetica Neue", Arial, Helvetica, sans-serif;
}
button.login-edmodo-button {
line-height: 44px;
padding: 0 14px 0 28px;
border-radius: 2px;
cursor: pointer;
background-color: #3784d3;
box-shadow: 0 2px 0 #276bb0;
border:0;
height:38px;
}
button.login-edmodo-button:hover {
text-decoration: none;
color: white;
background-color: #2d7bcc;
}
button.login-edmodo-button p {
color: white;
text-shadow: 0 1px 0 #555555;
font-size: 19px;
font-family: "HelveticaNeue-Light", "Helvetica Neue Light", "Helvetica Neue", Arial, Helvetica, sans-serif;
font-weight: 300;
display: inline-block;
margin:0;
}

HTML

<button class="login-edmodo-button">
<img id="edmodo-logo" src="https://s3-us-west-2.amazonaws.com/s.cdpn.io/41205/edmodo-icon_1.png">
<div id="vertical-divider"></div>
<p>Log in with <span id="edmodo">Edmodo</span></p>
</button>

Connecting Your Application

The Login Dialog

Parameters for GET https://api.edmodo.com/oauth/authorize

client_id String
Required		 Your application’s client id
redirect_uri String
Required		 Your application’s callback URL
scope String
Optional		 Space-delimited API scopes to request from the user, default is “basic”
response_type String
Required		 “code” or “token”. See below.

Your app can decide whether to open the Login Dialog as a popup window or as a redirect. A popup window is suitable for desktop websites or native apps capable of showing an embedded web view. The redirect is more appropriate for mobile websites or native apps that cannot open an embedded web view.

API scopes determine what information your app can access about a user through the API.

basic Read-only access to the current user’s profile
read_groups Read-only access to the current user’s groups and group memberships
read_connections Read-only access to the current user’s teacher connections on Edmodo
read_user_email Read-only access to the current user’s email address provided to Edmodo (teachers only)
create_messages POST access to send messages in Edmodo. See description below
library_items Send items to the teacher Library or student Backpack

Note that more scopes will be made available over time.

Getting an Access Token

After the user authorizes the app (or cancels the login), The Login Dialog will redirect to your application callback URL. The response data sent to the callback URL depends on the authentication flow, determined by the “response_type” parameter. The two available flows are “token” and “code“.

Token authentication flow

The response simply includes the API access token in the URL fragment. To use this flow, your app must use SSL for all server-client communication. Note that because the response is included in a URL fragment, the data will not get sent to your server, and must be accessed through JavaScript on the callback page.

Successful login
https://myapp.com/callback#access_token=8fb2f251560655dcaeca67adf9985f66aa9f7f1f55221de602b5958280a91a7f&token_type=bearer&expires_in=7200

Canceled login
https://myapp.com/callback#error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request.

Code authentication flow

The response includes a temporary “code” parameter. This code must be exchanged for an access token by making a server-to-server request with the client secret. This flow must be used by apps that do not have site-wide SSL.

Successful login
https://myapp.com/callback?code=11d987616ca8a758290a3790e2dfa30ba9b8a45a9dc6723a14585d50bb304263

The “code” parameter must be exchanged for an access token by making a second request from your app’s server:

Parameters for POST https://api.edmodo.com/oauth/token

client_id String
Required		 Your application’s client id
client_secret String
Required		 Your application’s client secret
redirect_uri String
Required		 Your application’s callback URL
code String
Required		 The “code” parameter received from the login dialog
grant_type String
Required		 Should be set to “authorization_code” if exchanging your “code” with an access_token

Response format{
"access_token":
"8fb2f251560655dcaeca67adf9985f66aa9f7f1f55221de602b5958280a91a7f",
"expires_in": 7200,
"token_type": "bearer",
}

Canceled login
https://myapp.com/callback?error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request.

Token refresh flow

When requesting the access token, the API also returns an expires_in and refresh_token parameter. expires_in is the number of seconds for which the access token is valid, from the moment it is issued. Once the access token expires, the refresh_token can be used to get a new access token without requesting further authorization from the user.
POST https://api.edmodo.com/oauth/token

client_id String
Required		 Your application’s client id
client_secret String
Required		 Your application’s client secret
redirect_uri String
Required		 Your application’s callback URL
refresh_token String
Required		 The refresh token returned from /oauth/token
grant_type String
Required		 Should be set to refresh_token

Keeping Users Logged In

You may persist the access token to keep the user logged in to your app. How the token is persisted is up to you. For web apps, it is best to store the access token in the session data. For native apps (desktop or mobile), the access token can be stored in the app’s data store.

Note that access tokens expire after a certain time. To get a new access token, you can open the login dialog box again. As long as the user is still logged in to edmodo.com and has not revoked API access for your app, the login dialog will immediately redirect to your callback URL with the appropriate response data to get a fresh access token.

Logging Users Out

To log users out, clear out the persisted access token. Again, how this is done is up to you and the method you use to persist the access token.

Use the return_to parameter in your query string to redirect users after a successful log-out.
https://api.edmodo.com/logout?return_to=http://yourSite.com

Using The Edmodo API

The Edmodo API is serves JSON over HTTPS from the following URL:
https://api.edmodo.com/

An access token must be included with each API request. It can be included either as a parameter or in the Authorization header of the request.

Access token as a parameter
GET https://api.edmodo.com/groups/26?access_token=8fb2f251560655

Access token as a request header
GET https://api.edmodo.com/groups/26
Authorization: Bearer 8fb2f251560655

Rate Limiting

An app is allowed a maximum of 300 API requests per user per day. Information about the remaining number of allowed requests is included in the response headers of each request. If you exceed your rate limit, the API requests will return a 403 Forbidden status.

Example Request
GET https://api.edmodo.com/groups/26
Authorization: Bearer 8fb2f251560655

Example Response
200 OK
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299

Example Response After Exceeding Rate Limit
403 Forbidden
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0

Pagination

All API endpoints that return a collection of resources use pagination. Requests that return paginated results use the following pagination parameters:

per_page Integer
Optional		 The maximum number of results per page, default depends on the requested resource.
page Integer
Optional		 The page number (starting with 1), default is 1

The Link header of the response will include information about the previous page or results (rel=”previous”) and the next page of results (rel=”next”). The previous and next links will only be present if a previous or next page of results exists. The total size of the collection can be determined by looking at the X-Total-Count header.

Example RequestGET https://api.edmodo.com/groups?page=2&per_page=2
Authorization: Bearer 8fb2f251560655

Example Response HeadersLink: <https://api.edmodo.com/groups?page=1&per_page=2>; rel="previous", <https://api.edmodo.com/groups?page=3&per_page=2>; rel="next"
X-Total-Count: 104

GET /users/:id

Get a single user (by ID)

Required Scopes: basic

Example RequestGET https://api.edmodo.com/users/1
Authorization: Bearer 8fb2f251560655

Example Response200 OK
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
{
"url": "https://api.edmodo.com/users/1",
"id": 1,
"type": "teacher",
"username": "adamstep",
"user_title": "Mr",
"first_name": "Adam",
"last_name": "Stepinski",
"avatars":
{
"small": "https://u.ph.edim.co/default-avatars/10_t.jpg",
"large": "https://u.ph.edim.co/default-avatars/10.jpg"
}
}

Note: user type options include “teacher” and “student”. For more information about these entities, check out our help center.

Get a single user (using “me”)

Note: Using “me” in place of the id will redirect to the actual id of the current user. All initial requests to the users resource requires using “me” in place of the id.

Example RequestGET https://api.edmodo.com/users/me
Authorization: Bearer 8fb2f251560655

Example Response302 Moved Temporarily
Location: https://api.edmodo.com/users/1
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299

Get a single user with email address

GET /users/:user_id

Returns extended information about the user. Includes the user’s email if the user is getting themselves, or if an admin is retrieving a user they administer. (When using OAuth, the “read_user_email” scope must be included to get the email address).

OAuth scopes

  • basic (does not include the user’s email)
  • read_user_email (must be combined with the “basic” scope)

Example request
GET /users/10

Example Response
200 OK
{
url: "http://localhost:3000/users/10",
id: 10,
type: "teacher",
username: "edna",
user_title: "Ms",
first_name: "Edna",
last_name: "Krabappel",
locale: "en-GB",
timezone: "America/New_York",
email: "edna@springfield.net",
avatars: {
small: "https://u.ph.edim.co/default-avatars/10_t.jpg",
large: "https://u.ph.edim.co/default-avatars/10.jpg"
},
school: {
url: "https://api.edmodo.com/schools/14",
id: 14
},
district: {
url: "https://api.edmodo.com/districts/12",
id: 12
},
school_admin_rights: {
institution: "school/1001",
can_grant_rights: true,
can_allocate_funds: true
},
district_admin_rights: {
institution: "district/90",
can_grant_rights: false,
can_allocate_funds: false
}
}

GET /users/:id/user_token

The older Apps API uses “user tokens” to identify users, but the new Edmodo API uses user ids. Publishers that use the Apps API can use this endpoint to retrieve the user token associated with the user. Additionally, the Apps API now returns the user id used in the new Edmodo API as well. See the /users, /launchRequests, and /members Apps API resources in your developer sandbox for more information.

Note: This endpoint will only work for publishers that use the older Apps API.

Required Scopes: basic

Example RequestGET https://api.edmodo.com/users/1/user_token
Authorization: Bearer 8fb2f251560655

Example Response200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
{
"user_token": "b858bab08"
}

GET /groups/:id

Get a single group

Required Scopes: read_groups

Example RequestGET https://api.edmodo.com/groups/26
Authorization: Bearer 8fb2f251560655

Example Response200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
{
"url": "https://api.edmodo.com/groups/26",
"id": 26,
"title": "Geometry Period 1",
"description": "Eighth grade geometry class",
"num_members": 2,
"archived": false,
"moderate_posts_and_replies": true,
"default_membership_type": "read_write_member",
"start_level": "eighth",
"end_level": "eighth",
"expected_group_size": "six_to_ten",
"subject": "geometry",
"memberships":
"https://api.edmodo.com/group_memberships?group_id=26",
"owners":
[
{
"url": "https://api.edmodo.com/users/1",
"id": 1,
"type": "teacher",
"username": "adamstep",
"user_title": "Mr",
"first_name": "Adam",
"last_name": "Stepinski",
"avatars":
{
"small": "https://u.ph.edim.co/default-avatars/10_t.jpg",
"large": "https://u.ph.edim.co/default-avatars/10.jpg"
}
}
]
}


Note about small groups: Edmodo has both groups and ‘small groups’ which are children on the main group. If the returned group is a small group, the object will have the key ‘parent_group_id’; the values for this key will designate the parent groups. See our help center page for how teachers use these in practice.

View all groups

To see all the groups (and their ids to use in subsequent queries) a teacher is in, do not include the final part of the path/query parameter designating the individual group.

Example RequestGET https://api.edmodo.com/groups
Authorization: Bearer 8fb2f251560655

GET /group_memberships

Get a single group membership (based on parameters)

Required Scopes: read_groups

user_id String
Optional		 Only show memberships for the given user. Defaults to the id of the currently authenticated user.
group_id Integer
Optional		 Only show memberships for the given group. If specified, user_id is ignored.
page Integer
Optional		 The page number (starting with 1), default is 1
per_page Integer
Optional		 The maximum number of results per page, default depends on the requested resource.

Example RequestGET https://api.edmodo.com/group_memberships?group_id=26
Authorization: Bearer 8fb2f251560655

Example Response[
{
"url": "https://api.edmodo.com/group_memberships/26",
"type": "owner",
"show_in_latest_posts": true,
"send_notifications": false,
"color": "purple",
"group":
{
"url": "https://api.edmodo.com/groups/26",
"id": 26,
"title": "Geometry Period 1",
},
"user":
{
"url": "https://api.edmodo.com/users/1",
"id": 1,
"type": "teacher",
"username": "adamstep",
"user_title": "Mr",
"first_name": "Adam",
"last_name": "Stepinski",
"avatars":
{
"small": "https://u.ph.edim.co/default-avatars/10_t.jpg",
"large": "https://u.ph.edim.co/default-avatars/10.jpg"
}
}
},
{
"url": "https://api.edmodo.com/group_memberships/39",
"type": "read_write_member",
"show_in_latest_posts": true,
"send_notifications": false,
"color": "mustard",
"group":
{
"url": "https://api.edmodo.com/groups/26",
"id": 26,
"title": "Geometry Period 1",
},
"user":
{
"url": "https://api.edmodo.com/users/2",
"id": 2,
"type": "student",
"username": "bart",
"user_title": null,
"first_name": "Bart",
"last_name": "Simpson",
"avatars":
{
"small": "https://u.ph.edim.co/default-avatars/11_t.jpg",
"large": "https://u.ph.edim.co/default-avatars/11.jpg"
}
}
}
]

Get a single group membership (based on ID)

GET /group_memberships/:id

Required Scopes: read_groups

Example RequestGET https://api.edmodo.com/group_memberships/2
Authorization: Bearer 8fb2f251560655

Example Response200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
{
"url": "https://api.edmodo.com/group_memberships/26",
"type": "owner",
"show_in_latest_posts": true,
"send_notifications": false,
"color": "purple",
"group":
{
"url": "https://api.edmodo.com/groups/26",
"id": 26,
"title": "Geometry Period 1",
"description": "Eighth grade geometry class"
},
"user":
{
"url": "https://api.edmodo.com/users/1",
"id": 1,
"type": "teacher",
"username": "adamstep",
"user_title": "Mr",
"first_name": "Adam",
"last_name": "Stepinski",
"avatars":
{
"small": "https://u.ph.edim.co/default-avatars/10_t.jpg",
"large": "https://u.ph.edim.co/default-avatars/10.jpg"
}
}
}

GET /connections

List connections

Retrieves a user’s connections.
OAuth scopes: read_connections

Parameters

user_id String
Optional		 The user for which to retrieve connections. Defaults to the current user.
status String
Optional		 Filter connections by status. Valid options:

  • active (default): The user’s current connections. User can be the requester or requestee.
  • pending: Connections requested by the user but not approved yet by the requestee.
  • blocked: Connection requests blocked by the user.
per_page Integer
Optional		 The maximum number of connections to return. Defaults to 20.
page Integer
Optional		 The page number to return. See pagination.

Example Request
GET /connections?status=active&per_page=2
Example Response
200 OK
[
{
"id": "10-11",
"url": "https://api.edmodo.com/connections/10-11",
"status": "active",
"user1": {
"id": 10,
"url": "https://api.edmodo.com/users/10",
"name": "Edna Krabappel",
"type": "teacher",
},
"user2": {
"id": 11,
"url": "https://api.edmodo.com/users/11",
"name: "Seymour Skinner",
"type": "teacher",
}
}
]

Get a single connection

GET /connections/:connection_id

A connection can be retrieved by the requester or requestee.
OAuth scopes: all or read_connections

Example Request
GET /connections/10-11
Example Response
{
"id": "10-11",
"url": "https://api.edmodo.com/connections/10-11",
"status": "active",
"user1": {
"id": 10,
"url": "https://api.edmodo.com/users/10",
"name": "Edna Krabappel",
"type": "teacher",
},
"user2": {
"id": 11,
"url": "https://api.edmodo.com/users/11",
"name: "Seymour Skinner",
"type": "teacher",
}
}

POST /messages

Create a messsage

POST /messages

Required scopes: create_messages

Input

content_type Required string The type of a message content. Valid options:

  • note
content Required object The content JSON.
For type note:

text Required string The text of the note.
attachments Optional object Attachments included with the note.
recipients Required recipients object The recipients of the message
post_at Optional datetime string If provided, the message will be posted at the given time. If not provided, the message is posted immediately.
moderated Optional boolean If provided, the message created will be put into the moderated queue before being posted

Example Request

POST /messages
{
"content_type": "note",
"content": {
"text": "This is my note",
"attachments": {
"links": [{"title": "A web page", "link_url": "https://google.com"}]
}
},
"recipients": {
"users": [{"id": 1}],
"groups": [{"id": 2}],
"parent_groups": [{"id": 2}]
},
"moderated": "true"
}

Example Response

201 Created
Location: https://api.edmodo.com/messages/1
{
"id": 23,
"url": "https://api.edmodo.com/messages/23",
"content_type": "note",
"content": {
"id": 23,
"url": "https://api.edmodo.com/messages/23",
"text": "This is my note",
"attachments": {
"links": [{"title": "A web page", "link_url": "https://google.com"}]
}
},
"creator": {
"id": 400,
"url": "https://api.edmodo.com/users/400",
"first_name": "Nic",
"last_name": "Borg",
"username": "nic",
"avatars": {...}
},
"recipients": {
"users": [
{
"id": 1,
"url": "https://api.edmodo.com/users/1"
"name": "Nic Borg"
"avatars": {...}
}
],
"groups": [
{
"id": 2,
"url": "https://api.edmodo.com/groups/2"
"name": "My Group"
}
]
}
"replies_url": https://api.edmodo.com/replies?message_id=23
"last_replies": [],
"created_at": "2013-03-04"
}

POST /library_items

Create an item in the teacher Library or student Backpack

POST /library_items

Required scopes: write_library_items

Input

type Required string The type of the item. Valid options include:

  • folder
  • file
  • link
  • embed
item Required object The item data.
For type folder:

title Required string The title of the folder.

For type link:

title Required string The title of the link.
link_url Required string The URL link.

For type embed:

title Required string The title of the embed.
content Required string HTML content of embed

Example request
POST /library_items
{
"type": "link",
"item": {
"link_url": "https://nytimes.com",
"title": "New York Times",
}
}
Example response
201 Created
Location: https://api.edmodo.com/library_items/123
{
"id": 123,
"url": "https://api.edmodo.com/library_items/123",
"type": "link",
"parent_id": 1,
"position": 1,
"subject_area": "MATHEMATICS",
"start_level": "FIRST",
"item": {
"id": 10,
"url": "https://api.edmodo.com/links/10",
"link_url": "https://nytimes.com",
"title": "New York Times",
},
"created_at": "2015-10-02"
}

Redirecting after log-in with ‘state’ parameter

We allow for a additional parameter called ‘state’ to be used during the authorization flow. You can use this to persist any information you would still like to be available after the user completes logging in via Edmodo Connect.

Example URL
https://api.edmodo.com/oauth/authorize?response_type=code&redirect_uri=https%3A%2F%2Fwww.edmodoRocks.com%2Flogin%2Fedmodo%2Fcallback&state=12345

Example use case

  • Want user to land on specific item, e.g. quiz_id=12345.
  • When user hits API authorization page, pass in ‘state’ parameter to identify the item.
  • After the log-in, the state parameter will perist in the URL. Use this to redirect to the desired location on your site or app.