Introduction
Magnit Reporting as a Service (RaaS) supports asynchronous API calls for report data retrieval. Our API uses OAuth2.0 authentication and returns JSON, ensuring secure and efficient access to your data. This page is designed to guide client representatives managing reports and technical teams integrating APIs through the functionalities and benefits of RaaS.
Overview
Authentication
- A Client User with RaaS Permission will maintain API keys in their Magnit Platform profile. This includes a Client Key, Client Secret, and Credential Key. The Credential Key generates after saving your credentials. To request RaaS Permission, contact your Program Representative.
- Keys are valid for a default maximum of 90 days but can be modified at the client level to 30 or 60 days.
- If your current credentials are valid for more than a week, when you generate new ones, the old ones will be extended to expire one week after the new ones are created. This allows you to test and validate the new credentials. You can also deactivate the old credentials at any time before their expiration.
Report Setup
- RaaS is available for Customizable Reports in the Magnit Platform. Instructions on creating and saving a Customizable Report can be found in the Magnit Platform User Guide.
- RaaS reports should have unique naming conventions to differentiate them from other report types.
- Once the report has been built and saved, click on the RaaS link to view token and report-specific API endpoints.
- If you rename a column in the report, the JSON key in the response will reflect the modification.
- To access data for your entire client, ask your Program Representative to add the Report Admin view to your profile, the “View all Records Under Department/Cost Center” permission, and enable the “Assign all Active Departments” setting. Depending on the number of departments, this could take up to 24 hours to take effect.
- If a report is shared with you through the Magnit Platform and you want to enable RaaS, you must save it with a new name to become the Report Owner
Sharing reports
As the Report Owner it is recommended that you share the reports within the Magnit Platform with other Client Users to prevent unexpected disruption to your RaaS deliverables (information on sharing reports is available in the Magnit Platform User Guide).
- Modifications to a shared report will be visible to everyone who has access to it.
- Should your Magnit profile become inactive, the API will no longer retrieve report data. Please be aware that direct login users must access the platform at least once every 60 days to remain active.
- The recipient of the shared report must save it under a new name to become the Report Owner and enable RaaS (the API endpoints will change with a new unique ID). Users should have the same profile settings to guarantee consistent report results.
Miscellaneous
- If you are accessing the Magnit Platform in a language other than US English and save a customizable report, the JSON keys will still be in US English, unless you rename the columns within the report page into the required language.
- If it is decided that a new Client User profile will maintain RaaS reports, and your client has a user integration, the RaaS profile/s must be specially configured to remain active when the integration runs (typically done through a manager custom field). Contact your Program Representative for more information.
Scheduling
The system calling the API will need to use its own scheduling method. The Magnit Platform Report Scheduling feature supports other export formats (xlsx, csv, etc.).
Process
Authentication
Make a POST call to the token endpoint provided in the RaaS page of your report. The request body should have JSON format type. The three components of your RaaS API Keys from your Magnit profile should be used as header keys to authenticate, and if successful, an access token will be returned.
Sample Request:
{
"CredentialKey": 1234,
"ClientKey": "XXXX",
"ClientSecret": "XXXX"
}
Once you have the access token you can call the three RaaS API endpoints to request and retrieve report data. When making the calls, set the authentication type as Bearer Token.
Request Report Data
Make a POST call to request the report. If successful, you will get a RunID in the response.
Sample Response:
{
"runid": "8efd721e-9a1b-43a2-b6a4-d17dca59343b",
"message": "Your request has been added to the queue, please refer to the Run ID."
}
Check the Status
Make a GET call to check the status, including RunID as a parameter in the API endpoint.
Sample Response:
{
"runid": "8efd721e-9a1b-43a2-b6a4-d17dca59343b",
"reportid": 70183,
"status": "Completed",
"message": "Report generation is complete. Please retrieve the report data."
}
Retrieve the Report
Make a GET call to retrieve the report data, including RunID as a parameter in the API endpoint. Data will be returned in JSON format.
Pagination
- You have the option to retrieve the report data with pagination.
- Pagination is managed through “page” and “size” query string parameters, with the default value for page set to 1 and the default value for size set to 5,000. These parameters can be adjusted to retrieve a specific range of data.
- Please note that these parameters are case-sensitive and must be in lower-case.
- Next Page: The response includes a “nextpage” value, which provides the URL for the next page of results.
- Page: The “page” parameter allows you to retrieve data from a specific page based on the page size.
- Size: The default value is 5,000 records per page, with a maximum limit of 20,000 records per page to ensure reasonable response times. If a request specifies a size greater than this limit, the maximum value will be applied instead.
- Total Records: The “totalrecords” field indicates the total number of records without pagination.
- Total Pages: The “totalpages: indicates the total number of pages based on the page size.
- Data Element: The “data” node contains the report records.
- Sample Pagination URL: https://{baseurl}/reports/{reportid}/requests/{runid}/retrievePagedData
- Sample Pagination URL with page and size parameters: https://{baseurl}/reports/{reportid}/requests/{runid}/retrievePagedData?page=2&size=2000
Features & Standards
Verbs
Supported verbs are POST and GET.
Error Response
- Error response uses "Content-Type" as "application/problem" and JSON format.
- 2XX status codes are used for successful request processing.
- 4XX HTTP status codes are used for client errors with a specific resource
- 500 HTTP status code is used for server errors.