CheckCentral API Documentation: createCheck Endpoint

Binary Fortress Software — Thu, 21 Feb 2019 19:53:05 GMT

The CheckCentral API provides an endpoint for creating checks programmatically. All of the configuration options are available through the API, detailed below. To create a new check through the API, you will require an API token for your organization with Read/Write access. Organization administrators can create tokens through the API portal on your dashboard.

The endpoint is located at https://api.checkcentral.cc/createCheck/?apiToken=APITOKEN where the APITOKEN placeholder is replaced with your valid token. The request must be made with the Content-Type header set to application/json. The body of the request should contain as many of the properties listed below as required to define the check. Any properties not passed will be set to their default value.

For example, to create a new check that:

Receives messages at the address "demo+apicheck@mycheckcentral.cc"
Expects messages every two hours
Expects messages only on weekdays
Is set to Failure unless the message subject is "Message Success" or the message body has the text "No Errors Reported"

you would send the following json in the body of the request:

Code
Copy
Select All

{
  "name": "An API Check",
  "email_alias": "apicheck",
  "interval_type": "hour",
  "interval_value": 2,
  "active_days": [
    "mon",
    "tue",
    "wed",
    "thu",
    "fri"
  ],
  "success_conditions": {
    "required_conditions": "any",
    "conditions": [
      {
        "message_field": "subject",
        "matches": "exactly",
        "value": "Message Success"
      },
      {
        "message_field": "body",
        "matches": "contains",
        "value": "No Errors Reported"
      }
    ]
  }
}

The check data must include a name property, as well as at least one of email_alias and matching_conditions to allow the check to be matched against incoming messages.

The complete list of possible properties for check configuration are as follows:

Check Structure

Parameter	Type/Allowed Values	Default
`name` The name for the new check. The `name` parameter is required.	String
`email_alias` The plus alias for the check. This will be used to generate the custom email address for the Check along with your organization account name: account_name+email_alias@mycheckcentral.cc. At least one of the `email_alias` or `matching_conditions` parameters must be specified.	String
`matching_conditions` The rules that will be used to match incoming messages. See the definition of a ConditionGroup below. At least one of the `email_alias` or `matching_conditions` parameters must be specified.	ConditionGroup	`{}`
`group_id` The ID of the group to assign this check. IDs may be retrieved from the `getGroups` API endpoint.	String
`description` An optional text description for this check.	String
`label` An optional label for this check. Check labels can be used to display checks together within a group, or to associate checks across multiple check groups.	String
`interval_type` The interval unit CheckCentral will use to calculate the expected arrival time of incoming messages	One of: minute hour day week month unscheduled	`day`
`interval_value` The number of interval units (see above) used when calculating the expected arrival of incoming messages.	Integer	`1`
`overdue_minutes` How many minutes after the interval has elapsed CheckCentral will wait before flagging the check as failed.	Integer	`30`
`restore_minutes` This setting is only applicable to checks with an frequency set to `unscheduled`. How many minutes CheckCentral will wait before automatically setting this check to Success after receiving a Failure or Warning. Set to 0 to disable this option.	Integer	`30`
`window_start` An optional time of day when messages will begin to be received.	String	`00:00`
`window_end` An optional time of day when messages will cease to be received.	String	`00:00`
`active_days` Pass an array of days to indicate which days the check should expect to receive messages.	An array containing either `"all"`, or any of: sun mon tue wed thu fri sat	`[ "all" ]`
`schedule_template_id` The ID of a check template that this check will use for its schedule configuration. Check template IDs can be retrieved with the `getCheckTemplates` API endpoint. This will override any schedule settings defined for this check.	String
`enabled_notifications` Pass an array of personal notification services to configure the check to send alerts via those services.	An array containing any of: email sms webpush push pushbullet pushover	`[]`
`enabled_notification_channels` Pass an array of organization notification channel IDs to configure the check to send alerts via those services. IDs may be retrieved from the `getNotificationChannels` API endpoint.	Array[String]	`[]`
`enabled_ticketing_systems` Pass an array of organization external ticketing system IDs to configure the check to create and update tickets via those services. IDs may be retrieved from the `getTicketingSystems` API endpoint.	Array[String]	`[]`
`notify_returned_to_success` Checks with this flag will send an alert when they are restored to a success state by an incoming message.	Bool	`true`
`notify_outside_window` Checks with this flag set to false will only send alerts during the time window and active days configured above.	Bool	`true`
`notify_activity_attachments` This parameter controls how CheckCentral will include the original message that triggered an alert when sending email notifications.	One of: attachment dont_include embed	`attachment`
`notify_consecutive_alerts` This parameter controls when CheckCentral will send alerts about repeated failure or warning messages.	One of: always first after_n every_nth first_after_n	`always`
`notify_consecutive_alerts_limit` If notify_consecutive_alerts is set to either after_n or every_nth, this parameter configures how many consecutive failures or consecutive warnings will trigger alerts.	Integer	1
`notify_failure_grace_period` The number of minutes this check will wait to send alerts about failures. If the check is returned to successful status before this period elapses, any pending alerts will be cancelled.	Integer	`0`
`notifications_template_id` The ID of a check template that this check will use for its notifications configuration. Check template IDs can be retrieved with the `getCheckTemplates` API endpoint. This will override any notification settings defined for this check.	String
`default_status` The default status for incoming messages that don't match against any of the conditions below.	One of: success warning failure	`failure`
`success_conditions` The rules that determine whether incoming messages will be set to success. See the definition of a ConditionGroup below.	ConditionGroup	`{}`
`warning_conditions` The rules that determine whether incoming messages will be set to warning. See the definition of a ConditionGroup below.	ConditionGroup	`{}`
`failure_conditions` The rules that determine whether incoming messages will be set to failure. See the definition of a ConditionGroup below.	ConditionGroup	`{}`
`status_template_id` The ID of a check template that this check will use for its status rules. Check template IDs can be retrieved with the `getCheckTemplates` API endpoint. This will override any success, warning, or failure rules defined for this check.	String

