Overview

In Zylo, alerts notify users about important events related to applications and contracts. The API supports creating email alerts for three types of notifications: renewal alerts, transaction alerts, and contract-renewal alerts.

Alert Types

Below is a table describing each type of alert available through the API:

Type	Description	Required Association
`renewal`	Alerts users when an application's contract is approaching its renewal date.	`application_id`
`transaction`	Alerts users when an application has a transaction (charge) exceeding a specified threshold.	`application_id`
`contract-renewal`	Alerts users when a contract is approaching its renewal date.	`contract_id`

Important Constraints

Application vs Contract Association

Alerts must be associated with either an application or a contract, but not both:

application_id and contract_id are mutually exclusive - you cannot provide both in the same request
renewal and transaction types require application_id to be set
contract-renewal type requires contract_id to be set

Method Restrictions

Currently, the API only supports creating email alerts:

You can create alerts with method: "email"
You can view alerts of any method (email, slack, teams)
You can delete alerts of any method
You cannot create slack or teams alerts through the API

End Date Requirements

Both renewal-based alert types require their associated resource to have an end date configured:

renewal alerts require the application to have at least one active contract with an end_date set
contract-renewal alerts require the contract to have an end_date set

These dates are necessary for the alert system to calculate when to send renewal notifications.

Alert Settings Structure

The settings property varies based on the alert type. Below are the required structures for each type:

Renewal Alert Settings

For both renewal and contract-renewal types:

{
  "recipients": [
    { "email": "user@example.com" },
    { "email": "manager@example.com" }
  ],
  "renewal": {
    "notification_period": [30]
  }
}

Valid notification_period values: 7, 15, 30, 60, 90, 120, 150, 180, 220, 240 (days before renewal)

Transaction Alert Settings

For transaction type:

{
  "recipients": [
    { "email": "finance@example.com" }
  ],
  "transaction": {
    "charge_type": "all",
    "transaction_threshold": 1000
  }
}

Valid charge_type values:

all - All transaction types
ap - Accounts payable transactions only
expense - Expense transactions only

transaction_threshold requirements:

Must be an integer
Must be at least 1

Creating Alerts

Creating a Renewal Alert

POST /v2/alerts

{
  "application_id": "app-uuid-here",
  "type": "renewal",
  "owner": "owner@example.com",
  "memo": "Salesforce renewal coming up",
  "settings": {
    "recipients": [
      { "email": "procurement@example.com" }
    ],
    "renewal": {
      "notification_period": [60]
    }
  }
}

Notes:

The owner field is required and must be a valid email address for a user in your company
The method field is automatically set to "email" and cannot be manually specified
The application must have at least one active contract with an end_date set

Creating a Transaction Alert

POST /v2/alerts

{
  "application_id": "app-uuid-here",
  "type": "transaction",
  "owner": "finance@example.com",
  "memo": "High-value Salesforce charges",
  "settings": {
    "recipients": [
      { "email": "finance@example.com" },
      { "email": "manager@example.com" }
    ],
    "transaction": {
      "charge_type": "all",
      "transaction_threshold": 5000
    }
  }
}

Creating a Contract-Renewal Alert

POST /v2/alerts

{
  "contract_id": "contract-uuid-here",
  "type": "contract-renewal",
  "owner": "contracts@example.com",
  "memo": "Enterprise agreement renewal",
  "settings": {
    "recipients": [
      { "email": "contracts@example.com" }
    ],
    "renewal": {
      "notification_period": [90]
    }
  }
}

Notes:

Uses contract_id instead of application_id
The owner field is required and must be a valid email address for a user in your company
The contract must have an end_date set

Updating Alerts

Currently, only the following properties can be updated:

owner - The email address of the alert owner
memo - The description or note for the alert
settings - The alert configuration (recipients, thresholds, etc.)

Example:

PATCH /v2/alerts/{alertId}

{
  "owner": "newowner@example.com",
  "memo": "Updated renewal notification",
  "settings": {
    "recipients": [
      { "email": "newowner@example.com" }
    ],
    "renewal": {
      "notification_period": [30]
    }
  }
}

Notes:

You cannot change the alert type after creation
You cannot change application_id or contract_id after creation
You cannot change the method after creation
The settings structure must match the alert's type

Common Validation Errors

Error	Reason
`Alert must have either application_id or contract_id`	Neither `application_id` nor `contract_id` was provided
`Alert must have either application_id or contract_id, not both`	Both `application_id` and `contract_id` were provided
`Type must be "renewal" or "transaction" when application_id is provided`	Invalid type for application-based alert
`Type must be "contract-renewal" when contract_id is provided`	Invalid type for contract-based alert
`Renewal alerts require the application to have a contract with an end_date set`	The application has no active contracts with end dates
`Contract-renewal alerts require the contract to have an end_date set`	The contract is missing an end date
`Settings must include a recipients property`	The `recipients` array is missing
`Recipients array must contain at least one recipient`	The `recipients` array is empty
`Invalid email address in recipients`	One or more recipient emails are malformed
`Notification period must be one of: 7, 15, 30, 60, 90, 120, 150, 180, 220, 240`	Invalid notification period value
`Transaction threshold must be at least 1`	Transaction threshold is 0 or negative