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 producesv1//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_idslists the organizations this user belongs to. Use one of them as yourORGIDheader.roleis a number:0tutor,1student,2admin,4parent,7custom role. Institute admins show as2.
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:
- From login. The
user_org_idslist in the login response holds the organization IDs your user belongs to. - Institution ID from your portal host. Call
GET institute/instituteinfo?host_name=<your-portal-host>. The response'sinst_info.institute_idis your institution ID. Use the host withouthttps://, for exampleyourinstitute.edmingle.com. - All organizations in your institution. Call
GET institution/organizations?institution_id=<your-institution-id>. Each entry ininstitutionhas anorganization_idandorganization_name. - 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,
JSONStringis required forPOST. Without it you getInvalid request format. JSONString required. - If the text in
JSONStringis not valid JSON, it is treated as empty. You then getParam [name] requiredfor 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
5or"5". - Boolean fields need a real JSON
trueorfalseinsideJSONString. The text"true", a form fieldpersistent_login=true, or a query parameter all fail withType 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_byandsort_order:sort_orderisA(ascending, the default) orD(descending).sort_byaccepts 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/loginis 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_pagevalues 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
APIKEYheader 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/loginand copyuser.apikeyexactly. Send it as theAPIKEYheader. Usepersistent_login: truefor 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": trueas a JSON boolean insideJSONString.
You are not a part of this org
- Cause:
ORGIDis 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_idsin 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
ORGIDis 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-urlalready 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
GETon aPOSTendpoint. - 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
JSONStringthat contains your JSON object.
Param [name] required even though I sent the field
- Cause: the JSON in
JSONStringis not valid, so it was read as empty. Or the field was sent as an empty string. Or aDELETErequest 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, putJSONStringin 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
JSONStringas 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/loginon 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
idfrompayload.usersand log in again with it asuser_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
ORGIDis 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_pagevalues, and wait for the lockout to end. Other endpoints still work while one is locked.