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

# Send SMS

`POST /sms`

## Request

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

Send a transactional TaScan SMS text to a worker (by worker_id, using their phone on file) or to a raw phone number. Optionally attach a task list — the recipient gets a tap-to-open checklist link. Sends from TaScan's carrier-registered A2P number (or the org's own Twilio if BYOK). Counts against the org's monthly SMS quota unless BYOK. Messages are auto-prefixed with "TaScan:" per carrier registration; transactional/work-related content only, no marketing. Attach images with media_url or media_base64 (MMS); message is optional when an image is attached.

## Request body

- object
  - `worker_id` string: Worker ID — sends to their phone on file (preferred over raw phone)
  - `phone` string: Raw phone number (e.g. "+17025551234") — used when no worker_id given
  - `message` string: Message text. Transactional and work-related only.
  - `list_id` string: Optional task list ID — appends a tap-to-open worker checklist link
  - `include_link` boolean: When a list_id is given, append the tap-to-open link to the SMS body (default true). Set false to send the message text alone — the link is still returned for you to share another way.
  - `idempotency_key` string: B1: optional replay key (up to 1024 chars, no braces) sent verbatim as the Idempotency-Key header instead of a fresh one per call — a retried call with the SAME key replays the original response instead of sending a second text.
  - `media_url` union: Image(s) to attach (MMS): public https URLs of JPEG/PNG/GIF images, up to 3.
    - string
    - string[]
  - `media_base64` string: Image to attach (MMS) as base64 bytes (data: URI accepted). JPEG, PNG or GIF, max 3.5 MB. Stored privately; sent via a short-lived link.
  - `media_type` 'image/jpeg' | 'image/png' | 'image/gif': MIME type of media_base64.

## 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)