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.

The Zylo API can be easily used with the Postman application in lieu of a terminal prompt. When using the Postman application, please use the Import button in the top left corner, next to your workspace's name. Use the Raw text tab to submit the cURL commands. Importing cURLs will automatically populate the necessary fields for you.

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.

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.

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>'

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.

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 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.

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')"

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:

{ "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.