Subscriptions

Subscriptions are configured instances of subscriptions that are created in the Zylo user interface. Subscriptions will usually have a 1:1 relationship to a given application, but you also may have multiple subscriptions to the same application within your organization.

Data Exports

Zylo provides the ability to retrieve the current state of user level subscription usage and utilization. Due to the size of the data, the subscription export is an asynchronous workflow where you first create an export job and then retrieve the results of the job when it is complete.

An example workflow for retrieving subscription data would be to first create the export job (note that in the URL, we are using the - character to denote that we want to create an Export Job for all Subscriptions. If you wish to just export data for a specific subscriptions, then you can pass it's ID in the URL instead):

$ curl -i -X POST \
  https://api.zylo.com/v1/subscriptions/-/exportJobs \
  -H "Authorization: Bearer <TOKEN:SECRET>"

which will return the following payload:

{
  "id": "8f42b1f6-06a4-465a-aff2-83be8fcf0886",
  "name":"subscriptions/*/exportJobs",
  "status":"IN_PROGRESS",
  "createTime": "2020-01-01T12:00:00+00:00",
  "companyId": "9234806a4-465a-aff2-83be8fcf0886",
}

Once you have the ID for the job, you can query the endpoint to see the status of the export:

$ curl -i -X GET \
  https://api.zylo.com/v1/subscriptions/-/exportJobs/2F8f42b1f6-06a4-465a-aff2-83be8fcf0886 \
  -H "Authorization: Bearer <TOKEN:SECRET>"

When the status has been updated to COMPLETE, a downloadUri property will appear on the job. You can retrieve the data from that URL for 7 days before the link expires:

$ curl -o export.csv "$(curl -s -H "Authorization: Bearer <TOKEN:SECRET>" "https://api.zylo.com/v1/subscriptions/-/exportJobs/2F8f42b1f6-06a4-465a-aff2-83be8fcf0886" | jq -r ".downloadUri"

Usage Connect Data Imports

In order to import data to an application, you must first create a Usage Connection for that application in Zylo. After logging into Zylo, select the Connect option from the side nav and the Connections option from the sub-nav. From the Connections page, select Add Connection and create a new connection for the application that you are looking to import data to.

Data Imports (Legacy)

Important Note: Data imports is a legacy feature that is retired but will continue to be supported for existing customers as of 6/11/2024. If you are looking to import usage data into your Zylo instance, please see the Usage Connect Imports section for more information.

In order to import data to a subscription, you must first associate the subscription with the API Integration. After logging into the Zylo application, select the Integrations option from the main menu. From the Utilization category, find the API Integration option and click Connect. Once you've arrived in the connection dialog, either create a new subscription or select one of your existing subscriptions in order to make it eligible for integration via API.

To get started with importing data to the subscription, you first create an import job:

$ curl -X POST "https://api.zylo.com/v1/subscriptions/9f797a9a-334a-44c1-81aa-1e4afdcb8595/importJob" -H  "accept: application/json" -H  "Authorization: Bearer <TOKEN:SECRET>" -d ""
which will return the payload:

This will return the following JSON result:

{ "id": "fa28d004-ec40-4c37-9603-f2cce9ed22aa", "name": "subscriptions/587d9c21-1c5e-4928-8fe9-3d1eba016d19/importJob", "companyId": "adc89494-3316-434c-b7a6-4aae12d12e86", "subscriptionId": "587d9c21-1c5e-4928-8fe9-3d1eba016d19", "status": "OPEN", "createTime": "2021-05-24T20:14:30.886Z", "updateTime": "2021-05-24T20:14:30.886Z" }

and then upload a CSV file to the job to the import job ID returned from the previous create call:
```bash
$ curl -X POST "https://api.zylo.com/v1/subscriptions/9f797a9a-334a-44c1-81aa-1e4afdcb8595/importJob/f8537200-3b75-4d2c-9caf-9abf87025cb0" -H  "accept: application/json" -H  "Authorization: Bearer <TOKEN:SECRET>" -H  "Content-Type: multipart/form-data" -F "file=@import_file.csv;type=application/vnd.ms-excel"

If you are using Postman, you can leave the file -F option and parameters unmodified for ease. The cURL will generate a file uploader for you in the Body tab of your request.

The CSV file should contain the following fields:

The format of the CSV file is documented as part of the route, but you can get an example file by exporting data from one of your existing subscriptions. Once a file has been uploaded to the job, you can check the status of the job:

curl -X GET "https://api.zylo.com/v1/subscriptions/9f797a9a-334a-44c1-81aa-1e4afdcb8595/importJob/f8537200-3b75-4d2c-9caf-9abf87025cb0" -H  "accept: application/json" -H  "Authorization: Bearer <TOKEN:SECRET>"

If the job status returns COMPLETE_WITH_ERRORS, then you will be provided with a URL to download a file that contains the error information for the job. The error information will provide a detailed list of errors for all of the rows that failed to import.

If the job status returns a 400 - Bad Request error, a message will be provided to briefly explain why the request could not be completed. In most cases, a syntax error is the source and the cURL command should be reviewed before resubmitting.