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:

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": "[email protected]" },
    { "email": "[email protected]" }
  ],
  "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": "[email protected]" }
  ],
  "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": "[email protected]",
  "memo": "Salesforce renewal coming up",
  "settings": {
    "recipients": [
      { "email": "[email protected]" }
    ],
    "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": "[email protected]",
  "memo": "High-value Salesforce charges",
  "settings": {
    "recipients": [
      { "email": "[email protected]" },
      { "email": "[email protected]" }
    ],
    "transaction": {
      "charge_type": "all",
      "transaction_threshold": 5000
    }
  }
}

Creating a Contract-Renewal Alert

POST /v2/alerts

{
  "contract_id": "contract-uuid-here",
  "type": "contract-renewal",
  "owner": "[email protected]",
  "memo": "Enterprise agreement renewal",
  "settings": {
    "recipients": [
      { "email": "[email protected]" }
    ],
    "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": "[email protected]",
  "memo": "Updated renewal notification",
  "settings": {
    "recipients": [
      { "email": "[email protected]" }
    ],
    "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