API Documentation | Contact Group

Contact groups are your means of being notified about alerts. Each group can have one to many users and means of contact. If Bob wants to be alerted via SMS and Email, Sally wants an IM, and the SA team wants an email to a shared account, this is all setup in the contact group. Once a contact group is created you associate it with a rule_set to be alerted when a rule is violated.

Fields

_cid string
The primary key
"/contact_group/1234"
A string containing a contact_group cid
_last_modified number
The point in time when this object was last updated.
1356998400
A positive integer that contains the number of seconds since the UNIX epoch (midnight on January 1st, 1970 in Greenwich, United Kingdom)
_last_modified_by string
The object id of the last user to modify this object.
"/user/923"
A string containing a user cid
aggregation_window number
The aggregation window.
300
A number containing an integer greater than or equal to zero
alert_formats object
The formatting of alert messages sent to this contact group when alerts occur.
An object
long_message string
The bulk of the message used in long form alert messages.
A string containing freeform text
long_subject string
The subject used in long form alert messages.
A string containing freeform text
long_summary string
The brief summary used in long form alert messages.
A string containing freeform text
short_message string
The subject used in short form alert messages
A string containing freeform text
short_summary string
The brief summary used in short form alert messages
A string containing freeform text
always_send_clear boolean
Send clear notifications even if the alert is in maintenance
Either true or false
contacts object
The contacts in this contact group
{"users":[{"_contact_info":"snuffy@example.com","user":"/user/923","method":"email"},{"_contact_info":"12125550199","user":"/user/923","method":"sms"}],"external":[{"contact_info":"12125550100","method":"sms"},{"contact_info":"bert@example.com","method":"xmpp"},{"contact_info":"ernie@example.com","method":"email"}]}
An object
external array
External contacts that do not have Circonus user accounts that should be contacted within this contact group
An array
object (zero or more times)
Details on how to contact the external contacts.
An object
contact_info string
The specific contact info that Circonus should use.
A string containing an email address, XMPP address, SMS number, etc.
method string
The method Circonus should use to contact the external contact (i.e., what kind of contact info is stored in contact_info).
A string containing either 'email', 'sms', 'irc', 'http', 'pagerduty', 'victorops', 'slack' or 'opsgenie'
users array
Circonus users in this contact group
An array
object (zero or more times)
Details on how to contact the Circonus users.
An object
_contact_info string
A read only field showing the actual current stored contact details for the user for the given contact method. For informational purposes only.
A string containing freeform text
method string
The method Circonus should use to contact the user.
A string containing either 'email', 'sms', 'irc', 'http' or 'pagerduty'
user string
The user to contact.
A string containing a user cid
escalations array
The alerting system is able to escalate alerts to further contact groups if an alert sent to this contact group is not acknowledged or resolved.
[{"after":900,"contact_group":"/contact_group/426"},null,null,null,null]
An array
object
Details of how to escalate a severity 1 alert (or null, indicating not to escalate)
An object or null
after number
How long to wait before escalating a severity 1 alert
A number containing an integer number of seconds; minimum value: 300 (5 minutes)
contact_group string
Which contact group to escalate a severity 1 alert to
A string containing a contact_group cid
object
Details of how to escalate a severity 2 alert (or null, indicating not to escalate)
An object or null
after number
How long to wait before escalating a severity 2 alert
A number containing an integer number of seconds; minimum value: 300 (5 minutes)
contact_group string
Which contact group to escalate a severity 2 alert to
A string containing a contact_group cid
object
Details of how to escalate a severity 3 alert (or null, indicating not to escalate)
An object or null
after number
How long to wait before escalating a severity 3 alert
A number containing an integer number of seconds; minimum value: 300 (5 minutes)
contact_group string
Which contact group to escalate a severity 3 alert to
A string containing a contact_group cid
object
Details of how to escalate a severity 4 alert (or null, indicating not to escalate)
An object or null
after number
How long to wait before escalating a severity 4 alert
A number containing an integer number of seconds; minimum value: 300 (5 minutes)
contact_group string
Which contact group to escalate a severity 4 alert to
A string containing a contact_group cid
object
Details of how to escalate a severity 5 alert (or null, indicating not to escalate)
An object or null
after number
How long to wait before escalating a severity 5 alert
A number containing an integer number of seconds; minimum value: 300 (5 minutes)
contact_group string
Which contact group to escalate a severity 5 alert to
A string containing a contact_group cid
name string
The contact group name
"Foo"
A string containing freeform text
reminders array
As part of the alerts system it is possible to get reminders sent after a user configurable number of minutes for open alerts.
[5,0,0,15,30]
An array with an entry for each severity level
number
The duration before reminders are sent for severity 1 alerts (or 0 meaning no reminders will be sent for severity 1 alerts)
A number containing an integer number of minutes
number
The duration before reminders are sent for severity 2 alerts (or 0 meaning no reminders will be sent for severity 2 alerts)
A number containing an integer number of minutes
number
The duration before reminders are sent for severity 3 alerts (or 0 meaning no reminders will be sent for severity 3 alerts)
A number containing an integer number of minutes
number
The duration before reminders are sent for severity 4 alerts (or 0 meaning no reminders will be sent for severity 4 alerts)
A number containing an integer number of minutes
number
The duration before reminders are sent for severity 5 alerts (or 0 meaning no reminders will be sent for severity 5 alerts)
A number containing an integer number of minutes
tags array

