Overview of how to create and submit a report.
Below is a step-by-step guide on how to create, submit and download a report job from Zylo.
1. Choose an Authentication Method
To create a report, the request must include an authentication token. The authentication token describes what resources the report can access when building the file.
Below are the different authentication methods:
If you try to build or download a report without the proper permissions, the request will be rejected. For more info, visit
2. Creating a Report Query
- You must have "admin" permission for the Enterprise API, additional permissions may be needed based on resources requested.
A report job must include a query which tells Zylo how you want to generate the report.
The query is based upon Zylo's Query syntax. There is a comprehensive guide on how to create a query to be used when creating a report job.
Once you have created a query to be used in the report, it is important to first validate that the query is valid.
The Validate Report will check to make sure that your query is formatted correct, that your token has the correct permissions, and validates the fields being returned.
The validation endpoint does not run a job.
Below is an example of a request to the validation endpoint:
curl --request POST \
--url https://api.zylo.com/v2/reports/validate \
--header 'authorization: Bearer {token}' \
--header 'content-type: application/json' \
--data '{
"builder": {
"applications": {
"fields": [
{
"name": "category",
"as": "category"
}
],
"with": {
"payments": {
"fields": [
{
"name": "amount",
"op": "sum",
"as": "total_amount"
}
]
}
}
}
},
"sort": "+total_amount"
}'3. Submit a Report Job
- You must have "admin" permission for the Enterprise API, additional permissions may be needed based on resources requested.
Once you have built and validated a query, the next step would be to submit that report query as a job so that processing can start.
The Create Report Job endpoint takes in the report query that was created and submit it as a job.
There is a limit to 10 concurrent reports running at once for a company.
Below is an example of submitting a report:
curl --request POST \
--url https://api.zylo.com/v2/reports/jobs \
--header 'authorization: Bearer {token}' \
--header 'content-type: application/json' \
--data '{
"builder": {
"applications": {
"fields": [
{
"name": "category",
"as": "category"
}
],
"with": {
"payments": {
"fields": [
{
"name": "amount",
"op": "sum",
"as": "total_amount"
}
]
}
}
}
},
"sort": "+total_amount"
}'Take note of the reportJobId that is returned, that will be used in the next step to monitor the job's progress.
4. Monitoring the Progress
To know when a job is available for download, the job must be in a "Completed" state.
Using the above reportJobId from the previous step, you can monitor the report's progress.
Below is an example request to see the job's progress:
curl --request GET \
--url https://api.zylo.com/v2/reports/jobs/{reportJobId} \
--header 'authorization: Bearer {token}' \
--header 'content-type: application/json' \The above will include a value called status.
- "E" - The job has errored and will be not be available for download.
- "P" - The job is still processing.
- "C" - The job is complete and available for download.
When the status is returned back as "C", continue to the next step to download your report.
5. Downloading the Report
To download a report, use the reportJobId from the previous two steps and make a call to the Download Report Job endpoint.
Below is an example request:
curl --request GET \
--url https://api.zylo.com/v2/reports/jobs/{reportJobId}/download \
--header 'authorization: Bearer {token}' \
--header 'content-type: application/json' \The response will include a downloadUrl, which is a secure URL used to download the contents of your CSV.
The URL will expire after 5 minutes.