Usage Connect Overview

Usage Connect integrations provides a way for Zylo users to upload their own application user data via CSV to an application.

1. Creating a Usage Connect Integration

Create via API

Pre-requisites

Token must have the "integrations:write" permission.

To create a Usage Connect integration, visit the Create Usage Connect page and follow the step-by-step.

Creating via Application

Pre-requisites

You must have "Integrations - Write" permission in the Zylo application.
This must be done in the Zylo UI currently.

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.

When prompted with Manual or Automatic option, choose the Automatic then choose "Zylo API".

📘
Important Note
The "Token Secret" that appears is for the Zylo Legacy API and is not used for the Zylo Enterprise API.

2. Fetching the `integrationId`

Pre-requisites

You must have "integrations:read" permission for the Enterprise API.

To import data to the Usage Connect integration, it is required to provide an integrationId.

To find the integrationId, make the below call using the "Get Integrations" endpoint.

curl --request GET \
     --url 'https://api.zylo.com/v2/integrations?type=usageconnect' \
     --header 'Authorization: Bearer {token}' \
     --header 'accept: application/json'

The response includes all Usage Connect integrations, find the Usage Connect integration that you want to import data into and copy the id value.

3. Creating an Import Job

Pre-requisites

You must have "integrations:write" permission for the Enterprise API.

To create an import job to start uploading data, you call the "Create an Import Job" POST request, like below:

curl --request POST \
     --url https://api.zylo.com/v2/usageConnect/{{integrationId}}/import \
     --header 'Authorization: Bearer {token}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "file_name": "example_file.csv"
}

The response includes a URL to upload your CSV and other parameters that are required when uploading the file. An example of the response is below, be sure to copy this response to use in the next step:

{
  "import_id": "52907745-7672-470e-a803-a2f8feb52944",
  "import_upload_url": "https://example-bucket.s3.region.amazonaws.com/",
  "import_metadata": {
    "policy": "<POLICY>",
    "signature": "<SIGNATURE>",
    "date": "<DATE>",
    "credential": "<CREDENTIAL>",
    "algorithm": "<ALGORITHM>",
    "key": "<UPLOAD KEY>",
    "securityToken": "<SECURITY TOKEN>"
  },
  "import_status_endpoint": "https://api.zylo.com/v2/usageConnect?id=52907745-7672-470e-a803-a2f8feb52944"
}

The credentials above expire in 5 minutes and the file size is limited to 3GB.

4. Upload CSV to Import Job

The CSV uploads requires a multipart/form-data request using the response metadata above to validate the import.

Below is an example using the response from Step 3 in a request to upload a CSV file:

curl --request POST \
     --url https://example-bucket.s3.amazonaws.com/ \
     --header 'accept: application/json' \
     --header 'content-type: multipart/form-data' \
     --form 'key=<UPLOAD KEY>' \
     --form 'X-Amz-Algorithm=<ALGORITHM>' \
     --form 'X-Amz-Credential=<CREDENTIAL>' \
     --form 'X-Amz-Date=<DATE>' \
     --form 'Policy=<POLICY>' \
     --form 'X-Amz-Signature=<SIGNATURE>' \
     --form 'Content-Type=text/csv' \
     --form 'X-Amz-Security-Token=<SECURITY TOKEN>' \
     --form 'file=@example_file.csv'