Contacts

The contact object:

{
  "id": "9ffb8d6d-…",
  "object": "contact",
  "name": "Jane Ops",
  "email": "[email protected]",
  "phone": "+3706…",
  "groups": [ { "id": "391e64ad-…", "name": "On-Call" } ],
  "created_at": "2026-08-24T16:00:00.000Z",
  "updated_at": "2026-08-24T16:05:00.000Z"
}

List contacts

GET /v1/contacts — newest first. Query: limit, cursor (pass the previous page's next_cursor; same for GET /v1/contact-groups).

curl https://watchfor.io/api/v1/contacts \
  -H "Authorization: Bearer wf_live_YOUR_KEY"

Create a contact

POST /v1/contacts — requires write scope. Body: name (required), email (required, unique per organization), phone, groupIds (array of contact-group ids to add the contact to right away). Supports Idempotency-Key.

curl -X POST https://watchfor.io/api/v1/contacts \
  -H "Authorization: Bearer wf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Ops",
    "email": "[email protected]",
    "groupIds": ["391e64ad-…"]
  }'

Returns 201 with the contact. A duplicate email returns 409 conflict.

Get / update / delete a contact

GET /v1/contacts/{id} · PATCH /v1/contacts/{id} · DELETE /v1/contacts/{id} (write scope for PATCH/DELETE)

PATCH is partial — send only what changes: name, email, phone, groupIds. Omitting groupIds leaves memberships unchanged; [] removes the contact from all groups.

curl -X PATCH https://watchfor.io/api/v1/contacts/9ffb8d6d-… \
  -H "Authorization: Bearer wf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+3706…", "groupIds": [] }'

DELETE returns 204 No Content and removes the contact from every group.

Contact groups

GET /v1/contact-groups — list groups. Use the ids in groupIds above. GET /v1/contact-groups/{id} includes the member list.

{
  "object": "list",
  "data": [
    {
      "id": "391e64ad-…",
      "object": "contact_group",
      "name": "On-Call",
      "description": null,
      "is_default": true,
      "member_count": 3,
      "created_at": "2026-07-01T08:00:00.000Z",
      "updated_at": "2026-08-24T16:05:00.000Z"
    }
  ],
  "has_more": false
}

Create / update / delete a group

POST /v1/contact-groups (name required, description, contactIds) · PATCH /v1/contact-groups/{id} (partial; contactIds: [] empties the group) · DELETE /v1/contact-groups/{id} — all require write scope.

curl -X POST https://watchfor.io/api/v1/contact-groups \
  -H "Authorization: Bearer wf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Platform team", "contactIds": ["9ffb8d6d-…"] }'

A duplicate name returns 409. Deleting the default group returns 409 — mark another group as default (dashboard) first; deletion also cleans the group out of every monitor's notification settings. Wiring groups to notification channels and on-call escalation stays in the dashboard.