Skip to main content
POST

Authorizations

X-API-Key
string
header
required

Authenticate every request by passing your API key in the X-API-Key header. Keys are scoped to your organization hierarchy. A key carries up to three permissions: public:read for GET requests, public:write for POST, PATCH, and PUT requests, and public:delete for DELETE requests. public:delete is only available together with public:write.

Headers

Idempotency-Key
string

Optional idempotency key: a unique string of 16-200 printable ASCII characters (a UUID is recommended). Retrying the write with the same key within 24 hours returns the stored response of the first call with an X-Idempotent-Replayed: true response header instead of executing it again. Reusing a key with a different request body returns 422 (IDEMPOTENCY_MISMATCH); a duplicate sent while the first call is still running returns 409 with a Retry-After header. Keys are scoped per endpoint and organization.

Required string length: 16 - 200

Body

application/json

Unknown body properties are rejected with a 400 (strict validation).

organization_id
string
required
name
string
required
protocol
enum<string>
required
Available options:
sms,
mms
message_text
string
required

Message text. Supports merge tags ({first_name|there}, contact custom fields) and {tracking_url}, {tracking_url_2} and {tracking_url_3} (the project's first, second and third tracked link) when link tracking is enabled on the project. Limited to 10 SMS parts (1,530 GSM-7 or 670 Unicode characters, counted with merge tags removed), or 1,500 characters when protocol is mms or media_ids is set; longer text is rejected with 400 and a message naming the limit.

Maximum string length: 1600
type
enum<string>

Project type. Optional for broadcast (the default).

Available options:
broadcast
channel
enum<string>
default:10dlc

Messaging channel. Defaults to 10dlc.

Available options:
10dlc,
toll-free,
short-code
brand_id
string

Required when channel=10dlc; omit when channel=toll-free or short-code.

campaign_id
string

Required when channel=10dlc; omit when channel=toll-free or short-code.

toll_free_verification_id
string

Required when channel=toll-free; omit when channel=10dlc. Must match the verification behind the chosen phone_number_ids.

phone_number_ids
string[]

Sending phone number IDs (1-49). At least one of phone_number_ids or phone_number_id is required. New conversations are spread randomly across the numbers; each recipient is then pinned to one number.

Required array length: 1 - 49 elements
phone_number_id
string
deprecated

Deprecated. Use phone_number_ids. A single id is accepted and treated as a one-element phone_number_ids. Provide one of phone_number_ids or phone_number_id.

contact_list_ids
string[]

Optional. Omit to create the project as a draft with no audience; attach lists or tags later via PATCH /projects/{id}. When present, must contain at least one list id. A project needs at least one list or one tag_ids entry to be complete.

Minimum array length: 1
suppression_list_ids
string[]
media_ids
string[]

Up to 3 tracked links per message, in tag order: the first answers {tracking_url}, the second {tracking_url_2}, the third {tracking_url_3}. Each tag becomes that recipient's own short link to that link's destination, and repeating a tag repeats the same short link. A tag with no link behind it is rejected when link_tracking_enabled is true. Send 1 to 3 entries on create; on update the list you send replaces the existing one. link_tracking_enabled and link_tracking_domain_id apply to every link (one short-link domain per project). Cannot be sent together with link_tracking_destination_url, link_tracking_param_field or link_tracking_fallback_url, which stay available as aliases for the first link.

Maximum array length: 3

Alias for the first entry of link_tracking_links (its destination_url). Where the tracking link redirects. A {field} placeholder in it must be one of the link's param_fields; otherwise the request is rejected with a 400 (INVALID_LINK_PLACEHOLDER). May also be exactly https://{<field>} to send each recipient to the URL in that contact field; then link_tracking_fallback_url is required. {phone} is not allowed as a whole URL. Cannot be sent together with link_tracking_links.

Alias for the first entry of link_tracking_links (its first param_fields entry): phone, a contact field name, or null for none. Appended to the redirect as a query pair, or embedded in place of a matching {field} placeholder in the destination URL. Cannot be sent together with link_tracking_links.

Maximum string length: 64

Alias for the first entry of link_tracking_links (its fallback_url). Used when a whole-URL destination's contact field is empty or not a valid URL. Required when the destination is a whole-URL placeholder (e.g. https://{custom_url}); rejected with a 400 (INVALID_LINK_PLACEHOLDER) otherwise. Cannot be sent together with link_tracking_links.

Whether the 'STOP=END' opt-out footer is appended to every outbound message. Defaults to true. Broadcast projects only; surveys never carry the footer.

follow_ups
object

Texts sent after the first message. A step that waits days needs scheduled_timezone and sequence_send_time in this same request.

scheduled_timezone
enum<string>

Only with follow-ups that wait days: the time zone their time of day is in. Sent without them it returns 400; you choose the project's own send time when you schedule it.

Available options:
America/New_York,
America/Chicago,
America/Denver,
America/Los_Angeles,
America/Anchorage,
Pacific/Honolulu
sequence_send_time
string

Only with follow-ups that wait days: the local time of day, HH:MM, those follow-ups send at.

Pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
tag_ids
string<uuid>[]

Send to every contact carrying ANY of these tags, in union with contact_list_ids. Each must be a tag of the project's organization. A tagged contact is only sent to through a list row the project's sender can use (see GET /tags). A tag cannot also be in suppression_tag_ids.

Maximum array length: 50
require_tag_ids
string<uuid>[]

Narrow the audience to contacts carrying ALL of these tags ("only contacts tagged"). A tag cannot also be in suppression_tag_ids.

Maximum array length: 50
suppression_tag_ids
string<uuid>[]

Skip contacts carrying ANY of these tags for this send only. This is separate from opt-outs, which always apply.

Maximum array length: 50

Response

Project created. Status reflects completeness (awaiting_test when ready to test).

success
boolean
required
data
object
required