Contacts API

Manage notification contacts including email, SMS, webhooks, Slack, Discord, PagerDuty, and more. Configure who gets alerted when monitors detect issues.

Contacts define how and where to send notifications when your monitors detect issues. Each contact has a specific channel type with its own configuration requirements.

Supported Channels

SMTP delivery

SMS

Text messages

Webhook

HTTP callbacks

Chat

Slack, Discord

Plus integrations with PagerDuty, incident.io, Opsgenie, and Zendesk for advanced incident management workflows.

GET/api/contacts

Retrieve a paginated list of all contacts in your account. Supports filtering and searching.

Query Parameters

Name	Type	Required	Description
page	`integer`	No	Page number for paginationDefault: `1`Example: `2`
per_page	`integer`	No	Items per page (max 100)Default: `50`Example: `25`
search	`string`	No	Search contacts by nameExample: `production`
channel	`string`	No	Filter by channel typeExample: `email`
sort	`string`	No	Sort fieldDefault: `created_at`Example: `name`
order	`string`	No	Sort orderDefault: `desc`Example: `asc`

Example Request

curl -X GET "https://api.uptime-monitor.io/api/contacts?page=1&per_page=25" \
  -H "Authorization: Bearer um_your_api_key_here"

Example Response

{
  "status": "ok",
  "contacts": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "DevOps Team Email",
      "channel": "email",
      "created_at": 1704067200,
      "details": {
        "email": "devops@example.com"
      },
      "active": true,
      "down_alerts_only": false,
      "error": null
    },
    {
      "id": "507f1f77bcf86cd799439012",
      "name": "On-call Team",
      "channel": "pagerduty",
      "created_at": 1704153600,
      "details": {
        "integration_key": "[REDACTED]",
        "severity_mapping": {
          "critical": "critical",
          "high": "error",
          "medium": "warning",
          "low": "info"
        },
        "auto_resolve_incidents": true
      },
      "active": true,
      "down_alerts_only": false,
      "error": null
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 2,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

GET/api/contacts/:id

Retrieve details for a specific contact by ID.

Path Parameters

Name	Type	Required	Description
id	`string`	Yes	Contact ID (24-character MongoDB ObjectID)Example: `507f1f77bcf86cd799439011`

Example Request

curl -X GET https://api.uptime-monitor.io/api/contacts/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer um_your_api_key_here"

Example Response

{
  "status": "ok",
  "contact": {
    "id": "507f1f77bcf86cd799439011",
    "name": "DevOps Team Email",
    "channel": "email",
    "created_at": 1704067200,
    "details": {
      "email": "devops@example.com"
    },
    "active": true,
    "down_alerts_only": false,
    "error": null
  }
}

Error Responses

404CONTACT_NOT_FOUND

Contact with the specified ID does not exist

POST/api/contacts

Create a new notification contact. The required fields in 'details' vary by channel type.

Body Parameters

Name	Type	Required	Description
name	`string`	Yes	Descriptive name for the contactExample: `DevOps Team Email`
channel	`string`	Yes	Type of notification channelExample: `email`
details	`object`	Yes	Channel-specific configuration (varies by channel type)
active	`boolean`	No	Whether the contact is activeDefault: `true`
down_alerts_only	`boolean`	No	Only send alerts when monitors go down (not recovery)Default: `false`

Example Request

curl -X POST https://api.uptime-monitor.io/api/contacts \
  -H "Authorization: Bearer um_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DevOps Team Email",
    "channel": "email",
    "details": {
      "email": "devops@example.com"
    },
    "active": true,
    "down_alerts_only": false
  }'

Example Response

{
  "status": "ok",
  "contact": {
    "id": "507f1f77bcf86cd799439011",
    "name": "DevOps Team Email",
    "channel": "email",
    "created_at": 1704067200,
    "details": {
      "email": "devops@example.com"
    },
    "active": true,
    "down_alerts_only": false,
    "error": null
  }
}

Error Responses

422VALIDATION_ERROR

Required fields are missing or invalid

PUT/api/contacts/:id

Update an existing contact. All fields are optional - only provided fields will be updated.

Path Parameters

Name	Type	Required	Description
id	`string`	Yes	Contact ID (24-character MongoDB ObjectID)Example: `507f1f77bcf86cd799439011`

Body Parameters

