Create Project
Create a new project. type selects the payload shape: broadcast (the default) sends one message to the audience; survey runs a multi-question flow with branching.
Phone numbers. Assign one or more sending numbers via phone_number_ids (up to 49). The project spreads new conversations randomly across the assigned numbers, and once a recipient has been messaged from a given number every later message to that recipient comes from the same number (sticky sender). A single legacy phone_number_id is still accepted and is treated as a one-element phone_number_ids.
Channel. channel defaults to 10dlc. For broadcast projects a 10dlc channel requires brand_id + campaign_id (and toll_free_verification_id must be omitted), while toll-free requires toll_free_verification_id with matching toll-free phone_number_ids (brand_id/campaign_id omitted). Survey projects always require campaign_id, on both channels.
Surveys. questions defines the whole flow: an intro at sequence 1, then multiple_choice/open_ended questions, optionally ending with an outro. Multiple-choice options can branch with next_sequence, and no_match_sequence routes unmatched replies; both are forward-only. Each question can be SMS or MMS (message_type + media_ids). Question text supports merge tags and {tracking_url}. Surveys are created complete: at least 2 questions, 1 contact list, and 1 phone number.
When link_tracking_enabled is true, link_tracking_destination_url and link_tracking_domain_id become required.
The created project starts in awaiting_test status (send a test, then schedule).
Authorizations
Authenticate every request by passing your API key in the X-API-Key header. Keys are scoped to your organization hierarchy.
Headers
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.
16 - 200Body
- Broadcast project
- Survey project
Sending phone number IDs (1-49). New conversations are spread randomly across them; each recipient is then pinned to one number (sticky sender).
1 - 49 elementssms, mms Project type. Optional for broadcast (the default).
broadcast Messaging channel. Defaults to 10dlc.
10dlc, toll-free Required when channel=10dlc; omit when channel=toll-free.
Required when channel=10dlc; omit when channel=toll-free.
Required when channel=toll-free; omit when channel=10dlc. Must match the verification behind the chosen phone_number_ids.
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 field appended as a redirect query param on tracking links. Use 'phone', a contact custom-field name, or omit for no param (default). The field's name becomes the query-param key; the contact's value is the value.
64