Usage Connect Overview

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

Creating via Application

Usage Connect integrations do not need to be created via API and can be created within the application.

If you wish to create the Usage Connect integration via API, follow the below steps.

1. Fetching the `application_id`

Pre-requisites

Token must have the "applications:write" permission to create a new Application.
Token must have the "applications:read" permission to fetch the id for an Application.

Usage Connect integrations are connected to an existing Application in your environment. If the Usage Connect integration is importing usage data for an Application that does not currently exist in your environment, one will need to be created.

To fetch the id to use for creating a Usage Connect integration, make a call to the Get Applications endpoint and search for the Application you wish to upload usage data for.

Once you have found the application, copy the "id" field from the response.

2. Create Usage Connect integration mappings

Usage Connect integrations require a mappings field to be passed in. The purpose for this field is to map your CSV headers to Zylo Data Fields, configure the data type, display key and tooltip.

Zylo has several fields that are created by default. These fields cannot have their display key or tooltip overriden. Below is the list of default fields.

first_name
last_name
full_name
email
employee_id
department
created_at
is_admin
license_names

For example, if there is a CSV you want to import that looks like the below:

Email,Department,"Last Login","Custom Field"
example@zylo.com,Engineering,2025-04-25,example

The mappings field will look like this:

[
    {
        "from": "Email",
        "to": "email",
        "type": "email",
    },
    {
        "from": "Department",
        "to": "department",
        "type": "text",
    },
    {
        "from": "Last Login",
        "to": "last_activity_date",
        "type": "date yyyy mm dd",
    },
    {
        "from": "Custom Field",
        "type": "text",
        "displayKey": "My custom field.",
        "tooltip": "My text custom field."
    }
]

📘
Important Note
Take note that a default Zylo Data Field such as email and department require a "to" field, but a custom field does not.
A mapping that is mapped to "email" is required.

Below is a list of all data types:

Type	Example
boolean	`true`
date mm dd yyyy	`"12-30-2023"`
date dd mm yyyy	`"30-12-2023"`
date dd mmm yyyy	`"30-Dec-2023"`
date mmm dd yyyy	`"Dec-30-2023"`
date yyyy dd mm	`"2023-30-12"`
date yyyy mm dd	`"2023-12-30"`
email	`"example@zylo.com"`
integer	`1234`
array	`"example,test"`
text	`"example"`

📘
Important Note
An "email" field is required for a Usage Connect integration mapping. The "email" should be for the "to" and for the "type".

3. Creating Usage Connect integration

Pre-requisites

Token must have "integrations:write" permission.

To create a Usage Connect integration, use the Create Usage Connect Integration endpoint. An example usage of the endpoint is below.

curl --request POST \
     --url https://api.zylo.com/v2/usageConnect \
     --header 'Authorization: Bearer {token}'
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "application_id": {id for application},
  "mappings": {CSV mappings as described above}
}
'

The above will return the integration_id for the newly created Usage Connect integration.

4. Importing Usage Data

To start importing data into your newly created Usage Connect integration, follow the Import Usage Data guide.