create-customer-notification
dci create-customer-notification [body] [flags]
Creates an organization-wide notification config. settings names one or more public types. Destinations are emails, slackChannels, and teamsChannels arrays. The response returns those three arrays. A channel that a subscribed type does not support is 422 customers.channel_not_supported. A Teams destination on a type that supports Teams is 422 validation_failed when the tenant has no Teams entitlement.
Requires the settings (Manage settings) permission.
The Idempotency-Key header is required. The same key and the same body replay the stored success. A different body is 422 idempotency_key_reused. A 5xx response may leave the key reserved, so a retry returns 409 until the original request is released or about 30 minutes pass. dryRun=true does not reserve the key. With dryRun=true the request goes through the same checks as a real create and returns 200 with X-Dry-Run: true and null identity fields (id, createTime, updateTime, etag) without creating anything.
Reads are immediately consistent. After a 201, a GET of that notification returns the created config.
Pass the request body as name: value arguments or pipe JSON on stdin — see Command structure.
Request
Content-Type: application/json
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Display name of the notification (max 200 characters). The stored name is trimmed. |
destinations | object | yes | Delivery targets for this config. Must include emails, slackChannels, and teamsChannels, with at least one non-empty array. |
destinations.emails | array of string (email) | yes | Email addresses that receive the notification, in the order sent. The array is required; an empty array means email is unused. Omitting the array is rejected. At least one of emails, slackChannels, or teamsChannels must be non-empty. Addresses are stored and returned lowercase. A duplicate or an invalid email is 422. |
destinations.slackChannels | array of string | yes | Slack channel ids for Slack channels that receive the notification, in the order sent. The array is required; an empty array means Slack is unused. Omitting the array is rejected. At least one of emails, slackChannels, or teamsChannels must be non-empty. Accepts a public channel, a shared channel, or a private channel the caller is a member of when the DoiT app is also in that channel. A service account cannot add a private channel and receives the same 422 as an id outside the tenant. The caller supplies the id; this API does not look channels up. A duplicate or an id outside the tenant is 422 without saying whether it exists elsewhere. After a channel is accepted, get and list keep returning that id even if the channel is later deleted, archived, or disconnected. That does not mean delivery still works. |
destinations.teamsChannels | array of string | yes | Microsoft Teams conversation ids for Microsoft Teams channels that receive the notification, in the order sent. The array is required; an empty array means Teams is unused. Omitting the array is rejected. At least one of emails, slackChannels, or teamsChannels must be non-empty. A duplicate or an id outside the tenant is 422 without saying whether it exists elsewhere. A Teams id is also 422 when the tenant has no Teams entitlement. After a channel is accepted, get and list keep returning that id even if the channel is later deleted, archived, or disconnected, or the tenant loses Teams entitlement. That does not mean delivery still works. |
settings | object | yes | Subscribed notification settings, one property per type. A present property subscribes that type; \{\} subscribes a type that has no fields. Omitting a property on create leaves that type unsubscribed. At least one property is required. Unknown properties, including dashboard, report, and commitment subscriptions, prompt schedules, and conditions, are rejected with 422. Properties and their Console labels: - newInvoices: New invoices - newProformaInvoices: New proforma invoices - paymentReminders: Due or overdue payments - creditUtilization: Credit utilization - quotaUtilization: Quota utilization - cloudIncidents: Cloud incidents - newSkuUsage: New SKUs usage detected - dailyDigest: Daily digest, one email per selected allocation rule each day - weeklyDigest: Weekly digest, one email per selected allocation rule each week - monthlyDigest: Monthly digest - expertInsights: Third-party insights (Console item "New insights recommended by DoiT experts") - insights: New insights - costAnomalies: Cloud cost anomalies (Console item "Cost anomaly detection") - savingsPlanApproval: Savings Plan purchase requires approval (PerfectScale for Commitments) - savingsPlanPurchased: Savings Plan purchased - cudApproval: committed use discount (CUD) purchase requires approval - cudPurchased: CUD purchased - dataIntegrationSyncFailure: Data integration sync failures - awsBillingDataImport: AWS Billing Data Import Alert Requires Manage settings; no other permission is checked. Every destination channel must be supported by every subscribed type, or the response is 422 customers.channel_not_supported: - Email and Slack only: expertInsights, dataIntegrationSyncFailure - Email, Slack, and Microsoft Teams: every other property - A Teams destination on a supported type is still 422 validation_failed when the tenant has no Teams entitlement |
settings.newInvoices | object | Billing profiles this notification applies to. Omit billingProfileIds, or send an empty array, to include every billing profile in the tenant. An id outside the tenant is rejected with 422, the same error as an unknown id. | |
settings.newInvoices.billingProfileIds | array of string | Billing-profile ids in this tenant, shaped like ent_01HEXAMPLEBILLING0001. This API does not list billing profiles, and GET /billing/v1/invoices does not return these ids. Empty or omitted means every billing profile in the tenant. A read of an omitted or empty list returns the field absent. An explicit list is returned in the order sent. A duplicate id is rejected with 422. | |
settings.newProformaInvoices | object | Billing profiles this notification applies to. Omit billingProfileIds, or send an empty array, to include every billing profile in the tenant. An id outside the tenant is rejected with 422, the same error as an unknown id. | |
settings.newProformaInvoices.billingProfileIds | array of string | Billing-profile ids in this tenant, shaped like ent_01HEXAMPLEBILLING0001. This API does not list billing profiles, and GET /billing/v1/invoices does not return these ids. Empty or omitted means every billing profile in the tenant. A read of an omitted or empty list returns the field absent. An explicit list is returned in the order sent. A duplicate id is rejected with 422. | |
settings.paymentReminders | object | Billing profiles this notification applies to. Omit billingProfileIds, or send an empty array, to include every billing profile in the tenant. An id outside the tenant is rejected with 422, the same error as an unknown id. | |
settings.paymentReminders.billingProfileIds | array of string | Billing-profile ids in this tenant, shaped like ent_01HEXAMPLEBILLING0001. This API does not list billing profiles, and GET /billing/v1/invoices does not return these ids. Empty or omitted means every billing profile in the tenant. A read of an omitted or empty list returns the field absent. An explicit list is returned in the order sent. A duplicate id is rejected with 422. | |
settings.creditUtilization | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. | |
settings.quotaUtilization | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. | |
settings.cloudIncidents | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. | |
settings.newSkuUsage | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. | |
settings.dailyDigest | object | Allocation rules included in a daily or weekly digest. At least one id is required. | |
settings.dailyDigest.allocationIds | array of string | yes | Allocation rule ids from GET /analytics/v1/allocations. At least one id is required. A read returns the ids in the order sent. A duplicate, or an id outside the tenant, is rejected with 422. |
settings.weeklyDigest | object | Allocation rules included in a daily or weekly digest. At least one id is required. | |
settings.weeklyDigest.allocationIds | array of string | yes | Allocation rule ids from GET /analytics/v1/allocations. At least one id is required. A read returns the ids in the order sent. A duplicate, or an id outside the tenant, is rejected with 422. |
settings.monthlyDigest | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. | |
settings.expertInsights | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. | |
settings.insights | object | Optional insight filters. An empty or omitted list means every value of that filter. An insight must match every criterion across pillars, severities, and providers. A read of an omitted or empty list returns that field absent. An explicit list is returned in the order sent. A repeated value is rejected with 422. | |
settings.insights.pillars | array of string | Insight pillars. Empty or omitted means all pillars. | |
settings.insights.severities | array of string | Insight severities. Empty or omitted means all severities. | |
settings.insights.providers | array of string | Insights provider ids such as aws, gcp, azure, azure-ad, general, google-cloud-source, google-workspace, k8s, oci, and vmware. These are the ids Insights resources use, not invoice platform ids such as amazon-web-services. Empty or omitted means all providers. Available ids depend on the tenant's connected accounts. Each value is a non-empty string. | |
settings.costAnomalies | object | Cost-anomaly notification settings: minimum severity, excess-cost threshold, allocation scope, and optional resend controls. | |
settings.costAnomalies.minSeverity | string | yes | warning — warning and above. critical — critical only. There is no information or all value; a write of all is rejected with 422. Clients may send only warning or critical. Responses return only warning or critical. A missing or empty stored severity (console "All severity levels") is returned as warning. critical is stored and returned as critical. One of: "warning", "critical". |
settings.costAnomalies.minExcessCost | object | yes | Minimum excess cost, as Money. Notify when excess cost is above this amount, not total spend. 100.00 USD means $100. currency must be USD; any other currency is rejected with 422. A negative amount is rejected with 422. A fractional amount is rejected with 422 (100.99 is not a whole number of dollars). 100 and 100.00 are both accepted. 0 and 0.00 are accepted. Amounts above 1,000,000,000 whole dollars, and forms such as Inf, exponents, a leading +, or underscores, are rejected with 422. Responses return the amount as "100.00". |
settings.costAnomalies.minExcessCost.amount | string | yes | Decimal monetary amount at ISO 4217 minor-unit precision (string). |
settings.costAnomalies.minExcessCost.currency | string | yes | ISO 4217 currency code. |
settings.costAnomalies.allocations | object | yes | Allocation scope for cost-anomaly notifications. ids are allocation ids from GET /analytics/v1/allocations. An id outside the caller's tenant is rejected with 422 without saying whether it exists elsewhere. mode: all means every allocation with anomaly detection enabled, including anomalies that are not tied to an allocation, and it carries an empty ids. include and exclude require at least one id. mode: all with a non-empty ids, and include or exclude with an empty ids, are rejected with 422. ids are an ordered list: the server stores and returns them in the order sent, and it does not sort or drop entries. A duplicate id is rejected with 422. |
settings.costAnomalies.allocations.mode | string | yes | all — every allocation with anomaly detection enabled (and unallocated anomalies). include — only the listed ids. exclude — all enabled allocations except the listed ids. all cannot be sent with a non-empty ids. include and exclude cannot be sent with an empty ids. One of: "all", "include", "exclude". |
settings.costAnomalies.allocations.ids | array of string | yes | Allocation ids, in the order sent. A read returns that same order. A duplicate id is rejected with 422. Empty when mode is all. Non-empty when mode is include or exclude. |
settings.costAnomalies.repeat | object | Resend controls for an active cost anomaly. Omit the whole repeat object when neither control is set. An empty object is rejected with 422. | |
settings.costAnomalies.repeat.everyHours | integer | Resend until the anomaly is inactive, every N hours (1–24). | |
settings.costAnomalies.repeat.whenCostGrows | object | Resend when the anomaly's cost grows. At least one of percentIncrease or minIncrease is required. An object with only withinHours, only match, or neither amount is rejected with 422. - both percentIncrease and minIncrease present → match is required (or or and) - exactly one of percentIncrease or minIncrease present → omit match (percentage-only or value-only) - neither amount present → rejected with 422 percentIncrease is an integer percent (10 means 10 percent) and must be at least 1. Omit withinHours when the time window is off. Nested fields omitted — see the raw JSON schema. | |
settings.savingsPlanApproval | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. | |
settings.savingsPlanPurchased | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. | |
settings.cudApproval | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. | |
settings.cudPurchased | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. | |
settings.dataIntegrationSyncFailure | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. | |
settings.awsBillingDataImport | object | Billing profiles this notification applies to. Omit billingProfileIds, or send an empty array, to include every billing profile in the tenant. An id outside the tenant is rejected with 422, the same error as an unknown id. | |
settings.awsBillingDataImport.billingProfileIds | array of string | Billing-profile ids in this tenant, shaped like ent_01HEXAMPLEBILLING0001. This API does not list billing profiles, and GET /billing/v1/invoices does not return these ids. Empty or omitted means every billing profile in the tenant. A read of an omitted or empty list returns the field absent. An explicit list is returned in the order sent. A duplicate id is rejected with 422. |
Example body (JSON)
{
"name": "New invoices",
"destinations": {
"emails": [],
"slackChannels": [
"C0123ABCD"
],
"teamsChannels": []
},
"settings": {
"newInvoices": {
"billingProfileIds": [
"ent_01HEXAMPLEBILLING0001"
]
}
}
}
Raw JSON schema
{
"type": "object",
"additionalProperties": false,
"description": "Fields of a new organization notification. Unknown fields are rejected. `settings` must include at least one notification type. `destinations` must include `emails`, `slackChannels`, and `teamsChannels`, with at least one non-empty array. A channel that a subscribed type does not support is `422` `customers.channel_not_supported`. A Teams destination on a type that supports Teams is `422` `validation_failed` when the tenant has no Teams entitlement.",
"required": [
"name",
"destinations",
"settings"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Display name of the notification (max 200 characters). The stored name is trimmed.",
"example": "Anomaly alerts"
},
"destinations": {
"description": "Delivery targets for this config. Must include `emails`, `slackChannels`, and `teamsChannels`, with at least one non-empty array.",
"allOf": [
{
"type": "object",
"additionalProperties": false,
"description": "Delivery targets for an organization notification. All three arrays are always present on read. An unused destination is an empty array, never omitted and never `null`. On create, and on a patch that includes `destinations`, all three arrays are required and at least one must be non-empty. An object whose three arrays are all empty is rejected with `422`. Each array is kept in the order sent; a later read returns that same order. Emails are trimmed and stored lowercase. Channel ids are trimmed and otherwise unchanged. A duplicate value inside one array is rejected with `422` (emails compared after lowercase; channel ids compared exactly after trim).",
"required": [
"emails",
"slackChannels",
"teamsChannels"
],
"properties": {
"emails": {
"type": "array",
"minItems": 0,
"description": "Email addresses that receive the notification, in the order sent. The array is required; an empty array means email is unused. Omitting the array is rejected. At least one of `emails`, `slackChannels`, or `teamsChannels` must be non-empty. Addresses are stored and returned lowercase. A duplicate or an invalid email is `422`.",
"items": {
"type": "string",
"format": "email",
"minLength": 1,
"x-doit-pii": true
},
"example": [
]
},
"slackChannels": {
"type": "array",
"minItems": 0,
"description": "Slack channel ids for Slack channels that receive the notification, in the order sent. The array is required; an empty array means Slack is unused. Omitting the array is rejected. At least one of `emails`, `slackChannels`, or `teamsChannels` must be non-empty. Accepts a public channel, a shared channel, or a private channel the caller is a member of when the DoiT app is also in that channel. A service account cannot add a private channel and receives the same `422` as an id outside the tenant. The caller supplies the id; this API does not look channels up. A duplicate or an id outside the tenant is `422` without saying whether it exists elsewhere. After a channel is accepted, get and list keep returning that id even if the channel is later deleted, archived, or disconnected. That does not mean delivery still works.",
"items": {
"type": "string",
"minLength": 1
},
"example": [
"C0123ABCD"
]
},
"teamsChannels": {
"type": "array",
"minItems": 0,
"description": "Microsoft Teams conversation ids for Microsoft Teams channels that receive the notification, in the order sent. The array is required; an empty array means Teams is unused. Omitting the array is rejected. At least one of `emails`, `slackChannels`, or `teamsChannels` must be non-empty. A duplicate or an id outside the tenant is `422` without saying whether it exists elsewhere. A Teams id is also `422` when the tenant has no Teams entitlement. After a channel is accepted, get and list keep returning that id even if the channel is later deleted, archived, or disconnected, or the tenant loses Teams entitlement. That does not mean delivery still works.",
"items": {
"type": "string",
"minLength": 1
},
"example": [
]
}
}
}
]
},
"settings": {
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"description": "Subscribed notification settings, one property per type. A present property subscribes that type;\n`{}` subscribes a type that has no fields. Omitting a property on create leaves that type\nunsubscribed. At least one property is required. Unknown properties, including dashboard, report,\nand commitment subscriptions, prompt schedules, and `conditions`, are rejected with `422`.\n\nProperties and their Console labels:\n\n- `newInvoices`: New invoices\n- `newProformaInvoices`: New proforma invoices\n- `paymentReminders`: Due or overdue payments\n- `creditUtilization`: Credit utilization\n- `quotaUtilization`: Quota utilization\n- `cloudIncidents`: Cloud incidents\n- `newSkuUsage`: New SKUs usage detected\n- `dailyDigest`: Daily digest, one email per selected allocation rule each day\n- `weeklyDigest`: Weekly digest, one email per selected allocation rule each week\n- `monthlyDigest`: Monthly digest\n- `expertInsights`: Third-party insights (Console item \"New insights recommended by DoiT experts\")\n- `insights`: New insights\n- `costAnomalies`: Cloud cost anomalies (Console item \"Cost anomaly detection\")\n- `savingsPlanApproval`: Savings Plan purchase requires approval (PerfectScale for Commitments)\n- `savingsPlanPurchased`: Savings Plan purchased\n- `cudApproval`: committed use discount (CUD) purchase requires approval\n- `cudPurchased`: CUD purchased\n- `dataIntegrationSyncFailure`: Data integration sync failures\n- `awsBillingDataImport`: AWS Billing Data Import Alert\n\nRequires Manage settings; no other permission is checked.\n\nEvery destination channel must be supported by every subscribed type, or the response is `422`\n`customers.channel_not_supported`:\n\n- Email and Slack only: `expertInsights`, `dataIntegrationSyncFailure`\n- Email, Slack, and Microsoft Teams: every other property\n- A Teams destination on a supported type is still `422` `validation_failed` when the tenant has\n no Teams entitlement",
"properties": {
"newInvoices": {
"type": "object",
"additionalProperties": false,
"description": "Billing profiles this notification applies to. Omit `billingProfileIds`, or send an empty array, to include every billing profile in the tenant. An id outside the tenant is rejected with `422`, the same error as an unknown id.",
"properties": {
"billingProfileIds": {
"type": "array",
"description": "Billing-profile ids in this tenant, shaped like `ent_01HEXAMPLEBILLING0001`. This API does not list billing profiles, and `GET /billing/v1/invoices` does not return these ids. Empty or omitted means every billing profile in the tenant. A read of an omitted or empty list returns the field absent. An explicit list is returned in the order sent. A duplicate id is rejected with `422`.",
"items": {
"type": "string",
"minLength": 1,
"example": "ent_01HEXAMPLEBILLING0001"
}
}
}
},
"newProformaInvoices": {
"type": "object",
"additionalProperties": false,
"description": "Billing profiles this notification applies to. Omit `billingProfileIds`, or send an empty array, to include every billing profile in the tenant. An id outside the tenant is rejected with `422`, the same error as an unknown id.",
"properties": {
"billingProfileIds": {
"type": "array",
"description": "Billing-profile ids in this tenant, shaped like `ent_01HEXAMPLEBILLING0001`. This API does not list billing profiles, and `GET /billing/v1/invoices` does not return these ids. Empty or omitted means every billing profile in the tenant. A read of an omitted or empty list returns the field absent. An explicit list is returned in the order sent. A duplicate id is rejected with `422`.",
"items": {
"type": "string",
"minLength": 1,
"example": "ent_01HEXAMPLEBILLING0001"
}
}
}
},
"paymentReminders": {
"type": "object",
"additionalProperties": false,
"description": "Billing profiles this notification applies to. Omit `billingProfileIds`, or send an empty array, to include every billing profile in the tenant. An id outside the tenant is rejected with `422`, the same error as an unknown id.",
"properties": {
"billingProfileIds": {
"type": "array",
"description": "Billing-profile ids in this tenant, shaped like `ent_01HEXAMPLEBILLING0001`. This API does not list billing profiles, and `GET /billing/v1/invoices` does not return these ids. Empty or omitted means every billing profile in the tenant. A read of an omitted or empty list returns the field absent. An explicit list is returned in the order sent. A duplicate id is rejected with `422`.",
"items": {
"type": "string",
"minLength": 1,
"example": "ent_01HEXAMPLEBILLING0001"
}
}
}
},
"creditUtilization": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"quotaUtilization": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"cloudIncidents": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"newSkuUsage": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"dailyDigest": {
"type": "object",
"additionalProperties": false,
"description": "Allocation rules included in a daily or weekly digest. At least one id is required.",
"required": [
"allocationIds"
],
"properties": {
"allocationIds": {
"type": "array",
"minItems": 1,
"description": "Allocation rule ids from `GET /analytics/v1/allocations`. At least one id is required. A read returns the ids in the order sent. A duplicate, or an id outside the tenant, is rejected with `422`.",
"items": {
"type": "string",
"minLength": 1,
"example": "alloc_abc"
}
}
}
},
"weeklyDigest": {
"type": "object",
"additionalProperties": false,
"description": "Allocation rules included in a daily or weekly digest. At least one id is required.",
"required": [
"allocationIds"
],
"properties": {
"allocationIds": {
"type": "array",
"minItems": 1,
"description": "Allocation rule ids from `GET /analytics/v1/allocations`. At least one id is required. A read returns the ids in the order sent. A duplicate, or an id outside the tenant, is rejected with `422`.",
"items": {
"type": "string",
"minLength": 1,
"example": "alloc_abc"
}
}
}
},
"monthlyDigest": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"expertInsights": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"insights": {
"type": "object",
"additionalProperties": false,
"description": "Optional insight filters. An empty or omitted list means every value of that filter. An insight must match every criterion across `pillars`, `severities`, and `providers`. A read of an omitted or empty list returns that field absent. An explicit list is returned in the order sent. A repeated value is rejected with `422`.",
"properties": {
"pillars": {
"type": "array",
"description": "Insight pillars. Empty or omitted means all pillars.",
"items": {
"type": "string",
"enum": [
"cost",
"operations",
"performance",
"security",
"compliance"
],
"x-enumDescriptions": {
"cost": "Cost. Notify for insights in the Cost category.",
"operations": "Operations. Notify for insights in the Operations category.",
"performance": "Performance. Notify for insights in the Performance category.",
"security": "Security. Notify for insights in the Security category.",
"compliance": "Compliance. Notify for insights in the Compliance category."
}
}
},
"severities": {
"type": "array",
"description": "Insight severities. Empty or omitted means all severities.",
"items": {
"type": "string",
"enum": [
"critical",
"high",
"medium",
"low"
],
"x-enumDescriptions": {
"critical": "Critical. Notify for Critical insights.",
"high": "High. Notify for High insights.",
"medium": "Medium. Notify for Medium insights.",
"low": "Low. Notify for Low insights."
}
}
},
"providers": {
"type": "array",
"description": "Insights provider ids such as `aws`, `gcp`, `azure`, `azure-ad`, `general`, `google-cloud-source`, `google-workspace`, `k8s`, `oci`, and `vmware`. These are the ids Insights resources use, not invoice platform ids such as `amazon-web-services`. Empty or omitted means all providers. Available ids depend on the tenant's connected accounts. Each value is a non-empty string.",
"items": {
"type": "string",
"minLength": 1,
"example": "aws"
}
}
}
},
"costAnomalies": {
"type": "object",
"additionalProperties": false,
"description": "Cost-anomaly notification settings: minimum severity, excess-cost threshold, allocation scope, and\noptional resend controls.\n",
"required": [
"minSeverity",
"minExcessCost",
"allocations"
],
"properties": {
"minSeverity": {
"type": "string",
"enum": [
"warning",
"critical"
],
"x-enumDescriptions": {
"warning": "Warning and above. A missing stored severity (Console \"All severity levels\") is also returned as `warning`.",
"critical": "Critical."
},
"description": "`warning` — warning and above. `critical` — critical only. There is no `information` or `all` value; a write of `all` is rejected with `422`. Clients may send only `warning` or `critical`. Responses return only `warning` or `critical`. A missing or empty stored severity (console \"All severity levels\") is returned as `warning`. `critical` is stored and returned as `critical`.",
"example": "warning"
},
"minExcessCost": {
"description": "Minimum excess cost, as Money. Notify when excess cost is above this amount, not total spend.\n`100.00` USD means $100. `currency` must be `USD`; any other currency is rejected with `422`. A\nnegative amount is rejected with `422`. A fractional amount is rejected with `422` (`100.99` is not a\nwhole number of dollars). `100` and `100.00` are both accepted. `0` and `0.00` are accepted. Amounts\nabove 1,000,000,000 whole dollars, and forms such as `Inf`, exponents, a leading `+`, or underscores,\nare rejected with `422`. Responses return the amount as `\"100.00\"`.\n",
"allOf": [
{
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$",
"description": "Decimal monetary amount at ISO 4217 minor-unit precision (string).",
"example": "100.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code.",
"example": "USD"
}
}
}
]
},
"allocations": {
"type": "object",
"additionalProperties": false,
"description": "Allocation scope for cost-anomaly notifications. `ids` are allocation ids from `GET\n/analytics/v1/allocations`. An id outside the caller's tenant is rejected with `422` without saying\nwhether it exists elsewhere.\n\n`mode: all` means every allocation with anomaly detection enabled, including anomalies that are not\ntied to an allocation, and it carries an empty `ids`. `include` and `exclude` require at least one\nid. `mode: all` with a non-empty `ids`, and `include` or `exclude` with an empty `ids`, are rejected\nwith `422`. `ids` are an ordered list: the server stores and returns them in the order sent, and it does\nnot sort or drop entries. A duplicate id is rejected with `422`.\n",
"required": [
"mode",
"ids"
],
"properties": {
"mode": {
"type": "string",
"enum": [
"all",
"include",
"exclude"
],
"x-enumDescriptions": {
"all": "Include all enabled allocations, including anomalies that are not tied to an allocation. Send an empty `ids`.",
"include": "Include specific allocations. Requires at least one id.",
"exclude": "Exclude specific allocations. Requires at least one id."
},
"description": "`all` — every allocation with anomaly detection enabled (and unallocated anomalies). `include` — only the listed ids. `exclude` — all enabled allocations except the listed ids. `all` cannot be sent with a non-empty `ids`. `include` and `exclude` cannot be sent with an empty `ids`.",
"example": "include"
},
"ids": {
"type": "array",
"description": "Allocation ids, in the order sent. A read returns that same order. A duplicate id is rejected\nwith `422`. Empty when `mode` is `all`. Non-empty when `mode` is `include` or `exclude`.\n",
"items": {
"type": "string",
"minLength": 1
},
"example": [
"alloc_abc",
"alloc_def"
]
}
}
},
"repeat": {
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"description": "Resend controls for an active cost anomaly. Omit the whole `repeat` object when neither control is\nset. An empty object is rejected with `422`.\n",
"properties": {
"everyHours": {
"type": "integer",
"minimum": 1,
"maximum": 24,
"description": "Resend until the anomaly is inactive, every N hours (1–24).\n",
"example": 24
},
"whenCostGrows": {
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"description": "Resend when the anomaly's cost grows. At least one of `percentIncrease` or `minIncrease` is required.\nAn object with only `withinHours`, only `match`, or neither amount is rejected with `422`.\n\n- both `percentIncrease` and `minIncrease` present → `match` is\n required (`or` or `and`)\n- exactly one of `percentIncrease` or `minIncrease` present → omit\n `match` (percentage-only or value-only)\n- neither amount present → rejected with `422`\n\n`percentIncrease` is an integer percent (`10` means 10 percent) and must be at least 1. Omit\n`withinHours` when the time window is off.",
"properties": {
"match": {
"type": "string",
"enum": [
"or",
"and"
],
"x-enumDescriptions": {
"or": "Resend when either the percent increase or the dollar increase is reached.",
"and": "Resend only when both are reached."
},
"description": "How to combine percent and dollar growth when both are set. Required when both amounts are present; omit when only one amount is present.",
"example": "or"
},
"percentIncrease": {
"type": "integer",
"minimum": 1,
"description": "Minimum percent cost increase that triggers a resend. `10` means 10 percent. Must be greater than 0.\n",
"example": 10
},
"minIncrease": {
"description": "Minimum cost growth that triggers a resend, as Money. Must be a positive whole number of dollars.\n`150.00` USD means $150. `currency` must be `USD`; any other currency is rejected with `422`. `0`,\n`0.00`, and a negative amount are rejected with `422`. A fractional amount is rejected with `422`\n(`150.99` is not a whole number of dollars). `150` and `150.00` are both accepted. Amounts above\n1,000,000,000 whole dollars, and forms such as `Inf`, exponents, a leading `+`, or underscores, are\nrejected with `422`. Responses return the amount as `\"150.00\"`.\n",
"allOf": [
{
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$",
"description": "Decimal monetary amount at ISO 4217 minor-unit precision (string).",
"example": "100.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code.",
"example": "USD"
}
}
}
]
},
"withinHours": {
"type": "integer",
"minimum": 1,
"maximum": 24,
"description": "Optional window in hours for the growth check (1–24).",
"example": 6
}
}
}
}
}
}
},
"savingsPlanApproval": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"savingsPlanPurchased": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"cudApproval": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"cudPurchased": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"dataIntegrationSyncFailure": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"awsBillingDataImport": {
"type": "object",
"additionalProperties": false,
"description": "Billing profiles this notification applies to. Omit `billingProfileIds`, or send an empty array, to include every billing profile in the tenant. An id outside the tenant is rejected with `422`, the same error as an unknown id.",
"properties": {
"billingProfileIds": {
"type": "array",
"description": "Billing-profile ids in this tenant, shaped like `ent_01HEXAMPLEBILLING0001`. This API does not list billing profiles, and `GET /billing/v1/invoices` does not return these ids. Empty or omitted means every billing profile in the tenant. A read of an omitted or empty list returns the field absent. An explicit list is returned in the order sent. A duplicate id is rejected with `422`.",
"items": {
"type": "string",
"minLength": 1,
"example": "ent_01HEXAMPLEBILLING0001"
}
}
}
}
}
}
},
"example": {
"name": "New invoices",
"destinations": {
"emails": [],
"slackChannels": [
"C0123ABCD"
],
"teamsChannels": []
},
"settings": {
"newInvoices": {
"billingProfileIds": [
"ent_01HEXAMPLEBILLING0001"
]
}
}
}
}
Flags
| Flag | Type | Default | Example | Description |
|---|---|---|---|---|
--dry-run | boolean | false | If true, validates the request and returns the would-be result without applying it. The response then carries the X-Dry-Run header. |
Every command also accepts the CLI-wide flags for output shaping — see Output formats and Table output options.
Output
OK - Dry run only (dryRun=true). Every check of a real create passed
and nothing was created; id, createTime, updateTime, and etag
are null.
By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.
| Field | Type | Description |
|---|---|---|
id | string | Server-assigned notification id. null only on a dry-run create. |
name | string | Display name of the notification (max 200 characters). The stored name is trimmed. |
createTime | string (date-time) | When the config was created. null only on a dry-run create. |
updateTime | string (date-time) | When the config was last changed. null only on a dry-run create. |
etag | string | Current strong ETag as bare SHA-256 hex. The ETag response header and If-Match wrap this value in double quotes. Send that quoted form unchanged on update or delete. null only on a dry-run create. |
destinations | object | Delivery targets. Always includes emails, slackChannels, and teamsChannels. Unused lists are empty arrays. |
destinations.emails | array of string (email) | Email addresses that receive the notification, in the order sent. The array is required; an empty array means email is unused. Omitting the array is rejected. At least one of emails, slackChannels, or teamsChannels must be non-empty. Addresses are stored and returned lowercase. A duplicate or an invalid email is 422. |
destinations.slackChannels | array of string | Slack channel ids for Slack channels that receive the notification, in the order sent. The array is required; an empty array means Slack is unused. Omitting the array is rejected. At least one of emails, slackChannels, or teamsChannels must be non-empty. Accepts a public channel, a shared channel, or a private channel the caller is a member of when the DoiT app is also in that channel. A service account cannot add a private channel and receives the same 422 as an id outside the tenant. The caller supplies the id; this API does not look channels up. A duplicate or an id outside the tenant is 422 without saying whether it exists elsewhere. After a channel is accepted, get and list keep returning that id even if the channel is later deleted, archived, or disconnected. That does not mean delivery still works. |
destinations.teamsChannels | array of string | Microsoft Teams conversation ids for Microsoft Teams channels that receive the notification, in the order sent. The array is required; an empty array means Teams is unused. Omitting the array is rejected. At least one of emails, slackChannels, or teamsChannels must be non-empty. A duplicate or an id outside the tenant is 422 without saying whether it exists elsewhere. A Teams id is also 422 when the tenant has no Teams entitlement. After a channel is accepted, get and list keep returning that id even if the channel is later deleted, archived, or disconnected, or the tenant loses Teams entitlement. That does not mean delivery still works. |
settings | object | Subscribed notification settings. At least one type is required. A config that also stores a dashboard, report, or commitment subscription or a prompt schedule is omitted from list and get. PATCH and DELETE of that id return 404. |
settings.newInvoices | object | Billing profiles this notification applies to. Omit billingProfileIds, or send an empty array, to include every billing profile in the tenant. An id outside the tenant is rejected with 422, the same error as an unknown id. |
settings.newInvoices.billingProfileIds | array of string | Billing-profile ids in this tenant, shaped like ent_01HEXAMPLEBILLING0001. This API does not list billing profiles, and GET /billing/v1/invoices does not return these ids. Empty or omitted means every billing profile in the tenant. A read of an omitted or empty list returns the field absent. An explicit list is returned in the order sent. A duplicate id is rejected with 422. |
settings.newProformaInvoices | object | Billing profiles this notification applies to. Omit billingProfileIds, or send an empty array, to include every billing profile in the tenant. An id outside the tenant is rejected with 422, the same error as an unknown id. |
settings.newProformaInvoices.billingProfileIds | array of string | Billing-profile ids in this tenant, shaped like ent_01HEXAMPLEBILLING0001. This API does not list billing profiles, and GET /billing/v1/invoices does not return these ids. Empty or omitted means every billing profile in the tenant. A read of an omitted or empty list returns the field absent. An explicit list is returned in the order sent. A duplicate id is rejected with 422. |
settings.paymentReminders | object | Billing profiles this notification applies to. Omit billingProfileIds, or send an empty array, to include every billing profile in the tenant. An id outside the tenant is rejected with 422, the same error as an unknown id. |
settings.paymentReminders.billingProfileIds | array of string | Billing-profile ids in this tenant, shaped like ent_01HEXAMPLEBILLING0001. This API does not list billing profiles, and GET /billing/v1/invoices does not return these ids. Empty or omitted means every billing profile in the tenant. A read of an omitted or empty list returns the field absent. An explicit list is returned in the order sent. A duplicate id is rejected with 422. |
settings.creditUtilization | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. |
settings.quotaUtilization | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. |
settings.cloudIncidents | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. |
settings.newSkuUsage | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. |
settings.dailyDigest | object | Allocation rules included in a daily or weekly digest. At least one id is required. |
settings.dailyDigest.allocationIds | array of string | Allocation rule ids from GET /analytics/v1/allocations. At least one id is required. A read returns the ids in the order sent. A duplicate, or an id outside the tenant, is rejected with 422. |
settings.weeklyDigest | object | Allocation rules included in a daily or weekly digest. At least one id is required. |
settings.weeklyDigest.allocationIds | array of string | Allocation rule ids from GET /analytics/v1/allocations. At least one id is required. A read returns the ids in the order sent. A duplicate, or an id outside the tenant, is rejected with 422. |
settings.monthlyDigest | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. |
settings.expertInsights | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. |
settings.insights | object | Optional insight filters. An empty or omitted list means every value of that filter. An insight must match every criterion across pillars, severities, and providers. A read of an omitted or empty list returns that field absent. An explicit list is returned in the order sent. A repeated value is rejected with 422. |
settings.insights.pillars | array of string | Insight pillars. Empty or omitted means all pillars. |
settings.insights.severities | array of string | Insight severities. Empty or omitted means all severities. |
settings.insights.providers | array of string | Insights provider ids such as aws, gcp, azure, azure-ad, general, google-cloud-source, google-workspace, k8s, oci, and vmware. These are the ids Insights resources use, not invoice platform ids such as amazon-web-services. Empty or omitted means all providers. Available ids depend on the tenant's connected accounts. Each value is a non-empty string. |
settings.costAnomalies | object | Cost-anomaly notification settings: minimum severity, excess-cost threshold, allocation scope, and optional resend controls. |
settings.costAnomalies.minSeverity | string | warning — warning and above. critical — critical only. There is no information or all value; a write of all is rejected with 422. Clients may send only warning or critical. Responses return only warning or critical. A missing or empty stored severity (console "All severity levels") is returned as warning. critical is stored and returned as critical. One of: "warning", "critical". |
settings.costAnomalies.minExcessCost | object | Minimum excess cost, as Money. Notify when excess cost is above this amount, not total spend. 100.00 USD means $100. currency must be USD; any other currency is rejected with 422. A negative amount is rejected with 422. A fractional amount is rejected with 422 (100.99 is not a whole number of dollars). 100 and 100.00 are both accepted. 0 and 0.00 are accepted. Amounts above 1,000,000,000 whole dollars, and forms such as Inf, exponents, a leading +, or underscores, are rejected with 422. Responses return the amount as "100.00". |
settings.costAnomalies.minExcessCost.amount | string | Decimal monetary amount at ISO 4217 minor-unit precision (string). |
settings.costAnomalies.minExcessCost.currency | string | ISO 4217 currency code. |
settings.costAnomalies.allocations | object | Allocation scope for cost-anomaly notifications. ids are allocation ids from GET /analytics/v1/allocations. An id outside the caller's tenant is rejected with 422 without saying whether it exists elsewhere. mode: all means every allocation with anomaly detection enabled, including anomalies that are not tied to an allocation, and it carries an empty ids. include and exclude require at least one id. mode: all with a non-empty ids, and include or exclude with an empty ids, are rejected with 422. ids are an ordered list: the server stores and returns them in the order sent, and it does not sort or drop entries. A duplicate id is rejected with 422. |
settings.costAnomalies.allocations.mode | string | all — every allocation with anomaly detection enabled (and unallocated anomalies). include — only the listed ids. exclude — all enabled allocations except the listed ids. all cannot be sent with a non-empty ids. include and exclude cannot be sent with an empty ids. One of: "all", "include", "exclude". |
settings.costAnomalies.allocations.ids | array of string | Allocation ids, in the order sent. A read returns that same order. A duplicate id is rejected with 422. Empty when mode is all. Non-empty when mode is include or exclude. |
settings.costAnomalies.repeat | object | Resend controls for an active cost anomaly. Omit the whole repeat object when neither control is set. An empty object is rejected with 422. |
settings.costAnomalies.repeat.everyHours | integer | Resend until the anomaly is inactive, every N hours (1–24). |
settings.costAnomalies.repeat.whenCostGrows | object | Resend when the anomaly's cost grows. At least one of percentIncrease or minIncrease is required. An object with only withinHours, only match, or neither amount is rejected with 422. - both percentIncrease and minIncrease present → match is required (or or and) - exactly one of percentIncrease or minIncrease present → omit match (percentage-only or value-only) - neither amount present → rejected with 422 percentIncrease is an integer percent (10 means 10 percent) and must be at least 1. Omit withinHours when the time window is off. Nested fields omitted — see the raw JSON schema. |
settings.savingsPlanApproval | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. |
settings.savingsPlanPurchased | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. |
settings.cudApproval | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. |
settings.cudPurchased | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. |
settings.dataIntegrationSyncFailure | object | A present empty object means this type is subscribed, for example "creditUtilization": \{\}. The object has no fields. On a patch property, null unsubscribes that type and is a different value. |
settings.awsBillingDataImport | object | Billing profiles this notification applies to. Omit billingProfileIds, or send an empty array, to include every billing profile in the tenant. An id outside the tenant is rejected with 422, the same error as an unknown id. |
settings.awsBillingDataImport.billingProfileIds | array of string | Billing-profile ids in this tenant, shaped like ent_01HEXAMPLEBILLING0001. This API does not list billing profiles, and GET /billing/v1/invoices does not return these ids. Empty or omitted means every billing profile in the tenant. A read of an omitted or empty list returns the field absent. An explicit list is returned in the order sent. A duplicate id is rejected with 422. |
Example response (--output json)
{
"id": null,
"name": "Anomaly alerts",
"createTime": null,
"updateTime": null,
"etag": null,
"destinations": {
"emails": [
],
"slackChannels": [
"C0123ABCD"
],
"teamsChannels": [
]
},
"settings": {
"costAnomalies": {
"minSeverity": "warning",
"minExcessCost": {
"amount": "100.00",
"currency": "USD"
},
"allocations": {
"mode": "include",
"ids": [
"alloc_abc",
"alloc_def"
]
},
"repeat": {
"everyHours": 24,
"whenCostGrows": {
"match": "or",
"percentIncrease": 10,
"minIncrease": {
"amount": "150.00",
"currency": "USD"
},
"withinHours": 6
}
}
}
}
}
Raw JSON schema
{
"type": "object",
"additionalProperties": false,
"description": "Organization-wide notification config. Create and read return the full resource with the same field names. Update and delete require `If-Match` against the strong `etag`.",
"required": [
"id",
"name",
"createTime",
"updateTime",
"etag",
"destinations",
"settings"
],
"properties": {
"id": {
"type": "string",
"readOnly": true,
"x-terraform-computed": true,
"description": "Server-assigned notification id. `null` only on a dry-run create.",
"nullable": true,
"example": "notif_01HX9P2KQVJ8Z3M4T5N6V7W8Y9"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Display name of the notification (max 200 characters). The stored name is trimmed.",
"example": "Anomaly alerts"
},
"createTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"x-terraform-computed": true,
"description": "When the config was created. `null` only on a dry-run create.",
"nullable": true,
"example": "2026-10-01T08:00:00Z"
},
"updateTime": {
"type": "string",
"format": "date-time",
"readOnly": true,
"x-terraform-computed": true,
"description": "When the config was last changed. `null` only on a dry-run create.",
"nullable": true,
"example": "2026-10-01T08:00:00Z"
},
"etag": {
"type": "string",
"readOnly": true,
"x-terraform-computed": true,
"description": "Current strong ETag as bare SHA-256 hex. The `ETag` response header and `If-Match` wrap this value in double quotes. Send that quoted form unchanged on update or delete. `null` only on a dry-run create.",
"nullable": true,
"example": "3f7a1c9e2b4d6f8a0c1e3a5b7d9f1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a3c5e"
},
"destinations": {
"description": "Delivery targets. Always includes `emails`, `slackChannels`, and `teamsChannels`. Unused lists are empty arrays.",
"allOf": [
{
"type": "object",
"additionalProperties": false,
"description": "Delivery targets for an organization notification. All three arrays are always present on read. An unused destination is an empty array, never omitted and never `null`. On create, and on a patch that includes `destinations`, all three arrays are required and at least one must be non-empty. An object whose three arrays are all empty is rejected with `422`. Each array is kept in the order sent; a later read returns that same order. Emails are trimmed and stored lowercase. Channel ids are trimmed and otherwise unchanged. A duplicate value inside one array is rejected with `422` (emails compared after lowercase; channel ids compared exactly after trim).",
"required": [
"emails",
"slackChannels",
"teamsChannels"
],
"properties": {
"emails": {
"type": "array",
"minItems": 0,
"description": "Email addresses that receive the notification, in the order sent. The array is required; an empty array means email is unused. Omitting the array is rejected. At least one of `emails`, `slackChannels`, or `teamsChannels` must be non-empty. Addresses are stored and returned lowercase. A duplicate or an invalid email is `422`.",
"items": {
"type": "string",
"format": "email",
"minLength": 1,
"x-doit-pii": true
},
"example": [
]
},
"slackChannels": {
"type": "array",
"minItems": 0,
"description": "Slack channel ids for Slack channels that receive the notification, in the order sent. The array is required; an empty array means Slack is unused. Omitting the array is rejected. At least one of `emails`, `slackChannels`, or `teamsChannels` must be non-empty. Accepts a public channel, a shared channel, or a private channel the caller is a member of when the DoiT app is also in that channel. A service account cannot add a private channel and receives the same `422` as an id outside the tenant. The caller supplies the id; this API does not look channels up. A duplicate or an id outside the tenant is `422` without saying whether it exists elsewhere. After a channel is accepted, get and list keep returning that id even if the channel is later deleted, archived, or disconnected. That does not mean delivery still works.",
"items": {
"type": "string",
"minLength": 1
},
"example": [
"C0123ABCD"
]
},
"teamsChannels": {
"type": "array",
"minItems": 0,
"description": "Microsoft Teams conversation ids for Microsoft Teams channels that receive the notification, in the order sent. The array is required; an empty array means Teams is unused. Omitting the array is rejected. At least one of `emails`, `slackChannels`, or `teamsChannels` must be non-empty. A duplicate or an id outside the tenant is `422` without saying whether it exists elsewhere. A Teams id is also `422` when the tenant has no Teams entitlement. After a channel is accepted, get and list keep returning that id even if the channel is later deleted, archived, or disconnected, or the tenant loses Teams entitlement. That does not mean delivery still works.",
"items": {
"type": "string",
"minLength": 1
},
"example": [
]
}
}
}
]
},
"settings": {
"description": "Subscribed notification settings. At least one type is required. A config that also stores a dashboard, report, or commitment subscription or a prompt schedule is omitted from list and get. PATCH and DELETE of that id return `404`.",
"allOf": [
{
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"description": "Subscribed notification settings, one property per type. A present property subscribes that type;\n`{}` subscribes a type that has no fields. Omitting a property on create leaves that type\nunsubscribed. At least one property is required. Unknown properties, including dashboard, report,\nand commitment subscriptions, prompt schedules, and `conditions`, are rejected with `422`.\n\nProperties and their Console labels:\n\n- `newInvoices`: New invoices\n- `newProformaInvoices`: New proforma invoices\n- `paymentReminders`: Due or overdue payments\n- `creditUtilization`: Credit utilization\n- `quotaUtilization`: Quota utilization\n- `cloudIncidents`: Cloud incidents\n- `newSkuUsage`: New SKUs usage detected\n- `dailyDigest`: Daily digest, one email per selected allocation rule each day\n- `weeklyDigest`: Weekly digest, one email per selected allocation rule each week\n- `monthlyDigest`: Monthly digest\n- `expertInsights`: Third-party insights (Console item \"New insights recommended by DoiT experts\")\n- `insights`: New insights\n- `costAnomalies`: Cloud cost anomalies (Console item \"Cost anomaly detection\")\n- `savingsPlanApproval`: Savings Plan purchase requires approval (PerfectScale for Commitments)\n- `savingsPlanPurchased`: Savings Plan purchased\n- `cudApproval`: committed use discount (CUD) purchase requires approval\n- `cudPurchased`: CUD purchased\n- `dataIntegrationSyncFailure`: Data integration sync failures\n- `awsBillingDataImport`: AWS Billing Data Import Alert\n\nRequires Manage settings; no other permission is checked.\n\nEvery destination channel must be supported by every subscribed type, or the response is `422`\n`customers.channel_not_supported`:\n\n- Email and Slack only: `expertInsights`, `dataIntegrationSyncFailure`\n- Email, Slack, and Microsoft Teams: every other property\n- A Teams destination on a supported type is still `422` `validation_failed` when the tenant has\n no Teams entitlement",
"properties": {
"newInvoices": {
"type": "object",
"additionalProperties": false,
"description": "Billing profiles this notification applies to. Omit `billingProfileIds`, or send an empty array, to include every billing profile in the tenant. An id outside the tenant is rejected with `422`, the same error as an unknown id.",
"properties": {
"billingProfileIds": {
"type": "array",
"description": "Billing-profile ids in this tenant, shaped like `ent_01HEXAMPLEBILLING0001`. This API does not list billing profiles, and `GET /billing/v1/invoices` does not return these ids. Empty or omitted means every billing profile in the tenant. A read of an omitted or empty list returns the field absent. An explicit list is returned in the order sent. A duplicate id is rejected with `422`.",
"items": {
"type": "string",
"minLength": 1,
"example": "ent_01HEXAMPLEBILLING0001"
}
}
}
},
"newProformaInvoices": {
"type": "object",
"additionalProperties": false,
"description": "Billing profiles this notification applies to. Omit `billingProfileIds`, or send an empty array, to include every billing profile in the tenant. An id outside the tenant is rejected with `422`, the same error as an unknown id.",
"properties": {
"billingProfileIds": {
"type": "array",
"description": "Billing-profile ids in this tenant, shaped like `ent_01HEXAMPLEBILLING0001`. This API does not list billing profiles, and `GET /billing/v1/invoices` does not return these ids. Empty or omitted means every billing profile in the tenant. A read of an omitted or empty list returns the field absent. An explicit list is returned in the order sent. A duplicate id is rejected with `422`.",
"items": {
"type": "string",
"minLength": 1,
"example": "ent_01HEXAMPLEBILLING0001"
}
}
}
},
"paymentReminders": {
"type": "object",
"additionalProperties": false,
"description": "Billing profiles this notification applies to. Omit `billingProfileIds`, or send an empty array, to include every billing profile in the tenant. An id outside the tenant is rejected with `422`, the same error as an unknown id.",
"properties": {
"billingProfileIds": {
"type": "array",
"description": "Billing-profile ids in this tenant, shaped like `ent_01HEXAMPLEBILLING0001`. This API does not list billing profiles, and `GET /billing/v1/invoices` does not return these ids. Empty or omitted means every billing profile in the tenant. A read of an omitted or empty list returns the field absent. An explicit list is returned in the order sent. A duplicate id is rejected with `422`.",
"items": {
"type": "string",
"minLength": 1,
"example": "ent_01HEXAMPLEBILLING0001"
}
}
}
},
"creditUtilization": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"quotaUtilization": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"cloudIncidents": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"newSkuUsage": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"dailyDigest": {
"type": "object",
"additionalProperties": false,
"description": "Allocation rules included in a daily or weekly digest. At least one id is required.",
"required": [
"allocationIds"
],
"properties": {
"allocationIds": {
"type": "array",
"minItems": 1,
"description": "Allocation rule ids from `GET /analytics/v1/allocations`. At least one id is required. A read returns the ids in the order sent. A duplicate, or an id outside the tenant, is rejected with `422`.",
"items": {
"type": "string",
"minLength": 1,
"example": "alloc_abc"
}
}
}
},
"weeklyDigest": {
"type": "object",
"additionalProperties": false,
"description": "Allocation rules included in a daily or weekly digest. At least one id is required.",
"required": [
"allocationIds"
],
"properties": {
"allocationIds": {
"type": "array",
"minItems": 1,
"description": "Allocation rule ids from `GET /analytics/v1/allocations`. At least one id is required. A read returns the ids in the order sent. A duplicate, or an id outside the tenant, is rejected with `422`.",
"items": {
"type": "string",
"minLength": 1,
"example": "alloc_abc"
}
}
}
},
"monthlyDigest": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"expertInsights": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"insights": {
"type": "object",
"additionalProperties": false,
"description": "Optional insight filters. An empty or omitted list means every value of that filter. An insight must match every criterion across `pillars`, `severities`, and `providers`. A read of an omitted or empty list returns that field absent. An explicit list is returned in the order sent. A repeated value is rejected with `422`.",
"properties": {
"pillars": {
"type": "array",
"description": "Insight pillars. Empty or omitted means all pillars.",
"items": {
"type": "string",
"enum": [
"cost",
"operations",
"performance",
"security",
"compliance"
],
"x-enumDescriptions": {
"cost": "Cost. Notify for insights in the Cost category.",
"operations": "Operations. Notify for insights in the Operations category.",
"performance": "Performance. Notify for insights in the Performance category.",
"security": "Security. Notify for insights in the Security category.",
"compliance": "Compliance. Notify for insights in the Compliance category."
}
}
},
"severities": {
"type": "array",
"description": "Insight severities. Empty or omitted means all severities.",
"items": {
"type": "string",
"enum": [
"critical",
"high",
"medium",
"low"
],
"x-enumDescriptions": {
"critical": "Critical. Notify for Critical insights.",
"high": "High. Notify for High insights.",
"medium": "Medium. Notify for Medium insights.",
"low": "Low. Notify for Low insights."
}
}
},
"providers": {
"type": "array",
"description": "Insights provider ids such as `aws`, `gcp`, `azure`, `azure-ad`, `general`, `google-cloud-source`, `google-workspace`, `k8s`, `oci`, and `vmware`. These are the ids Insights resources use, not invoice platform ids such as `amazon-web-services`. Empty or omitted means all providers. Available ids depend on the tenant's connected accounts. Each value is a non-empty string.",
"items": {
"type": "string",
"minLength": 1,
"example": "aws"
}
}
}
},
"costAnomalies": {
"type": "object",
"additionalProperties": false,
"description": "Cost-anomaly notification settings: minimum severity, excess-cost threshold, allocation scope, and\noptional resend controls.\n",
"required": [
"minSeverity",
"minExcessCost",
"allocations"
],
"properties": {
"minSeverity": {
"type": "string",
"enum": [
"warning",
"critical"
],
"x-enumDescriptions": {
"warning": "Warning and above. A missing stored severity (Console \"All severity levels\") is also returned as `warning`.",
"critical": "Critical."
},
"description": "`warning` — warning and above. `critical` — critical only. There is no `information` or `all` value; a write of `all` is rejected with `422`. Clients may send only `warning` or `critical`. Responses return only `warning` or `critical`. A missing or empty stored severity (console \"All severity levels\") is returned as `warning`. `critical` is stored and returned as `critical`.",
"example": "warning"
},
"minExcessCost": {
"description": "Minimum excess cost, as Money. Notify when excess cost is above this amount, not total spend.\n`100.00` USD means $100. `currency` must be `USD`; any other currency is rejected with `422`. A\nnegative amount is rejected with `422`. A fractional amount is rejected with `422` (`100.99` is not a\nwhole number of dollars). `100` and `100.00` are both accepted. `0` and `0.00` are accepted. Amounts\nabove 1,000,000,000 whole dollars, and forms such as `Inf`, exponents, a leading `+`, or underscores,\nare rejected with `422`. Responses return the amount as `\"100.00\"`.\n",
"allOf": [
{
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$",
"description": "Decimal monetary amount at ISO 4217 minor-unit precision (string).",
"example": "100.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code.",
"example": "USD"
}
}
}
]
},
"allocations": {
"type": "object",
"additionalProperties": false,
"description": "Allocation scope for cost-anomaly notifications. `ids` are allocation ids from `GET\n/analytics/v1/allocations`. An id outside the caller's tenant is rejected with `422` without saying\nwhether it exists elsewhere.\n\n`mode: all` means every allocation with anomaly detection enabled, including anomalies that are not\ntied to an allocation, and it carries an empty `ids`. `include` and `exclude` require at least one\nid. `mode: all` with a non-empty `ids`, and `include` or `exclude` with an empty `ids`, are rejected\nwith `422`. `ids` are an ordered list: the server stores and returns them in the order sent, and it does\nnot sort or drop entries. A duplicate id is rejected with `422`.\n",
"required": [
"mode",
"ids"
],
"properties": {
"mode": {
"type": "string",
"enum": [
"all",
"include",
"exclude"
],
"x-enumDescriptions": {
"all": "Include all enabled allocations, including anomalies that are not tied to an allocation. Send an empty `ids`.",
"include": "Include specific allocations. Requires at least one id.",
"exclude": "Exclude specific allocations. Requires at least one id."
},
"description": "`all` — every allocation with anomaly detection enabled (and unallocated anomalies). `include` — only the listed ids. `exclude` — all enabled allocations except the listed ids. `all` cannot be sent with a non-empty `ids`. `include` and `exclude` cannot be sent with an empty `ids`.",
"example": "include"
},
"ids": {
"type": "array",
"description": "Allocation ids, in the order sent. A read returns that same order. A duplicate id is rejected\nwith `422`. Empty when `mode` is `all`. Non-empty when `mode` is `include` or `exclude`.\n",
"items": {
"type": "string",
"minLength": 1
},
"example": [
"alloc_abc",
"alloc_def"
]
}
}
},
"repeat": {
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"description": "Resend controls for an active cost anomaly. Omit the whole `repeat` object when neither control is\nset. An empty object is rejected with `422`.\n",
"properties": {
"everyHours": {
"type": "integer",
"minimum": 1,
"maximum": 24,
"description": "Resend until the anomaly is inactive, every N hours (1–24).\n",
"example": 24
},
"whenCostGrows": {
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"description": "Resend when the anomaly's cost grows. At least one of `percentIncrease` or `minIncrease` is required.\nAn object with only `withinHours`, only `match`, or neither amount is rejected with `422`.\n\n- both `percentIncrease` and `minIncrease` present → `match` is\n required (`or` or `and`)\n- exactly one of `percentIncrease` or `minIncrease` present → omit\n `match` (percentage-only or value-only)\n- neither amount present → rejected with `422`\n\n`percentIncrease` is an integer percent (`10` means 10 percent) and must be at least 1. Omit\n`withinHours` when the time window is off.",
"properties": {
"match": {
"type": "string",
"enum": [
"or",
"and"
],
"x-enumDescriptions": {
"or": "Resend when either the percent increase or the dollar increase is reached.",
"and": "Resend only when both are reached."
},
"description": "How to combine percent and dollar growth when both are set. Required when both amounts are present; omit when only one amount is present.",
"example": "or"
},
"percentIncrease": {
"type": "integer",
"minimum": 1,
"description": "Minimum percent cost increase that triggers a resend. `10` means 10 percent. Must be greater than 0.\n",
"example": 10
},
"minIncrease": {
"description": "Minimum cost growth that triggers a resend, as Money. Must be a positive whole number of dollars.\n`150.00` USD means $150. `currency` must be `USD`; any other currency is rejected with `422`. `0`,\n`0.00`, and a negative amount are rejected with `422`. A fractional amount is rejected with `422`\n(`150.99` is not a whole number of dollars). `150` and `150.00` are both accepted. Amounts above\n1,000,000,000 whole dollars, and forms such as `Inf`, exponents, a leading `+`, or underscores, are\nrejected with `422`. Responses return the amount as `\"150.00\"`.\n",
"allOf": [
{
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$",
"description": "Decimal monetary amount at ISO 4217 minor-unit precision (string).",
"example": "100.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code.",
"example": "USD"
}
}
}
]
},
"withinHours": {
"type": "integer",
"minimum": 1,
"maximum": 24,
"description": "Optional window in hours for the growth check (1–24).",
"example": 6
}
}
}
}
}
}
},
"savingsPlanApproval": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"savingsPlanPurchased": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"cudApproval": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"cudPurchased": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"dataIntegrationSyncFailure": {
"type": "object",
"additionalProperties": false,
"description": "A present empty object means this type is subscribed, for example `\"creditUtilization\": {}`. The object has no fields. On a patch property, `null` unsubscribes that type and is a different value.",
"example": {}
},
"awsBillingDataImport": {
"type": "object",
"additionalProperties": false,
"description": "Billing profiles this notification applies to. Omit `billingProfileIds`, or send an empty array, to include every billing profile in the tenant. An id outside the tenant is rejected with `422`, the same error as an unknown id.",
"properties": {
"billingProfileIds": {
"type": "array",
"description": "Billing-profile ids in this tenant, shaped like `ent_01HEXAMPLEBILLING0001`. This API does not list billing profiles, and `GET /billing/v1/invoices` does not return these ids. Empty or omitted means every billing profile in the tenant. A read of an omitted or empty list returns the field absent. An explicit list is returned in the order sent. A duplicate id is rejected with `422`.",
"items": {
"type": "string",
"minLength": 1,
"example": "ent_01HEXAMPLEBILLING0001"
}
}
}
}
}
}
]
}
}
}
Errors
On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.
HTTP status to exit code mapping
| HTTP status | Exit code | Error code | Meaning |
|---|---|---|---|
| 400, 422 | 30 | VALIDATION_ERROR | The arguments or request body were rejected. Review the command's flags and payload. |
| 401 | 10 | AUTHENTICATION_FAILED | Not signed in, or the API token is invalid. Run dci login or check DCI_API_KEY. |
| 403 | 11 | PERMISSION_DENIED | The DoiT user or the active customer context does not have access. |
| 409 | 21 | RESOURCE_CONFLICT | The operation conflicts with the resource's current state. |
| 500 | 40 | API_SERVER_ERROR | The API failed to process the request. Retryable; contact DoiT support if it persists. |
Related
- create-user-notification — Create a personal notification for a user
- delete-customer-notification — Delete an organization notification
- delete-user-notification — Delete a personal notification
- get-customer-notification — Get an organization notification
- get-user-notification — Retrieve a personal notification
- list-customer-notifications — List organization notifications
- list-user-notifications — List personal notifications for a user
- update-customer-notification — Update an organization notification
- update-user-notification — Update a personal notification
- API reference: POST /customers/v1/notifications
Aliases: createcustomernotification