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 https //ampeducator com/api php before you begin before using the api an administrator must enable api access under institution config generate or copy the institution's api key from institution config keep your api key secure your api key provides access to your institution's data and should not be shared or exposed in client side code making an api request api requests are made using the following endpoint structure https //{purl} ampeducator com/api/{resource}/{action} where {purl} is your institution's unique ampeducator identifier {resource} identifies the section of the application you are accessing {action} identifies the operation you want to perform {parameters} are any additional values required by the action each endpoint in the developer api reference specifies whether it requires a get or post request and which parameters are required authentication your institution's api key is required to authenticate requests the api key can be provided using an http bearer token authorization bearer {apikey} for endpoints that accept parameters, the api key may also be included as a request parameter https //{purl} ampeducator com/api/{resource}/{action}?apikey={apikey}&{parameters} for integrations, using the authorization bearer header is recommended where supported form encoded post request curl x post \\ "https //{purl} ampeducator com/api/{resource}/{action}" \\ h "content type application/x www form urlencoded" \\ h "authorization bearer {apikey}" \\ d "{parameters}" json post requests endpoints that accept post requests can also receive a json object as the request body use the following headers authorization bearer {apikey} content type application/json example curl x post \\ "https //{purl} ampeducator com/api/{resource}/{action}" \\ h "content type application/json" \\ h "authorization bearer {apikey}" \\ d '{ json object }' api responses the api returns responses as json a typical response follows this structure { "responsecode" 200, "messages" { "general" \[], "warning" \[], "errors" \[], "witherrors" false, "totalmessages" 0 }, "action" "string", "query" {}, "body" "string", "page" 1, "totalpages" 1, "totalrecords" 0, "totalms" 0, "data" \[] } response fields responsecode — the http response code returned for the requested action messages — general, warning, and error messages related to the request action — the action that was requested query — the parsed query parameters body — the contents of the request body page — the current page of returned data totalpages — the total number of pages available totalrecords — the total number of objects available totalms — the total queue and execution time in milliseconds data — the objects returned by the api always check the messages object for warnings or errors that may provide additional information about the request response codes 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 filtering results 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 get /student/get?status=active multiple filters can be combined get /student/get?currentstatus=active\&program=nursing 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 page limit orderby orderdir pagination and ordering list endpoints return results one page at a time pagination the following parameters can be used to control pagination for example \&page=2\&limit=500 a paginated response includes information such as { "page" 2, "limit" 500, "totalrecords" 17342, "totalpages" 35, "data" \[] } 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 ordering results results can be ordered using orderby and orderdir for example \&orderby=studentid\&orderdir=asc or in a json request { "orderby" "studentid", "orderdir" "asc" } orderdir accepts asc desc 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 request handling and rate limits api requests are managed on a per institution basis to maintain reliable performance request queuing 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 http 429 too many requests a request that waits too long in the queue may receive http 504 gateway timeout if either occurs, wait before retrying the request and consider reducing the number of concurrent calls rate limiting 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 temporary blocks for sustained excessive traffic 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 working with large data sets when retrieving larger amounts of data use filtering and pagination to retrieve multiple records in fewer, larger requests use batch endpoints where available instead of requesting individual records one at a time request a larger limit, up to 500, for bulk or synchronization operations avoid large bursts of concurrent requests add pacing or delays between requests when a batch approach is not available implement retry with backoff for temporary 429 and 504 responses 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 report generation 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 report downloads 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 api usage and troubleshooting 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 400 responses 429 responses slower than expected api calls other unexpected request behaviour testing an api call a simple api request can be useful when confirming your api key and institution url for example https //{purl} ampeducator com/api/location/get?apikey={apikey} 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 authorization bearer {apikey} recommended practices for reliable and efficient api integrations use filtering to retrieve only the records you need use pagination and larger page limits when retrieving larger data sets avoid repeatedly requesting individual records when a filtered or batch request can be used avoid unnecessary concurrent requests add pacing between calls where appropriate implement retry with backoff for 429 and 504 responses review the api usage log when troubleshooting unexpected responses or performance check the messages object for warnings as well as errors api reference 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 https //ampeducator com/api php