Summary
The Report API is designed so that you post a JSON request data to it, and receive a response with the data defined in the JSON request. The default response format is also JSON, but you can get a CSV response if you want.
Note that CSV, being a "flat" data format, is limited to only the values in the top-most layer of the API response, so if your request includes complex data, CSV will not really work for you. There is syntax to request sub-element fields as top-level fields, so it is possible to create "flat" CSV data if you really need or prefer that.
Resources
The API is built around "resources". You can think of these as roughly relating to database tables. Resources can be related to each other. For example, a Product resource is related to productRegistrations for that product… and productRegistrations are related to both Products and Users.
API URL
The URL of the API, where you will post your JSON data, is https://YourElevateSite.tld/api/reports/
We've set up a demo account and loaded it with a lot of test orders, for a number of products, spread out over a 6-month period, so that you can access that for testing and learning how to access the API. The URL of the API for that demo account is: https://demo.lv8test.commpartners.com/api/reports/
API Test Form
There is a test page, where you can manually paste in and edit JSON queries and see the resulting responses, so you can learn the API and refine your query before putting it into your automated scripts https://demo.lv8test.commpartners.com/api/reports/form
If you would like more information and pricing, please contact us at elevate-support@gocadmium.com
Elevate LMS Integrations
Custom Data Push
This is a module we can custom build for your Elevate site that sends information to your AMS in real-time, as events happen. There are four events that can trigger a Data Push in Elevate. These include (Fig.1):
- When a user registers for a product
- When a user starts a product
- When a user completes a product
- When a user earns a credit
Fig. 1 - Four Events That Trigger a Data Push.
This integration requires your AMS to have API "endpoints" to which we can send the information to. The first step is to discuss with your AMS what information from above you want sent, then to discuss where you want it to show up in your AMS. They should be able to advise whether they have, or are able to build for you, an API endpoint to receive that data. Once it is determined that the AMS can provide the needed API tools on their end, then we can begin working on the technical details.
Report API
Our Report API is a tool designed to allow you to extract data from Elevate at a specific interval. This pull of data can happen monthly, weekly, or daily.
Example Use Case
You set up a pull from Elevate to occur each night of all registrations and credits earned that happened in the LMS that previous day.
To Achieve This
Your AMS needs to be able to program custom actions to occur on a timed, recurring basis.
The Process Involves
Posting a JSON request data to the Report API, from which you will receive a response with the data defined in the JSON request. While the default response format is also JSON, you can also set it up to receive a CSV response if desired. Note that CSV, being a "flat" data format, is limited to only the values in the top-most layer of the API response, so if the request includes complex data, CSV is not the best method.
Resources
The API is built around "resources." Think of these as roughly relating to database tables. Resources can be related to each other. For example, a Product resource is related to productRegistrations for that product and productRegistrations are related to both Products and Users.
API URL
The URL of the API where a client will post their JSON data, is https://YourElevateSite.tld/api/reports/
We’ve also set up a demo account and loaded it with test orders for a number of products, spread out over a 6-month period, so that a developer can run tests.
The URL of the API for that demo account is: https://demo.lv8test.commpartners.com/api/reports/
API Test Form
We've also created a test page where a client may manually paste in and edit JSON queries and see the resulting responses, in order to learn the API and refine queries before putting it into their automated scripts.
https://demo.lv8test.commpartners.com/api/reports/form
Your First Query
Below is a simple query that lists all the Products on the demo site:
{
"api_key":"z12k4Si25nOcDfxoqEk2tYeQe8DnAVur",
"format":"json",
"resource":"product",
"fields":{
"id" : true,
"remote_accounting_code" : true,
"title" : true
}
}
The first few fields are:
api_key: This is a key to grant access. The key shown is for the demo account. For your specific client key, as your Project Manager.
format: This will be either json or csv, but defaults to json.
resource: This will be the data resource that is the "root" of the request, i.e. the top layer of your data.
A resource can have many related sub-resources from which you can request data fields. Available resources include "product", "productRegistration", "user", "accountCode", "category", "assetAccess".
fields: is a list of the fields that you want included in the result.
More Complex Query Example
The sample below is for retrieving a summary report, listing all AccountCodes (GL accounts, to one of which each product should be assigned), with a total revenue and total number of orders/registrations for each, within a given date range (the previous month - Sept 2014):
{
"api_key":"z12k4Si25nOcDfxoqEk2tYeQe8DnAVur",
"format":"json",
"resource":"accountingCode",
"fields":{
"id" : true,
"revenue":true,
"number_registrations":true
},
"filters":{
"products.productRegistrations.transaction_at":{">=":"2014-09-01 00:00:00","<=":"2014-09-30 23:59:59"}
}
}
In the query above, total_revenue and number_registrations are both summary fields for the total revenue and number of registrations for all orders for each Accounting Code defined on the site. We've also added a new parameter, "filters".
filters: a list of requirements, like the "where" clause of an SQL query, to limit the results. In the case above, we are limiting the results to orders that were paid in the previous month. Below is a similar request for a summary by Product, rather than Accounting Code, and adding a filter to only list products
with more than zero registrations in the specified date range.
{
"api_key":"z12k4Si25nOcDfxoqEk2tYeQe8DnAVur",
"format":"json",
"resource":"product",
"fields":{
"id" : true,
"title":true,
"revenue":true,
"number_registrations": true
},
"filters":{
"productRegistrations.transaction_at":{">=":"2014-09-01 00:00:00","<=":"2014-09-30 23:59:59"},
"number_registrations":{">":0}
}
}
The following request combines the above two requests. It lists accounting codes and their revenue and registrations, with sub-elements listing specific products within those Account Codes, and each product's revenue and registration.
{
"api_key":"z12k4Si25nOcDfxoqEk2tYeQe8DnAVur",
"format":"json",
"resource":"accountingCode",
"fields":{
"id" : true,
"products.total_revenue":true,
"products.total_number_registrations":true,
"products":{
"title":true,
"total_revenue":true,
"total_number_registrations":true
}
},
"filters":{
"products.productRegistrations.transaction_at":{">=":"2014-09-01 00:00:00","<=":"2014-09-30 23:59:59"},
"products.number_registrations":{">":0}
}
}
Here is an example of a "detail" report that lists all registrations in a date range with information about the user, the product, and the purchase:
{
"api_key":"z12k4Si25nOcDfxoqEk2tYeQe8DnAVur",
"format":"json",
"resource":"productRegistration",
"fields":{
"product.title" : true,
"product.remote_accounting_code" : true,
"transaction_at" : true,
"price_before_discount": true,
"amount_discounted": true,
"price_after_discount": true,
"user.member_id":true,
"user.firstname": true,
"user.lastname": true,
"user.email": true,
"payment.payment_method":true,
"payment.card_type":true,
"payment.card_partial":true,
"payment.transaction_id":true
},
"filters":{
"transaction_at": {">=":"2014-09-01 00:00:00","<=":"2014-09-30 23:59:59"}
}
}
A report listing user who purchased anything in a data range, and sub-elements showing what they purchased, and total revenue of their purchases:
{
"api_key":"z12k4Si25nOcDfxoqEk2tYeQe8DnAVur",
"format":"json",
"resource":"user",
"fields":{
"firstname":true,
"lastname":true,
"productRegistrations":{
"price_after_discount":true,
"transaction_at":true,
"product.title":true,
"total_revenue":true
}
},
"filters":{
"productRegistrations.transaction_at":{"date":["2014-06","2014-10"]}
}
}
Date Range Filtering Shortcuts - To filter by a date range, you can also use the "date" filter.
"filters":{
"transaction_at": {"date" : ["2014-02", "2014-05-31"]}
}
This will include all results between 2014-02-01 00:00:00 and 2014-05-31 23:59:59. You can also omit the first or second parameter to have "before date" or "after date" filter.
Example:
"filters":{
"transaction_at": {"date" : [null, "2014-05-31"]}
}
This will include all results before 2014-05-31 23:59:59.
Few more examples:
"filters":{
"transaction_at": {"date" : ["2014", "2014"]}
}
This will include all results in 2014 year, i.e. between 2014-01-01 00:00:00 and 2014-12-31 23:59:59.
"filters":{
"transaction_at": {"date" : ["2014-02", null]}
}
This will include all results starting from February 2014, i.e. all the dates after 2014-02-01 00:00:00.
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article