Getting Started #

The eCardWidget API lets you send eCards and keep your team-member directory in sync from your own systems (HR/CRM, donation platforms, internal tools). The same endpoints power the official Zapier integration, so you can build directly or use Zapier.

Base URL #

https://app.ecardwidget.com

All API paths below are relative to this host (e.g. /v2/api/pub/ecard-actions/send-ecard).

Authentication #

Every request authenticates with your account API key, sent as a Bearer token:

Authorization: Bearer <YOUR_API_KEY>

Find and manage keys in the dashboard under Settings → Developers → API Keys (https://app.ecardwidget.com/s/settings/developers). Notes:

  • A key is shown in full only once, at creation. After that only the first/last 4 characters are displayed — store it somewhere safe.
  • Keys are labeled so you can tell integrations apart; deleting a label/key revokes it immediately.
  • Every call is scoped to the account that owns the key (tenant-isolated). You can only access your own widgets, eCards, and directory.
curl https://app.ecardwidget.com/v2/api/pub/team-member-actions/departments \
  -H "Authorization: Bearer $ECW_API_KEY"

Response format #

Most endpoints return a standard envelope:

{
  "success": true,
  "data": { },
  "messages": []
}
  • success — boolean.
  • data — object or array, endpoint-specific. Some list endpoints also include a meta object (pagination cursors etc.).
  • messages — array of human-readable strings; populated with error/info messages.

Exception: POST /v2/api/pub/ecard-actions/send-ecard returns a flat object (no data wrapper) — the result fields are at the top level. See send-ecard.md.

Errors #

Errors use standard HTTP status codes with success: false and a messages array:

Status Meaning
400 Bad request — missing/invalid parameter (details in messages)
401 Missing or invalid API key
403 Authenticated, but not allowed for this account
404 Resource not found, or not owned by your account
422 Validation failed (e.g. required custom fields missing)
429 Rate limited — retry after a short delay 
{ "success": false, "data": null, "messages": ["Missing or invalid recipientEmail parameter"] }

Rate limiting #

Keep request volume reasonable. If you exceed the limit you'll receive 429; back off and retry. For large initial loads (e.g. importing an entire employee base), prefer the in-app spreadsheet importer and use the API for ongoing deltas — see directory-sync.md.

IDs are vanity IDs #

eCards, widgets, and sent/share records are identified by short opaque vanity IDs (e.g. e4xgrzltk), not numeric DB IDs. Treat them as opaque strings.

Next steps #

← PreviousIntroductionNext →Developer Portal
Documentation
Getting Started