An array of tags. The tags in the array are automatically sorted, deduplicated and transformed into their lowercase canonical form.
string (zero or more times)
An associated tag
A tag is just a string, with or without a colon, such as 'foo', 'bar', 'datacenter:london', or 'os:linux'. The part of the string before the colon is considered the category the tag is in; Tag strings without a colon will place the string in the 'uncategorized' category. Circonus will lowercase the contents of the string before storing it.

Example

Fetching Contact Groups

Fetching details for a contact group is as simple as performing a GET on the contact group cid:

GET /contact_group/1234
{"aggregation_window":300,"escalations":[{"contact_group":"/contact_group/426","after":900},null,null,null,null],"_cid":"/contact_group/1234","name":"Foo","_last_modified_by":"/user/923","reminders":[10,0,0,15,30],"_last_modified":1356998400,"contacts":{"external":[{"contact_info":"12125550100","method":"sms"},{"method":"xmpp","contact_info":"bert@example.com"},{"method":"email","contact_info":"ernie@example.com"}],"users":[{"method":"email","user":"/user/923","_contact_info":"snuffy@example.com"},{"user":"/user/923","_contact_info":"12125550199","method":"sms"}]}}

From this we can see a lot of important things

Creating and Updating Contact Groups

Creating a new contact group is as simple as making a HTTP POST request to /contact_group and passing JSON representing the new contact group:

POST /contact_group
{"contacts":{"users":[],"external":[{"contact_info":"gonzo@example.com","method":"email"},{"contact_info":"cookie.monster@example.com","method":"email"}]},"name":"Fuzzy and Blue"}

As is usual, the POST request returns the full JSON in the response (incuding the new contact group's cid, and any default and read only values)

Contact groups can be updated simply by using the PUT HTTP method with new field values:

PUT /contact_group/1701
{"contacts":{"external":[{"contact_info":"gonzo@example.com","method":"email"},{"contact_info":"cookie.monster@example.com","method":"email"},{"contact_info":"fozzie@example.com","method":"email"}],"users":[]},"name":"Fuzzy and Blue (and Orange)"}

(You must re-put all contacts when adding to them to avoid removing contacts)

As is normal with Circonus the PUT method returns the full JSON of the updated contact group in response.

Listing and Filtering Contact Groups

You can list all contact groups for your account simply by requesting the /contact_group path with a simple GET request.

GET /contact_group
[{"contacts":{"external":[{"method":"sms","contact_info":"12125550100"},{"contact_info":"bert@example.com","method":"xmpp"},{"method":"email","contact_info":"ernie@example.com"}],"users":[{"user":"/user/923","_contact_info":"snuffy@example.com","method":"email"},{"_contact_info":"12125550199","user":"/user/923","method":"sms"}]},"_last_modified":1356998400,"reminders":[10,0,0,15,30],"_last_modified_by":"/user/923","name":"Foo","_cid":"/contact_group/1234","escalations":[{"after":900,"contact_group":"/contact_group/426"},null,null,null,null],"aggregation_window":300},{"escalations":[null,null,null,null,null],"aggregation_window":300,"_cid":"/contact_group/1048","reminders":[0,0,0,0,0],"_last_modified_by":"/user/923","name":"Fuzzy and Blue (and Orange)","contacts":{"users":[],"external":[{"contact_info":"cookie.monster@example.com","method":"email"},{"contact_info":"fozzie@example.com","method":"email"},{"contact_info":"gonzo@example.com","method":"email"}]},"_last_modified":1383318267}]

This request can be also filtered in the usual manner; for example, to search for a contact group with the word "Blue" in the name and filter for an aggregation_window of 300:

Note on filtering, you should not use a filter without a search parameter as well, using just a filter may become unsupported in the future. Please see the section on API searching.

GET /contact_group?search=*Blue*&f_aggregation_window=300
[{"_cid":"/contact_group/1048","aggregation_window":300,"escalations":[null,null,null,null,null],"_last_modified":1383318267,"contacts":{"users":[],"external":[{"contact_info":"cookie.monster@example.com","method":"email"},{"contact_info":"fozzie@example.com","method":"email"},{"method":"email","contact_info":"gonzo@example.com"}]},"name":"Fuzzy and Blue (and Orange)","reminders":[0,0,0,0,0],"_last_modified_by":"/user/923"}]

Removing Contact Groups

Contact groups can be simply removed by using the DELETE HTTP method on the cid:

DELETE /contact_group/1701

This will have the effect of removing them from all rule sets that are currently using them