API Overview

The ampEducator API provides developers with access to a large subset of ampEducator features, allowing you to access and interact with data in your institution's account.

For a complete list of available resources, endpoints, parameters, and response objects, see the ampEducator Developer API Reference.

Before using the API:

API requests are made using the following endpoint structure:

Where:

Each endpoint in the Developer API Reference specifies whether it requires a GET or POST request and which parameters are required.

Your institution's API key is required to authenticate requests.

The API key can be provided using an HTTP Bearer token:

For endpoints that accept parameters, the API key may also be included as a request parameter:

For integrations, using the Authorization Bearer header is recommended where supported.

Endpoints that accept POST requests can also receive a JSON object as the request body.

Use the following headers:

Example:

The API returns responses as JSON.

A typical response follows this structure:

Always check the messages object for warnings or errors that may provide additional information about the request.

The API may return the following HTTP response codes:

A 200 response may still contain a warning, so integrations should review the messages object rather than relying on the response code alone.

Most get and list endpoints support filtering directly on fields of the returned object.

Use the field name and desired value as a query parameter:

Multiple filters can be combined:

When multiple filters are provided, results must match all of the specified values.

If a query parameter matches a field on the underlying object, its value is used as an exact-match filter. Parameter names that do not correspond to a valid field are ignored, so check the parameter name carefully if a filter does not appear to be applying.

Filter values are automatically converted to the underlying field's data type, such as numbers, booleans, or dates. If a value cannot be converted to the expected type, the API returns an HTTP 400 response identifying the invalid field and value.

The following parameter names are reserved for pagination and sorting and cannot be used as field filters:

List endpoints return results one page at a time.

The following parameters can be used to control pagination:

For example:

A paginated response includes information such as:

Continue requesting pages until page equals totalPages.

If you request a page beyond totalPages, the API returns an empty data array rather than an error. Use totalPages to determine when you have reached the end of the result set.

When retrieving a large number of records, increasing limit up to the maximum of 500 can significantly reduce the number of API calls required.

Results can be ordered using orderBy and orderDir.

For example:

Or in a JSON request:

orderDir accepts:

orderBy must match a valid field on the returned object. If the field is not recognized, the API ignores it and returns results in the default order.

API requests are managed on a per-institution basis to maintain reliable performance.

Requests from the same institution are processed sequentially, one at a time, in the order received.

If an integration submits multiple API requests at the same time, the requests are queued rather than processed concurrently.

Typical API usage should not be affected. However, large bursts of concurrent requests will take longer to complete because later requests must wait for earlier requests to finish.

Each institution has a limited queue depth. If too many requests are waiting at once, additional requests receive:

A request that waits too long in the queue may receive:

If either occurs, wait before retrying the request and consider reducing the number of concurrent calls.

In addition to request queuing, each institution has a limit on the number of requests it can make over time.

This protects against a different pattern than concurrent requests: an integration making continuous, high-frequency calls even if those calls are being sent one at a time.

If the rate limit is exceeded, additional requests receive an HTTP 429 response until the request rate decreases.

This is a rolling limit rather than a hard daily cap, so normal usage recovers automatically as the call rate drops.

Exact rate limits are not published and may be adjusted over time. Integrations making occasional or moderately paced requests, including reasonable bursts such as several requests during a page load, should not normally encounter the limit.

Rate limiting is primarily intended to prevent continuous, high-frequency calling, such as repeatedly retrieving individual records when a batch or filtered request could be used instead.

If an integration repeatedly exceeds the rate limit over a sustained period, it may be temporarily blocked.

This is particularly likely if an integration continues retrying immediately after receiving 429 responses rather than waiting before retrying.

While temporarily blocked, requests from the institution receive an HTTP 429 response indicating the block.

Repeated excessive traffic may increase the duration of the temporary block. After a sustained period of normal activity, the block duration resets.

To avoid temporary blocks, implement retry-with-backoff rather than immediately retrying a request after receiving a 429 response.

When retrieving larger amounts of data:

For example, if a request receives a 429, wait briefly before retrying. If repeated attempts continue to fail, progressively increase the delay rather than immediately sending another request.

Additional limits apply when generating reports through the API.

A report can be regenerated through the API at most once per hour, per report.

If /report/generate is called again for the same report before one hour has passed since it was last generated, ampEducator returns the most recently generated version instead of starting another report-generation job.

The request still returns an HTTP 200 response and includes a warning indicating that the existing report was returned.

This cooldown applies only to automated API requests. Generating the report manually in ampEducator is not affected.

Most SIS data, such as enrollment, grades, courses, and invoices, does not change frequently enough to require regenerating the same report more than once per hour.

If you have a specific need for more frequent generation of a report, please contact us to discuss your requirements.

If your integration calls /report/generate, always check the messages object for warnings as well as errors.

The /report/download endpoint is being deprecated.

Report downloads currently return the report file as base64-encoded data directly in the API response. This approach is being replaced with a new endpoint that will return a short-lived download URL instead.

Base64 encoding increases the size of the file being transferred, and returning large files directly within API responses can tie up server resources that could otherwise be used to process other requests. Moving to short-lived download links provides a more efficient approach for report downloads.

The existing /report/download endpoint will continue to work during the transition period.

Details about the replacement endpoint, migration process, and sunset date will be provided separately. Integrations using /report/download should plan to migrate once the replacement endpoint becomes available.

You can view a log of your institution's recent API calls, including timing and any errors.

This can be a useful first place to check if your integration is experiencing:

A simple API request can be useful when confirming your API key and institution URL.

For example:

Replace {purl} and {apikey} with the values for your institution.

Because this example places the API key in the URL, use it only for testing in a secure environment.

For integrations, use the following header where supported:

For reliable and efficient API integrations:

This guide covers the general requirements and recommended practices for working with the ampEducator API.

For the complete technical reference, including available resources, methods, required parameters, return objects, and field definitions, see the:

ampEducator Developer API Reference