Using Triggers

Overview

Triggers allow you to pair actions with events in order to create powerful automated workflows. Whereas actions allow you to do something once, triggers allow you to ensure actions are executed each time an event occurs. Put another way, you can tag an application once with an action, or ensure an application is automatically tagged when it is marked as hired with a trigger.

Available Events

You may retrieve a list of available events by making a GET request to https://api.applicant-tracking.com/api/v1/workflow/events. The payload will be an array of event types:

[
  "app_sent_to_integration",
  "app_status_updated",
  "app_viewed",
  "applicant_email_received",
  "applicant_hired_file_added",
  "applicant_marked_as_hired",
  "applicant_new",
  "applicant_sms_received",
  "background_check_requested",
  "background_check_status_updated",
  "background_check_completed",
  "background_check_completed_pass",
  "background_check_completed_fail",
  "company_registered",
  "custom_fields_schema_definition_update",
  "daily_maintenance",
  "everify_request_data_returned",
  "everify_request_started",
  "i9_cancelled",
  "i9_ordered",
  "i9_step_one_complete",
  "i9_step_two_complete",
  "last_open_position_filled",
  "offer_letter_signed"
]

Of course, not every event type is compatible with each action type. To see a list of compatible events for a specific action type, you can pass an optional action_type parameter to the call above. For example, https://api.applicant-tracking.com/api/v1/workflow/events?action_type=tag_app yields:

[
  "applicant_marked_as_hired",
  "applicant_new"
]

Creating a Trigger

Once you've decided on an event type and an action type, you can make a request to create a trigger.

Each action type requires a different set of data in order to create a trigger. For detail on data required for a specific action, refer to https://api.atsanywhere.io/docs/using-actions#section-action-data.

Make a POST request to https://api.applicant-tracking.com/api/v1/triggers with a body that contains the event type, action type and required data:

{
  "event_type": "applicant_marked_as_hired",
  "action_type": "tag_app",
  "data": {
    "tag_text": "Tagging an app automatically!"
  }
}

A successful request will return data about the trigger you've created:

{
  "id": "1",
  "company_id": "1",
  "custom_workflow_id": null,
  "event_type": "applicant_marked_as_hired",
  "action_type": "tag_app",
  "data": {
    "tag_text": "Tagging an app automatically!"
  },
  "conditions": {},
  "created_at": "2020-02-13T20:22:33Z",
  "updated_at": "2020-02-13T20:22:33Z"
}

Now each time an applicant is marked as hired, it will automatically be tagged with the chosen tag text.

Managing Triggers

To view a list of all of your configured triggers, make a GET request to https://api.applicant-tracking.com/api/v1/triggers. To view a specific trigger, add the id to the request URL like https://api.applicant-tracking.com/api/v1/triggers/:id.

You can edit any of your triggers by making a PUT request to https://api.applicant-tracking.com/api/v1/triggers/:id. For example, you can change the text for your automatic tags:

{
  "event_type": "applicant_marked_as_hired",
  "action_type": "tag_app",
  "data": {
    "tag_text": "This is a new tag!"
  }
}

The updated trigger will be returned:

{
  "id": "1",
  "company_id": "1",
  "custom_workflow_id": null,
  "event_type": "applicant_marked_as_hired",
  "action_type": "tag_app",
  "data": {
    "tag_text": "This is a new tag!"
  },
  "conditions": {},
  "created_at": "2020-02-13T20:22:33Z",
  "updated_at": "2020-02-13T20:23:56Z"
}

If you no longer wish for a trigger to execute you may delete it by making a DELETE request to https://api.applicant-tracking.com/api/v1/triggers/:id.