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. More info: {link}",
  "media_ids": [],
  "link_tracking_enabled": true,
  "link_tracking_destination_url": "https://example.com/vote",
  "link_tracking_domain_id": "01HX0000000000000000000005",
  "link_tracking_param_field": "voter_id"
}
'

{
  "success": true,
  "data": {
    "id": "proj_new123",
    "name": "Spring Outreach",
    "status": "draft",
    "channel": "10dlc",
    "organization_id": "01HX0000000000000000000000",
    "brand_id": "01HX0000000000000000000001",
    "campaign_id": "01HX0000000000000000000002",
    "toll_free_verification_id": null,
    "phone_number_ids": [
      "01HX0000000000000000000003",
      "01HX0000000000000000000006"
    ],
    "protocol": "sms",
    "message_text": "Hi {first_name}, early voting starts Monday. More info: {link}",
    "created_at": "2026-03-20T11:00:00Z"
  }
}

Projects

Create Project

Create a new project in draft status. Broadcast type only.

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. A 10dlc project routes through a brand + campaign, so brand_id and campaign_id are required (and toll_free_verification_id must be omitted). A toll-free project has no brand/campaign; instead toll_free_verification_id is required and the chosen phone_number_ids must be toll-free numbers belonging to that verification (brand_id/campaign_id must be omitted).

When link_tracking_enabled is true, link_tracking_destination_url and link_tracking_domain_id become required.

POST

projects

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. More info: {link}",
  "media_ids": [],
  "link_tracking_enabled": true,
  "link_tracking_destination_url": "https://example.com/vote",
  "link_tracking_domain_id": "01HX0000000000000000000005",
  "link_tracking_param_field": "voter_id"
}
'

{
  "success": true,
  "data": {
    "id": "proj_new123",
    "name": "Spring Outreach",
    "status": "draft",
    "channel": "10dlc",
    "organization_id": "01HX0000000000000000000000",
    "brand_id": "01HX0000000000000000000001",
    "campaign_id": "01HX0000000000000000000002",
    "toll_free_verification_id": null,
    "phone_number_ids": [
      "01HX0000000000000000000003",
      "01HX0000000000000000000006"
    ],
    "protocol": "sms",
    "message_text": "Hi {first_name}, early voting starts Monday. More info: {link}",
    "created_at": "2026-03-20T11:00:00Z"
  }
}

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.

Body

application/json

organization_id

string

required

phone_number_ids

string[]

required

Sending phone number IDs (1-49). New conversations are spread randomly across them; each recipient is then pinned to one number (sticky sender).

Required array length: 1 - 49 elements

name

string

required

protocol

enum<string>

required

Available options:

sms,

mms

contact_list_ids

string[]

required

message_text

string

required

channel

enum<string>

default:10dlc

Messaging channel. Defaults to 10dlc.

Available options:

10dlc,

toll-free

brand_id

string

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

campaign_id

string

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

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_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.

suppression_list_ids

string[]

media_ids

string[]

link_tracking_enabled

boolean

link_tracking_destination_url

string<uri>

link_tracking_domain_id

string

link_tracking_param_field

string

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.

Maximum string length: 64

Response

Project created (in draft status)

List Projects Get Project Stats (all)