Automations API #

List, inspect, and enable/disable your automations — the rules that automatically send eCards (and optionally rewards) on birthdays, work anniversaries, holidays, fixed dates, and custom rules.

Auth & scope. All endpoints are under https://app.ecardwidget.com/v2/api/automation/… and use your Bearer API key (Authorization: Bearer <YOUR_API_KEY>). The key needs the automations feature scope. Requests are tenant-scoped to the account that owns the key.

Recipients come from your Directory. Automations fire against the team members in your directory (birthdays, hire-date anniversaries, etc.). Keep members current with the Directory Sync API.

---

How automations work (concepts) #

Each automation has an event type and a trigger type:

event_type	Fires on	Typical trigger_type
birthday	a member's birthday	recipient_date
anniversary	a member's hire-date anniversary	recipient_date
custom_field	a custom member date (custom_date_1..N)	recipient_date
onboarding	a member's onboarding milestone	recipient_date
holiday	a named holiday	rule_based
fixed_date	a specific calendar date	fixed_date
rule_based	a computed rule (e.g. "last Friday of the month")	rule_based

Key behaviors:

• Timing is per-automation: send_time (local) + timezone (default America/New_York). Events are matched against the member's local day, so a birthday sends at 9am their time, not the server's.
• Birthday privacy: stored birthdays are year-masked (year 1800); Feb 29 is normalized to Feb 28 so leap-day birthdays still fire every year.
• Milestones / offsets: an automation can send N days before/after the event (e.g. "3 days before").
• Rewards: set gift_card_enabled to attach a reward when the automation fires (see gift-cards.md). Reward automations are subject to your spend limits and provider mode.

---

List automations — GET /v2/api/automation/list #

Query param	Notes
page, perPage	pagination (perPage default 10)
keyword	matches automation name, from-name, or from-email
eventType	filter to one event_type (see table above)
sortBy	id (default), name, event_type, …
sortOrder	ASC / DESC
status	active / inactive (by the enabled flag)

curl "https://app.ecardwidget.com/v2/api/automation/list?eventType=birthday&perPage=25" \
  -H "Authorization: Bearer $ECW_API_KEY"

Response #

{
  "success": true,
  "data": [
    {
      "id": 42,
      "automation_name": "Birthday Rewards",
      "event_type": "birthday",
      "trigger_type": "recipient_date",
      "enabled": true,
      "from_name": "The People Team",
      "from_email": "[email protected]",
      "send_time": "09:00:00",
      "timezone": "America/Chicago",
      "gift_card_enabled": true
    }
  ],
  "meta": { "total_count": 1, "per_page": 25, "page_count": 1, "page": 1 }
}

---

Get one automation — GET /v2/api/automation/findOne/id/{id} #

Returns the full automation configuration including its milestones (offsets/schedule).

curl https://app.ecardwidget.com/v2/api/automation/findOne/id/42 \
  -H "Authorization: Bearer $ECW_API_KEY"

---

Enable / disable — POST /v2/api/automation/toggle #

Turn an automation on or off. Send the automation id and the desired enabled state.

curl -X POST https://app.ecardwidget.com/v2/api/automation/toggle \
  -H "Authorization: Bearer $ECW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "automation": { "id": 42, "enabled": false } }'

Enabling an automation validates its configuration first (a misconfigured automation can't be enabled).

---

Preview upcoming sends — POST /v2/api/automation/previewTrigger #

Dry-run which members/events an automation would match in an upcoming window — useful for validating a new automation before enabling it. Returns the would-be recipients and dates without sending.

---

Create / update / delete #

• POST /v2/api/automation/save — create or update an automation. The payload is rich (event/trigger config, timing, milestones, eCard selection, reward settings) — build it from an existing automation's findOne response as a template.
• DELETE /v2/api/automation/delete/id/{id} — permanently delete an automation.

Dashboard-gated actions. Deleting an automation, and saving a reward-enabled (gift_card_enabled) automation, require an interactive OTP confirmation and are intended to be performed in the dashboard — they can't be completed with an API key alone. Use the API to list, inspect, preview, and toggle; use the dashboard for reward-automation creation and deletion.