Create an alert contact Beta
POST /api/v1/alerting/contacts
Add someone who should hear about outages but has no RankNibbler login, such as a client or an out-of-hours number.
Needs an X-API-Key header whose owner has permission to manage uptime monitors in the app. The call counts once against your daily quota. See Monitoring API: getting started for authentication, rate limits and errors.
Body
| Field | Type | Description |
|---|---|---|
name required | string | What you call this contact. Up to 120 characters. |
methods required | object[] | How to reach them, up to 5. Each is { kind, target, severity }. |
methods[].kind optional | string | email, which is also the default. Other channels are planned; anything else returns 400 today. |
methods[].target required | string | The email address, up to 320 characters. |
methods[].severity optional | string | all (default) for every alert, or high for monitors marked high importance only. |
email optional | string | Shorthand for a single address: { "name": "…", "email": "…" } is the same as one email method with severity all. |
- Two methods with the same address (ignoring case) are collapsed into one.
- A workspace can have up to 200 contacts, each with up to 5 addresses.
Request
Response
201 Created with the contact.
201 · application/json
- {
- "contact": {
- "id": "ct_5b8d1f0a9c2e4d6f7a83",
- "name": "Night shift",
- "methods": [
- { "id": "318", "kind": "email", "target": "[email protected]", "severity": "all", "optedOut": false },
- { "id": "319", "kind": "email", "target": "[email protected]", "severity": "high", "optedOut": false }
- ],
- "createdAt": "2026-09-17T09:02:11.000Z",
- "updatedAt": "2026-09-17T09:02:11.000Z"
- },
- "usage": { "used": 43, "dailyLimit": 100, "tier": "free" }
- }
A new contact hears nothing until a monitor points at it. Add its id to a monitor's contacts, or put it in a team.
Errors
| Status | When |
|---|---|
400 | No name, no address, an address that isn't a valid email, a severity other than all or high, or a kind that isn't email. |
401 | The API key is missing or invalid. |
403 | The key's owner doesn't have permission to change alert contacts, or the key isn't linked to a workspace. |
405 | The endpoint doesn't accept that method. |
409 | The workspace already has 200 alert contacts. |
429 | A rate limit or your daily quota was hit. Read Retry-After, in seconds. Writes are also limited to 30 a minute per key. |
500, 503 | Something went wrong, or the API is temporarily unavailable. Try again. |
Errors are JSON: { "error": "message" }. See Monitoring API errors.
Related
- Update a contact: change the name or addresses
- Monitor settings: send a monitor's alerts to this contact
- Alerting: severity and opting out