curl --request POST \
--url https://api.politicalcomms.com/v1/projects \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"organization_id": "01HX0000000000000000000000",
"channel": "10dlc",
"brand_id": "01HX0000000000000000000001",
"campaign_id": "01HX0000000000000000000002",
"phone_number_ids": [
"01HX0000000000000000000003",
"01HX0000000000000000000006"
],
"name": "Spring Outreach",
"protocol": "sms",
"contact_list_ids": [
"01HX0000000000000000000004"
],
"suppression_list_ids": [],
"message_text": "Hi {first_name}, early voting starts Monday. Vote info: {tracking_url} Volunteer: {tracking_url_2}",
"media_ids": [],
"link_tracking_enabled": true,
"link_tracking_links": [
{
"destination_url": "https://example.com/vote",
"param_fields": [
"voter_id"
],
"fallback_url": null
},
{
"destination_url": "https://example.com/volunteer?src={voter_id}",
"param_fields": [
"voter_id",
"phone"
],
"fallback_url": null
}
],
"link_tracking_domain_id": "01HX0000000000000000000005",
"opt_out_footer_enabled": true
}
'{
"success": true,
"data": {
"project_id": "01HX000000000000000000P001",
"name": "Spring Outreach",
"type": "broadcast",
"status": "awaiting_test",
"channel": "10dlc",
"created_via_api": true,
"estimated_cost_cents": 4250,
"total_recipients": 500,
"completeness": {
"has_list": true,
"has_message": true,
"has_phone_number": true,
"ready_to_test": true
}
}
}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; triggered has no contact list and sends one message to each person its trigger brings in (see Triggered projects below).
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). Media on a question must belong to the organization and fit the project’s brand or registration, as intro media does; otherwise the request returns 400. Question text supports merge tags and the tracked-link tags {tracking_url}, {tracking_url_2} and {tracking_url_3}. Surveys need at least 2 questions and 1 phone number.
Tracked links. A text project (broadcast, survey or triggered) can carry up to 3 tracked links per message, each with its own destination and up to 10 per-recipient parameters, set with link_tracking_links (entry order is tag order: {tracking_url}, {tracking_url_2}, {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 (in the message, a follow-up step or a survey question) is rejected when link tracking is enabled. The older link_tracking_destination_url, link_tracking_param_field and link_tracking_fallback_url remain as aliases for the first link; sending them together with link_tracking_links returns 400. link_tracking_enabled and link_tracking_domain_id apply to all links. When link_tracking_enabled is true, at least one link with a destination and link_tracking_domain_id become required. A tracked link counts at the length of the short link that is sent, for segments, cost and the length limit.
Each link’s param_fields are the contact fields (phone or a contact field name) carried on its redirect. A destination URL may embed a field anywhere via a placeholder named after it, which must be one of that link’s param_fields, e.g. https://test.com?utm_content=xyzd_{linkid} redirects as ...utm_content=xyzd_ABC123 (no separate &linkid= pair is appended). Fields without a placeholder are appended as &field=value in list order, after short_id, which is always appended; a recipient with no value for a field gets it omitted (or an empty substitution for a placeholder), and phone is sent without the leading +. A link’s destination may also be exactly https://{<field>}, e.g. https://{custom_url}; each recipient’s tracking link then redirects to the URL stored in that contact field instead (short_id is still appended as a query param, but no <field> query param is). In this mode the link’s fallback_url is required, and recipients whose field is empty or not a valid URL go there instead. phone cannot be used as a whole-URL destination, and a {field} token in the host position must be the entire URL (https://{custom_url}/path is rejected). A placeholder that does not match the selected field, or an invalid whole-URL form, is rejected with a 400 (INVALID_LINK_PLACEHOLDER).
Opt-out footer. Broadcast messages automatically carry the STOP=END opt-out footer. Set opt_out_footer_enabled to false to disable it (defaults to true); surveys never carry the footer.
Drafts. contact_list_ids is optional. With at least one list the created project starts in awaiting_test status (send a test, then schedule). Without it the project is created as a draft; attach lists later via PATCH /projects/{id} and the project moves to awaiting_test automatically. Drafts cannot be tested or scheduled. The response’s completeness block shows what is still missing.
Triggered projects. Send type: "triggered" with a required trigger (see the Trigger schema). The body is the broadcast body without contact_list_ids and suppression_list_ids, which are not accepted: recipients arrive one at a time when the trigger fires, and opted-out numbers are never sent to. The project is created ready to test; send a test with POST /projects/{id}/test, then start it with POST /projects/{id}/start. It stays active until paused or ended. A person is sent a triggered project once. The trigger can wait (delay_minutes) or start the next day at a time you set (start: next_day, with scheduled_timezone and sequence_send_time), and a tag trigger sends when a contact is tagged: its start asks who it sends to (see POST /projects/{id}/start). A type other than broadcast, survey or triggered returns 400 INVALID_PROJECT_TYPE.
Tags. A broadcast or survey project can send to contact tags as well as lists: tag_ids (ANY), require_tag_ids (ALL) and suppression_tag_ids (skip, for this send only). Triggered projects refuse them. A survey with neither contact_list_ids nor tag_ids is created as a draft. See GET /tags.
Follow-ups. A broadcast or triggered text project can send up to nine follow-up texts with follow_ups (see the ProjectFollowUps schema): each step waits a number of days (at a set time of day) or hours, and people leave the follow-ups when they reply or click, and always when they opt out. Each is charged when it sends. A survey cannot have follow-ups (400).
curl --request POST \
--url https://api.politicalcomms.com/v1/projects \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"organization_id": "01HX0000000000000000000000",
"channel": "10dlc",
"brand_id": "01HX0000000000000000000001",
"campaign_id": "01HX0000000000000000000002",
"phone_number_ids": [
"01HX0000000000000000000003",
"01HX0000000000000000000006"
],
"name": "Spring Outreach",
"protocol": "sms",
"contact_list_ids": [
"01HX0000000000000000000004"
],
"suppression_list_ids": [],
"message_text": "Hi {first_name}, early voting starts Monday. Vote info: {tracking_url} Volunteer: {tracking_url_2}",
"media_ids": [],
"link_tracking_enabled": true,
"link_tracking_links": [
{
"destination_url": "https://example.com/vote",
"param_fields": [
"voter_id"
],
"fallback_url": null
},
{
"destination_url": "https://example.com/volunteer?src={voter_id}",
"param_fields": [
"voter_id",
"phone"
],
"fallback_url": null
}
],
"link_tracking_domain_id": "01HX0000000000000000000005",
"opt_out_footer_enabled": true
}
'{
"success": true,
"data": {
"project_id": "01HX000000000000000000P001",
"name": "Spring Outreach",
"type": "broadcast",
"status": "awaiting_test",
"channel": "10dlc",
"created_via_api": true,
"estimated_cost_cents": 4250,
"total_recipients": 500,
"completeness": {
"has_list": true,
"has_message": true,
"has_phone_number": true,
"ready_to_test": true
}
}
}Authorizations
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
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
- Broadcast project
Unknown body properties are rejected with a 400 (strict validation).
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.
1600Up 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.
3Show child attributes
Show child attributes
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.
64Alias 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.
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.
America/New_York, America/Chicago, America/Denver, America/Los_Angeles, America/Anchorage, Pacific/Honolulu 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.
50