Zylo API

Number of APIs: 13

The Zylo platform provides a modern, RESTful API to work with your subscription data. The API is built using resource-oriented URLs that are protected by HTTPS transport security and authenticated via secure tokens.

Authentication

Zylo uses API tokens for authentication. You can retrieve your token ID and token secret by going to your account, selecting Admin from the main menu, and then going to the Company Tokens tab. Once you select Request Token, you can create a named token and assign the permissions you wish to associate with it. You will need to record the Token ID and Token Secret in order to authenticate against the API. Please note that the Token Secret will only be displayed when the key is generated - if you do not record it then you will need to generate a new token in order to use the API.

In order to authenticate individual API requests, you need to add a bearer token to your request. The value of the bearer token is your Token ID and Token Secret separated by a colon, i.e.:

curl 'https://api.zylo.com/v1/subscriptions' \
-H "Authorization: Bearer <TOKENID:TOKENSECRET>"

A successful response will return a json object returning all available subscription information.

Errors

If you receive an error from the API, a response code will be set indicating the error with a payload that will optionally contain additional error details. The following is an example error message:

{"statusCode":401,"message":"Unauthorized"}

The API documentation for individual routes contains any potential error codes for that route.

Pagination

Resources that have a list method allow for the pagination of result sets. Each of these methods have a standard way of controlling pagination for the resource. When querying a list method, you will receive a response called nextPageToken which gives you a token that can be used to retrieve the next page of results.If there are no further results for a given requests, then an empty string "" will be returned for this value.

To retrieve the next set of results using the nextPageToken, pass the nextPageToken value as a pageToken in the query string, i.e.:

curl 'https://api.zylo.com/v1/subscriptions?pageToken=NEXT_PAGE_TOKEN_VALUE' \
    -H "Authorization: Bearer <TOKENID:TOKENSECRET>"

Request IDs

Each API request has a request identifier associated with it under the response header: zylo-request-id. If you assistance with a particular API request, please provider the request identifier along with your inquiry.

Versioning

All APIs are versioned and contain the version of the API directly in the URI. APIs are guaranteed to be backwards compatible across all major version numbers.

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 Qodex, 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:

Field	Type
firstName	string
lastName	string
email	email
lastActivityDate	ISO-8601 date
daysActiveOfLast30	numeric
licenseNames	string (comma separated)
isPaidUser	true/false (all lowercase)

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.