---
title: "Schedule SMS"
method: POST
path: "/sms/schedule"
tags: ["sms"]
---

# Schedule SMS

`POST /sms/schedule`

## Request

- Base URL: `https://app.tascan.io/api/v1`
- URL: `https://app.tascan.io/api/v1/sms/schedule`
- Auth: HTTP bearer

Schedule a transactional TaScan SMS for a future time (up to 90 days out): the text is sent by TaScan's own scheduler (every 5 minutes) through the same guarded lane as tascan_send_sms — recipient must be a worker of your org or a phone the org already knows, STOP opt-outs honoured, burst limits and the SMS quota apply, the "TaScan:" prefix is added, and a list_id appends a tap-to-open checklist link. Use this for reminders (e.g. "log your out time" each show night) — nothing outside TaScan needs to stay awake. Returns the scheduled row id; cancel with tascan_cancel_scheduled_sms while it is still pending. The same idempotency_key within an org returns the existing row instead of a duplicate.

## Request body

- object
  - `send_at` string, required: When to send — ISO 8601 with a timezone offset, e.g. "2026-09-25T18:30:00-07:00" (Las Vegas is -07:00 in September). Delivery happens on the next 5-minute tick at or after this time.
  - `message` string, required: Message text (1-400 chars, links stripped). Transactional and work-related only.
  - `worker_id` string: Worker ID — texts their phone on file (preferred over raw phone)
  - `phone` string: Raw phone (E.164) — must already belong to a worker or roster entry of your org
  - `list_id` string: Optional task list ID — appends the tap-to-open checklist link
  - `include_link` boolean: Append the list link (default true when list_id is given)
  - `idempotency_key` string: Optional caller key (≤ 200 chars) — replays return the existing scheduled row

## Response `200`

Success. JSON body: { data: ... } or an error object { error, message }.

## Other responses

- `4XX`: Client error (validation, auth, scope, rate limit).

---

[API](https://skmtc.dev/tascan/apis/tascan-api.md) · [All operations](https://skmtc.dev/tascan/apis/tascan-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tascan/apis/tascan-api/revisions/56fcd2861498?raw)