# Schedule multi-stage appointment reminder
URL: /docs/api-reference/smart-reminders/scheduleReminder

## POST `/api/v1/public/reminders/schedule`

**Summary:** Schedule multi-stage appointment reminder
**Operation ID:** `scheduleReminder`

Queues automated timed reminders before an event (e.g. 24h, 2h before). Charges SMS segment cost plus configured service surcharge per sent stage.

**Authentication:** `X-Api-Key: sk_live_...` or `Authorization: Bearer sk_live_...`

### Request Body (`application/json`)

```json
{
  "type": "object",
  "required": [
    "recipient",
    "eventTitle",
    "eventTime",
    "schedule",
    "messageTemplate"
  ],
  "properties": {
    "recipient": {
      "type": "string",
      "example": "+233241234567"
    },
    "eventTitle": {
      "type": "string",
      "example": "Dental Checkup"
    },
    "eventTime": {
      "type": "string",
      "format": "date-time",
      "example": "2026-11-15T14:30:00Z"
    },
    "schedule": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": [
        "24h",
        "2h"
      ]
    },
    "messageTemplate": {
      "type": "string",
      "example": "Reminder: {eventTitle} scheduled for {eventTime}."
    },
    "senderId": {
      "type": "string",
      "example": "CLINIC"
    }
  }
}
```

### Responses

- **`201`**: Reminder successfully scheduled

```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "example": "success"
    },
    "message": {
      "type": "string",
      "example": "Reminder scheduled successfully"
    },
    "data": {
      "$ref": "#/components/schemas/ReminderResponseDto"
    }
  }
}
```
- **`401`**: Authentication failed or API key missing
- **`422`**: Validation error or invalid input parameters