This document describes the Magpi Outbound API, which allows Magpi Enterprise users client applications to pull information from the Magpi server at app.magpi.com . To push data to Magpi's servers, you will need to use the Magpi Inbound API.
To fetch subform data, please use version 2 url on the Get Survey Data API.
We are still working on version 2 of the List Questions API which will include subform questions.
The Magpi API allows Enterprise users' client applications to request :
- a list of a forms
- a list of questions for a specified form
- form data
The data is returned as an XML representation. All API calls must take place over HTTPS .
To use the API,first create an accesstoken on the API settings page - the page can be accessed by clicking the Settings link at the top of any Magpi page, and then choosing the API tab. Enter the name of the accesstoken e.g admintoken and click generate.The accesstoken is used together with the username of the user who generated it to authenticate an API call.
- List Surveys
Description:
This action gets a list of all the Magpi forms for which the user has data view access.
version 1 URL: https://app.magpi.com/api/surveys/
Parameters:
| Name | Description |
| username | The account username |
| accesstoken | The accesstoken genetated on the site.Each accesstoken is associated with the user who generated it |
Allowed HTTP Method: POST
Sample curl command:
curl -X POST -d "username=testuser&accesstoken=yt72xk536RUPpKscMUof" https://app.magpi.com/api/surveys
Sample Output:
62TiaTesttia@aidn.org
186Malezi_Boratia@datadyne.org
187Malezi_Bora2tia@datadyne.org
- List Questions
Description:
This action gets a list of all questions for the specified form.
version 1 URL: https://app.magpi.com/api/questions/
Parameters:
| Name | Description |
| username | The account username. |
| accesstoken | The accesstoken genetated on the site.Each accesstoken is associated with the user who generated. |
| surveyid | The surveyid is not the form's name.The surveyid can be obtained from the list of forms generated in 1 above. |
Allowed HTTP Method: POST
br>
Sample curl command:
curl -X POST -d "username=testuser&accesstoken=yt72xk536RUPpKscMUof&surveyid=1292" https://app.magpi.com/api/questions/
Sample Output:
22203drop downdrop
22204Radio Questionradio
22205Check boxbox
22212EndEnd
- Get Survey Data
Description:
This action gets the data for the form specified in the request parameters.
Allowed HTTP Method: POST/GET
1. version 1 URL: https://app.magpi.com/api/surveydata/
Parameters:
| Name | Description |
| username | The account username. |
| accesstoken | The accesstoken generated on the site. Each accesstoken is associated with the user who generated. |
| surveyid | The surveyid is not the survey's name. The surveyid can be obtained from the list of forms generated in 1 above. |
| startdate | Start date of the data to be returned. Filtering is done based on the DateStamp and is inclusive.(Optional). The date format should be the same one as the one on the data tab/ The date format should be the same one as the one on the data tab. Format is YYYY-MM-DD. e.g 2020-01-01 |
| enddate | End date of the data to be returned. Filtering is done based on the DateStamp and is inclusive. (Optional). Format is YYYY-MM-DD. e.g 2020-12-31 |
Startdate and Enddate Note: This parameters are optional but MUST be used together for accurate results in the filter.
2. version 2 URL: https://app.magpi.com/api/surveydata/v2
Note: Version 2 of the Get Survey Data, allows you to fetch sub-form data.
Parameters:
| Name | Description |
| username | The account username. |
| accesstoken | The accesstoken generated on the site. Each accesstoken is associated with the user who generated. |
| surveyid | The surveyid is not the survey's name. The surveyid can be obtained from the list of forms generated in 1 above. |
| startdate | Start date of the data to be returned. Filtering is done based on the DateStamp and is inclusive.(Optional). The date format should be the same one as the one on the data tab/ The date format should be the same one as the one on the data tab. Format is YYYY-MM-DD. e.g 2020-01-01 |
| enddate | End date of the data to be returned. Filtering is done based on the DateStamp and is inclusive. (Optional). Format is YYYY-MM-DD. e.g 2020-12-31 |
| start | Start record data count to be returned. For example; if the total records returned are a total of 3000 and the start is initialized as 2000, records to be returned will be from 2000 to 2100. |
| limit | This is the limit of record data to be returned. Note: the default limit is 100 and the maximum limit of record data is 500. |
| sort | Allows user to sort data by specific field. Default value: lastSubmission. Possible values: dateCreated, startRecord, endRecord, lastSubmission, lastSubmitter, createdBy. Parameter name: order. Default value: desc. Possible values: desc, asc. |
Optional parameters: startdate, enddate, start and limit.
Startdate and Enddate Note: MUST be used together for accurate results in the filter.
Sample curl command:
version 1
curl -X POST -d "username=testuser&accesstoken=yt72xk536RUPpKscMUof&surveyid=1292" https://app.magpi.com/api/surveydata/
version 2
curl -X POST -d "username=testuser&accesstoken=yt72xk536RUPpKscMUof&surveyid=1292" https://app.magpi.com/api/surveydata/v2
Sample Output:
77gnjuguna@datadyne.org2010-03-17 10:41:44.0~Bongyoungstock5ad21.02.011.00.0,0.02009-11-17~76gnjuguna@datadyne.org2010-03-15 11:35:12.0~Capemountweaned3 El mediokhjgjkhkmh235465.06.023.00.0,0.02010-03-15~
.
.
.