ConditionGroup

Parameter	Type/Allowed Values	Default
`required_conditions` This parameter controls whether incoming messages must meet any or all of the conditions defined below to be considered a match.	One of: all any	`"all"`
`condense_whitespace` If this flag is set, all of the conditions defined in this group will treat multiple whitespace characters as a single space.	Bool	`false`
`combine_attachment_content` If this flag is set, the conditions defined in this group will treat the text contents of all attachments as a single file for the purposes of processing conditions.	Bool	`false`
`conditions` The list of conditions for this ConditionGroup to match messages against. See the definition of a Condition below.	Array[Condition]	`[]`

Condition

Parameter Type/Allowed Values Default

Parameter	Type/Allowed Values	Default
`message_field` Which part of the incoming message will be examined for this condition.	One of: subject body to cc attachments from originally_to body_html	`subject`
`matches` What matching rule this condition will use.	One of: contains not_contains exactly empty not_empty has_attachments has_no_attachments filename_contains filename_not_contains filename_exact text_contains text_not_contains complex_match complex_filename_match complex_text_match regex_match regex_filename_match regex_text_match	`contains`
`value` The value to use with the above matching rule and message component.	String

message_field

Which part of the incoming message will be examined for this condition.

One of:

subject
body
to
cc
attachments
from
originally_to
body_html

subject

matches

What matching rule this condition will use.

One of:

contains
not_contains
exactly
empty
not_empty
has_attachments
has_no_attachments
filename_contains
filename_not_contains
filename_exact
text_contains
text_not_contains
complex_match
complex_filename_match
complex_text_match
regex_match
regex_filename_match
regex_text_match

contains

value

The value to use with the above matching rule and message component.

String

CheckCentral RSS: CheckCentral API Documentation: createCheck Endpoint

CheckCentral API Documentation: createCheck Endpoint

CodeCopySelect All

Check Structure

ConditionGroup

Condition

Code
Copy
Select All