Skip to main content
The Political Comms API is a RESTful interface for integrating messaging data, project statistics, contact and media management, and billing into your application. It’s the same API that powers our own dashboard, so anything you can do in the UI you can also do programmatically.

Authentication

Authenticate with an API key passed in the X-API-Key header.

Webhooks

Stream real-time events into your CRM, warehouse, or alerting stack.

Rate limits

100 requests per hour per API key. Headers tell you where you stand.

Errors

Conventional HTTP status codes with structured error responses.

​
Base URL

https://api.politicalcomms.com/v1
Custom domains are supported for white-labeled deployments. If your organization has a custom API domain configured, use that as the base URL - the API surface is identical.

​
Quickstart

1

Get an API key

From the dashboard, go to Admin → API Keys → New Key. Copy the key (it’s only shown once) and store it in a secret manager - never in source control.
2

Make your first call

List your accessible organizations:
curl https://api.politicalcomms.com/v1/organizations \
  -H "X-API-Key: pc_live_1234567890abcdef"
3

Subscribe to webhooks

Configure an HTTPS endpoint that receives real-time events for messages, replies, and link clicks. Always validate the HMAC signature before trusting any payload.

​
What you can do

List organizations, brands, campaigns, phone numbers, and tracking domains across your full org tree. Filter by org / brand / campaign at every level.
Import contact lists from S3 presigned URLs, trigger LRN analysis (mobile / landline / VoIP / invalid), upload and reuse media files. Both contacts and media use async import + polling for “ready” status.
Build broadcast projects programmatically: select contact list and phone number, compose the message with merge fields, add media, enable link tracking, send tests, and schedule for a specific time + timezone.
Query message stats by date range with org/brand/campaign filters. Pull usage and billing data per organization or grouped by initiating org.
Real-time notifications for message.sent, message.delivered, message.failed, message.replied, and link.clicked - with HMAC-signed payloads and automatic retry.

​
SDKs and tooling

We don’t ship an official SDK - the API is small and stable enough that direct HTTP calls from your language of choice are the cleanest path. The dashboard’s Export to Postman button generates a fully-configured Postman collection (Collection v2.1) you can import into Postman or Bruno for interactive testing. Format your code samples in curl, Node, Python, Go, or any other language - the API is plain JSON over HTTPS.

​
Idempotency and consistency

  • All GET endpoints are safe to retry - they have no side effects.
  • All POST and PATCH endpoints that mutate state are designed to be safe to retry; duplicate calls during a network blip will not create duplicate resources. If you need stronger guarantees, send a unique Idempotency-Key header on every write - repeated calls with the same key replay the original response.
  • Aurora Serverless v2 + RDS Proxy backs every read with p99 < 100ms at the database layer.