Name	Type	Required	Description
name	`string`	No	New descriptive name for the contactExample: `Updated Team Email`
details	`object`	No	Updated channel-specific configuration
active	`boolean`	No	Whether the contact is active
down_alerts_only	`boolean`	No	Only send alerts when monitors go down

Example Request

curl -X PUT https://api.uptime-monitor.io/api/contacts/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer um_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated DevOps Email",
    "details": {
      "email": "new-devops@example.com"
    },
    "active": false
  }'

Example Response

{
  "status": "ok",
  "contact": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Updated DevOps Email",
    "channel": "email",
    "created_at": 1704067200,
    "details": {
      "email": "new-devops@example.com"
    },
    "active": false,
    "down_alerts_only": false,
    "error": null
  }
}

Error Responses

404CONTACT_NOT_FOUND

Contact with the specified ID does not exist

403READONLY_CHANNEL

This contact channel cannot be modified (e.g., APNS)

DELETE/api/contacts/:id

Permanently delete a contact. This action cannot be undone.

Path Parameters

Name	Type	Required	Description
id	`string`	Yes	Contact ID (24-character MongoDB ObjectID)Example: `507f1f77bcf86cd799439011`

Example Request

curl -X DELETE https://api.uptime-monitor.io/api/contacts/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer um_your_api_key_here"

Example Response

HTTP 204 No Content

Error Responses

404CONTACT_NOT_FOUND

Contact with the specified ID does not exist

403READONLY_CHANNEL

This contact channel cannot be deleted (e.g., APNS)

Channel Types & Configuration

Each channel type requires specific fields in the details object. Here are the supported channels and their configuration:

Email

Send notifications via email. Most basic and reliable notification method.

Required Details

{
  "channel": "email",
  "details": {
    "email": "alerts@example.com"
  }
}

SMS

Send text message alerts to mobile phones. Requires SMS credits.

Required Details

{
  "channel": "sms",
  "details": {
    "phone": "+1234567890"
  }
}

Webhook

HTTP POST requests to your custom endpoint. Perfect for custom integrations.

Required Details

{
  "channel": "webhook",
  "details": {
    "url": "https://example.com/webhook"
  }
}

Slack

Send alerts to Slack channels using incoming webhooks.

Required Details

{
  "channel": "slack",
  "details": {
    "webhook_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
  }
}

Discord

Send alerts to Discord channels using webhooks.

Required Details

{
  "channel": "discord",
  "details": {
    "webhook_url": "https://discord.com/api/webhooks/1234567890/abcdefghijk"
  }
}

PagerDuty

Create incidents in PagerDuty with severity mapping and auto-resolution.

Required Details

{
  "channel": "pagerduty",
  "details": {
    "integration_key": "R01234567890123456789012345678901",
    "severity_mapping": {
      "critical": "critical",
      "high": "error",
      "medium": "warning",
      "low": "info"
    },
    "auto_resolve_incidents": true
  }
}

incident.io

Create and manage incidents in incident.io with webhook integration.

Required Details

{
  "channel": "incidentio",
  "details": {
    "webhook_url": "https://api.incident.io/webhooks/...",
    "bearer_token": "inc_...",
    "auto_resolve_incidents": true
  }
}

Opsgenie

Create alerts in Opsgenie with custom priority, responders, and tags.

Required Details

{
  "channel": "opsgenie",
  "details": {
    "api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "priority": "P3",
    "responders": [
      {
        "type": "team",
        "id": "team-id"
      }
    ],
    "tags": ["uptime", "monitoring"],
    "auto_close_alerts": true,
    "eu_instance": false
  }
}

Zendesk

Create support tickets in Zendesk with custom fields and tags.

Required Details

{
  "channel": "zendesk",
  "details": {
    "subdomain": "company",
    "email": "support@example.com",
    "api_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "priority": "normal",
    "custom_fields": [
      {
        "id": 360000000001,
        "value": "monitoring"
      }
    ],
    "tags": ["uptime", "alert"],
    "auto_solve_tickets": true
  }
}

Security & Privacy

• Sensitive fields (API keys, tokens) are redacted as [REDACTED] in API responses
• APNS (Apple Push Notification) contacts are read-only and cannot be modified via API
• All contacts are account-scoped - you can only access your own contacts
• Store integration keys and tokens securely in your application

← Authentication Monitors API →