---
title: "Create SMS broadcast from contacts"
method: POST
path: "/broadcasts"
tags: ["SMS Broadcast"]
---

# Create SMS broadcast from contacts

`POST /broadcasts`

Create a new SMS broadcast by selecting individual contacts or entire contact lists. Either contact_ids or contact_list_ids must be provided, but not both.

## Request body

- BroadcastCreateRequest
  - `broadcast_name` string, required — Human-readable broadcast campaign name. String.
  - `tracking_number` string, required — Phone number the caller dialed (the tracking/DNI number). Convirza routes calls from this number through the configured call flow. String of digits.
  - `agent_ring_to` string, required — Phone number of the agent receiving SMS replies. String. Must resolve to 10 digits; formatting like parentheses, dashes, or '+1' prefix is accepted.
  - `message` string, required — SMS message body. String. Max length set by carrier (typically 160 chars for single-segment, up to 1600 for concatenated).
  - `contact_ids` integer[] — Array of contact IDs to send to. Either contact_ids or contact_list_ids must be provided (not both). Example [101, 202]. Type: array of integer.
  - `contact_list_ids` integer[] — Array of contact list IDs to send to. Either contact_ids or contact_list_ids must be provided (not both). Example [1, 2, 3]. Type: array of integer.
  - `group_id` integer, required — Organization unit (group) ID the call/record belongs to. Integer. Used to scope data; see /group/list for available group IDs.
  - `is_scheduled` boolean — Boolean. If true, the broadcast is queued for future delivery; if false, it sends immediately. Default false.
  - `schedule_datetime` string, date-time — When to send the broadcast, required when is_scheduled=true. Format 'YYYY-MM-DD HH:mm:ss'.

## Response `200`

Broadcast created successfully with bulk_sms_conversations_id

- PostResponse
  - `result` string, required — Outcome of the request. String, typically 'success' or 'error'.
  - `err` string, required — Error message when result='error'. String. Empty/null on success.
  - `data` string — Response payload. Shape varies by endpoint.

## Other responses

- `default` — Unexpected error

---

[API](https://skmtc.net/convirza/apis/convirza-apis.md) · [All operations](https://skmtc.net/convirza/apis/convirza-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/convirza/convirza-apis/versions/ccf9bbe34f5a/schema)