Docs home

Getting started and troubleshooting

Base URL, API keys, required headers, request and response format, errors.

This article explains how to connect to the Edmingle REST API: the base URL, how to get an API key, which headers to send, how requests and responses look, rate limits, error codes, and fixes for the most common setup mistakes.

What is the Edmingle API base URL?

Every institute has its own API host. All endpoints sit under the same path on that host:

https://<your-api-host>/nuSource/api/v1/<endpoint>

For example, the login endpoint is:

https://yourinstitute-api.edmingle.com/nuSource/api/v1/tutor/login

In the Edmingle Postman collection, the domain-url variable holds everything up to and including v1/:

domain-url = https://yourinstitute-api.edmingle.com/nuSource/api/v1/

domain-url already ends with a /. Join it to the endpoint with no extra slash:

  • Correct: {{domain-url}}tutor/login
  • Wrong: {{domain-url}}/tutor/login (this produces v1//tutor/login)

Endpoint paths are lowercase letters and slashes, plus at most one numeric ID. Do not add a trailing slash after the endpoint. A path that does not fit this format is rejected with Invalid URI1.

Only GET, POST and DELETE are used. Each endpoint exists for a specific method.

How do I find my institute's API host?

For an institute on an Edmingle subdomain, the API host is usually the portal hostname with -api added to the first part:

Your portal Your API host
yourinstitute.edmingle.com yourinstitute-api.edmingle.com

If your institute uses a custom domain, or you are not sure, ask Edmingle support for your API URL.

Always call your own institute's API host. Login works out which institute you belong to from the host you call. Logging in through another institute's host fails with Invalid Credentials, even when the username and password are correct.

How do I get an API key?

You get an API key by logging in with an Edmingle user account. Use the same username (or email) and password that the user signs in to Edmingle with. For admin-level integrations, use an admin account.

Send a POST to tutor/login with a form field named JSONString that holds a JSON object:

curl -X POST 'https://yourinstitute-api.edmingle.com/nuSource/api/v1/tutor/login' \
  -F 'JSONString={"username":"admin@example.com","password":"<your-password>","persistent_login":true}'

Login fields:

Field Type Required Notes
username string Yes Email, username or contact number. Max 50 characters.
password string Yes, unless you send otp The user's password.
persistent_login boolean No true gives a long-lived key, false a short-lived one. Defaults to true if left out. Send a real JSON boolean, not the text "true".
user_id integer No Only needed when login returns a list of users (see below).

A successful login returns code: 200, the message Login successful, and a user object. The key is in user.apikey:

{
  "code": 200,
  "message": "Login successful",
  "user": {
    "apikey": "<your-api-key>",
    "user_id": 12345,
    "username": "admin",
    "name": "Admin User",
    "email": "admin@example.com",
    "role": 2,
    "is_user_mfa_enabled": 0,
    "user_org_ids": [2, 5]
  }
}
  • user_org_ids lists the organizations this user belongs to. Use one of them as your ORGID header.
  • role is a number: 0 tutor, 1 student, 2 admin, 4 parent, 7 custom role. Institute admins show as 2.

What the API key is tied to

The key belongs to the user who logged in. Every call made with it acts as that user. The user's role is checked against the organization in your ORGID header, so the same key can have admin rights in one organization and fewer rights in another. A student's key cannot call admin endpoints.

If login returns a list of users instead of a key

If the username and password match more than one account, the response has no apikey. Instead it has payload.users, a list with each account's id, name, email, contact_number and username. Send the login again with the chosen account's id as user_id.

If is_user_mfa_enabled is 1

Your institute requires multi-factor (OTP) login for this user's role. The apikey in that response is not active, and calls with it fail with invalid.credentials. For a server-to-server integration, use an account whose role is not covered by your institute's multi-factor login setting.

The integration "Edmingle API token" is not an API key

The "Edmingle API token" in your institute's integration settings is a different value. It is not accepted as APIKEY. Use the key from tutor/login.

How long does an Edmingle API key last?

Each login creates a new key. A key's lifetime is fixed when it is created. Using the key does not extend it.

Login type Key lifetime
persistent_login: true (or left out) 30 days from login. Some institutes are set to 1 day.
persistent_login: false 5 hours from login.

When a key expires, calls fail with code: 10002 and the message invalid.credentials. Log in again to get a new key.

How do I invalidate (log out) an API key?

Send a POST to user/logout with the key in the APIKEY header:

curl -X POST 'https://yourinstitute-api.edmingle.com/nuSource/api/v1/user/logout' \
  -H 'APIKEY: <your-api-key>'

The key stops working immediately. Logging out a key that is already invalid returns invalid.credentials.

Which headers does the Edmingle API require?

Every endpoint that is not public needs two headers:

Header Value
APIKEY The apikey from tutor/login.
ORGID The ID of the organization you are working in. The user must belong to it.
curl 'https://yourinstitute-api.edmingle.com/nuSource/api/v1/organization/students?page=1&per_page=10' \
  -H 'APIKEY: <your-api-key>' \
  -H 'ORGID: <your-organization-id>'

If APIKEY is missing, wrong or expired, you get invalid.credentials. If ORGID is missing, or the user is not part of that organization, you get You are not a part of this org.

Public endpoints, such as tutor/login, need neither header.

Are APIKEY and ORGID header names case-sensitive?

No. Header names are not case-sensitive. APIKEY, apikey and ApiKey all work, and so do ORGID and orgid.

You can also send both values as request parameters instead of headers:

  • apikey (lowercase) as a query parameter or form field.
  • ORGID (uppercase) as a query parameter or form field.

Parameter names are case-sensitive: apikey and ORGID exactly. If you send both a parameter and a header, the parameter wins. For POST, send them as their own form fields, not inside JSONString.

Prefer headers. Values in a URL query string tend to end up in server and proxy logs.

Browser apps signed in to Edmingle also carry the key in a login cookie. Server integrations should always send the header.

How do I find my institution ID and organization ID (ORGID)?

Your institution is your whole Edmingle account. It can contain several organizations (branches or businesses), each with its own ID. ORGID is an organization ID, not the institution ID.

Ways to find them:

  1. From login. The user_org_ids list in the login response holds the organization IDs your user belongs to.
  2. Institution ID from your portal host. Call GET institute/instituteinfo?host_name=<your-portal-host>. The response's inst_info.institute_id is your institution ID. Use the host without https://, for example yourinstitute.edmingle.com.
  3. All organizations in your institution. Call GET institution/organizations?institution_id=<your-institution-id>. Each entry in institution has an organization_id and organization_name.
  4. Ask Edmingle support.

What request format does the Edmingle API expect?

GET requests

Send parameters as URL query parameters:

GET {{domain-url}}organization/students?organization_id=2&page=1&per_page=10

POST requests: form-data with JSONString

The API does not read a raw JSON request body. Send POST data as multipart/form-data or application/x-www-form-urlencoded, with one field named JSONString that holds a JSON object:

JSONString={"username":"admin@example.com","password":"<your-password>","persistent_login":true}

Rules:

  • On endpoints that take input, JSONString is required for POST. Without it you get Invalid request format. JSONString required.
  • If the text in JSONString is not valid JSON, it is treated as empty. You then get Param [name] required for the first required field.
  • Other plain form fields are merged into the JSON. Where a field appears in both, the plain form field wins. Plain form fields always arrive as text.
  • File uploads go as normal multipart file fields next to JSONString.

DELETE requests

DELETE reads only URL query parameters, not a request body. On DELETE endpoints that take input, send JSONString as a URL-encoded query parameter.

Field types

Each endpoint checks its declared fields:

  • Integer and number fields accept numbers or numeric text, such as 5 or "5".
  • Boolean fields need a real JSON true or false inside JSONString. The text "true", a form field persistent_login=true, or a query parameter all fail with Type mismatch for [name].
  • String fields need a JSON string. Sending a number where text is expected fails with Type mismatch for [name].
  • Pattern-checked fields must match the expected format, or you get Invalid value for param [name].
  • A required field sent as an empty string fails with Param [name] required. An optional empty field is ignored.
  • Fields can have a maximum length. Longer values fail with Max allowed length for name is N.

How do numeric IDs in the URL path work?

Some endpoints take a resource ID in the path, for example course/123/students. Rules:

  • The ID must be digits only.
  • A path can contain at most one numeric ID.
  • On many such endpoints the API checks that the ID belongs to your organization and, for tutor and student keys, to that user's own courses or records. If not, you get Invalid Resource ID.

What does an Edmingle API response look like?

Every response is JSON with a code and a message.

Success: HTTP status 200, code: 200. The data sits in extra top-level keys next to code and message. Their names depend on the endpoint, for example user for login or institution for the organizations list.

{
  "code": 200,
  "message": "Success",
  "institution": [ { "organization_id": 2, "organization_name": "Main Branch" } ]
}

Error: only code and message. message is usually a string. Some endpoints return a list of strings instead.

{ "code": 17003, "message": "Param [username] required" }

How HTTP status relates to code

code in the body HTTP status
200 200
400, 403, 404, 429, 500 The same number
Any code above 2000 (for example 10002, 17003) 400

Always read code in the body. Many different errors share HTTP 400. Authentication, organization and permission errors return HTTP 400 or 404, never 401.

How does pagination work in the Edmingle API?

List endpoints that support pagination take two query parameters:

Parameter Default Allowed values
page 1 Integer, 1 to 10000000
per_page 50 Integer, 1 to 10000000

A page or per_page value outside these rules fails on any endpoint with code 50060 (page must be a valid integer between 1 and 10000000) or 50061 (per_page must be a valid integer between 1 and 10000000).

Paginated responses include a page_context object:

Key Meaning
page The page you asked for.
per_page The page size you asked for.
total_rows Total matching rows, when the endpoint reports a total.
has_more_page true if more pages follow, when the endpoint reports a total.
sort_by, sort_order Present when sorting was applied.

Keep requesting the next page until has_more_page is false.

Some list endpoints also accept:

  • search: a keyword matched against the endpoint's searchable fields.
  • sort_by and sort_order: sort_order is A (ascending, the default) or D (descending). sort_by accepts only the fields that endpoint allows.

A few report endpoints use cursor paging instead of page. Their responses include has_next_page and next_cursor. To get the next batch, send the next_cursor value back as cursor.

What are the Edmingle API rate limits?

There are two kinds of limit. Which one applies depends on whether you identify your calls as an API client.

Per-endpoint limits (default)

  • Each endpoint has its own limit. The default is 30 requests per 1-minute window, with a 30-minute lockout when you go over.
  • Some endpoints set their own numbers. For example, some read endpoints allow 100, 300 or 1000 requests per minute.
  • Counts are kept separately for each combination of user, endpoint, HTTP method and calling IP address. Public endpoints (no API key) are counted per IP address. tutor/login is one of these: 30 requests per minute per IP, then a 30-minute lockout.
  • The window starts with your first request. Once the window has passed, the count starts again from zero.
  • Going over the limit locks only that endpoint and method. Your other endpoints keep working.

Institution-wide quota for API clients

If you send the header X-Platform-Type: 4 (or the request parameter PLATFORM_TYPE=4) with a valid API key, the per-endpoint limits are replaced by a single quota:

  • One shared count for your whole institute, across all endpoints and all API keys.
  • Default: 10 requests per 60-second window. Your institute's plan can set a different number.
  • No lockout. The count resets when the window ends.
  • Every such response carries these headers:
Header Meaning
X-RateLimit-Limit Requests allowed per window.
X-RateLimit-Remaining Requests left in the current window.
X-RateLimit-Reset Unix time, in seconds, when the window resets.

What happens when I hit the Edmingle API rate limit?

You get HTTP status 429 and code: 429.

Per-endpoint limit. When you first go over:

{ "code": 429, "message": "IP Blocked. API limit for this request exceeded. Try after 30 minutes" }

During the lockout, the message shows the minutes left, for example Try after 12.5 minutes.

Institution-wide quota:

{ "code": 429, "message": "Request quota exhausted. Limit: 10 requests per minute. Reset in 42 seconds" }

How to recover:

  • Per-endpoint limit: wait out the lockout shown in the message. Retrying during the lockout does not shorten it. Other endpoints still work meanwhile.
  • Institution-wide quota: wait until the time in X-RateLimit-Reset, or the seconds in the message.
  • For bulk jobs, spread calls out. Use larger per_page values to make fewer list calls. Stay under 30 calls per minute per endpoint unless you know that endpoint's limit is higher.
  • If your integration needs higher limits, contact Edmingle support.

Edmingle API error codes

code HTTP message What it means What to do
10002 400 invalid.credentials API key missing, wrong, expired or logged out. Check the APIKEY header. Log in again for a new key.
10002 400 Invalid Credentials Login failed: wrong username or password, or wrong institute API host. Check the credentials and that you are calling your own institute's API host.
10002 400 Invalid OTP OTP login with a wrong or expired OTP. Request a new OTP.
10026 400 PLEASE ENTER PASSWORD / OTP Login sent with neither password nor otp. Add password to JSONString.
10001 400 User Blocked The user is blocked. Ask your institute admin to unblock the user.
10001 400 Please Contact Admin. The user has no active organization. Ask your institute admin to add the user to an organization.
10001 400 Institution subscription is inactive. Please contact support. Your institute's subscription is not active. Contact Edmingle support.
404 404 You are not a part of this org ORGID is missing, or the key's user does not belong to that organization. Send ORGID with an ID from user_org_ids.
404 404 You do not have permissions to access this api The user's role in this organization cannot call this endpoint. Use a key for a user with the right role, such as an admin. Check ORGID.
404 404 Admin API. Only Edmingle admin can access this API. Internal Edmingle staff endpoint. Not available to institutes. Use a different endpoint.
2007 400 Invalid Resource ID The path ID is not in your organization, or a tutor or student key used an ID they are not mapped to. Check the ID and ORGID. Use an ID the user has access to.
2007 400 Tutor not allowed to add/edit resource inside department. Endpoint limited to admins in this case. Use an admin key.
2009 400 Admin not allowed to add/edit resource inside department. Endpoint does not allow admins in this case. Check the endpoint's documentation.
400 400 Invalid URI1 The URL path is malformed: double slash, trailing slash, capital letters, or more than one numeric ID. Fix the URL. See "What is the Edmingle API base URL?".
400 400 Invalid URI2 No endpoint with this path for this HTTP method. Check the path spelling and the HTTP method.
400 400 Invalid request format. JSONString required POST or DELETE sent without a JSONString field. Send the data as form-data in a JSONString field.
17003 400 Param [name] required A required field is missing or empty. Also shown when JSONString is not valid JSON. Add the field. Validate your JSON.
17001 400 Type mismatch for [name] Wrong type, for example a boolean sent as text. Send the right JSON type inside JSONString.
17001 400 Invalid value for param [name] Value is not in the expected format. Check the allowed values for that field.
17002 400 Max allowed length for name is N Value too long. Shorten the value.
50060 400 page must be a valid integer between 1 and 10000000 Bad page value. Send a whole number of 1 or more.
50061 400 per_page must be a valid integer between 1 and 10000000 Bad per_page value. Send a whole number of 1 or more.
400 400 Uploaded file should be [...] File type not allowed for this endpoint. Upload one of the listed types.
400 400 Uploaded file should be less than N MB File too large. Upload a smaller file.
429 429 IP Blocked. API limit for this request exceeded. Try after N minutes Per-endpoint rate limit hit. Wait for the lockout to end. See the rate limit sections.
429 429 Request quota exhausted. Limit: N requests per minute. Reset in N seconds Institution-wide quota hit. Wait for the reset.
1700001 400 Varies, for example Asset not found The record does not exist, or is not in your institute. Check the ID and ORGID.
7001, 13001 400 Varies The endpoint refused the action for this user. Check the user's role and permissions.
500 500 Usually Uh-oh! Something went wrong. Server error. Retry later. If it continues, contact Edmingle support with the endpoint, the time, and the ORGID used.

Other codes above 2000 are endpoint-specific errors. They always come with HTTP 400. Read the message.

Troubleshooting Edmingle API setup problems

Every call returns invalid.credentials

  • Cause: the APIKEY header is missing, the key is wrong, it expired, or it was logged out. It can also be a key from a login that needed multi-factor authentication (is_user_mfa_enabled: 1).
  • Fix: log in again with tutor/login and copy user.apikey exactly. Send it as the APIKEY header. Use persistent_login: true for a 30-day key instead of 5 hours.

My API key stopped working after 5 hours

  • Cause: the key was created with persistent_login: false.
  • Fix: log in with "persistent_login": true as a JSON boolean inside JSONString.

You are not a part of this org

  • Cause: ORGID is missing, has a typo, or is an organization the key's user does not belong to. Sending the institution ID instead of an organization ID also causes this.
  • Fix: use an ID from user_org_ids in the login response.

You do not have permissions to access this api

  • Cause: the key's user has a role that cannot call this endpoint in this organization, for example a student or tutor key on an admin endpoint. The same user can have different roles in different organizations.
  • Fix: log in as a user with the required role, usually an admin, and check that ORGID is an organization where that user has it.

Invalid URI1 on every request

  • Cause: the URL has a double slash ({{domain-url}}/endpoint), a trailing slash after the endpoint, capital letters, or more than one numeric ID.
  • Fix: domain-url already ends with /. Write {{domain-url}}organization/students, all lowercase, with no slash at the end.

Invalid URI2

  • Cause: the endpoint path is misspelled, or you used the wrong HTTP method, for example GET on a POST endpoint.
  • Fix: check the endpoint's path and method in the API reference.

Invalid request format. JSONString required when sending JSON

  • Cause: you sent a raw JSON body (Content-Type: application/json). The API does not read raw JSON bodies.
  • Fix: send form-data with one field named JSONString that contains your JSON object.

Param [name] required even though I sent the field

  • Cause: the JSON in JSONString is not valid, so it was read as empty. Or the field was sent as an empty string. Or a DELETE request put its data in the body instead of the query string.
  • Fix: validate the JSON, for example check the quotes and trailing commas. Send a value for the field. For DELETE, put JSONString in the URL query string.

Type mismatch for [persistent_login] (or any boolean field)

  • Cause: the boolean was sent as text: a plain form field, a query parameter, or "true" in quotes.
  • Fix: put it inside JSONString as a real JSON boolean: "persistent_login": true.

Login fails with Invalid Credentials but the password is right

  • Cause: the request went to the wrong API host, such as another institute's host or a generic one. Login identifies your institute from the host you call.
  • Fix: call tutor/login on your own institute's API host.

Login returns a list of users and no API key

  • Cause: several accounts match the username and password.
  • Fix: pick the right id from payload.users and log in again with it as user_id.

Login succeeds but the key does not work (is_user_mfa_enabled is 1)

  • Cause: your institute requires multi-factor login for this user's role. The returned key is not active.
  • Fix: use an account whose role is not covered by the multi-factor login setting.

The "Edmingle API token" from settings does not work as APIKEY

  • Cause: that token is used for other integrations. It is not a REST API key.
  • Fix: get a key from tutor/login.

Invalid Resource ID

  • Cause: the ID in the path belongs to another organization, or, for a tutor or student key, to a course or record that this user is not mapped to.
  • Fix: check the ID and that ORGID is the organization it belongs to. For tutor and student keys, use an ID the user has access to, or use an admin key.

Getting 429 errors during a bulk sync

  • Cause: more than the endpoint's limit (30 per minute by default) from the same user and IP address, which triggers a 30-minute lockout on that endpoint.
  • Fix: slow down, use larger per_page values, and wait for the lockout to end. Other endpoints still work while one is locked.

Updated yesterday

Ask AI