{ "openapi": "3.1.0", "info": { "title": "Political Comms API", "summary": "Direct-to-carrier political texting API for campaigns, PACs, advocacy organizations, fundraisers, and elected officials.", "description": "Public REST API for the Political Comms platform. Surfaces include Projects (compose, test, schedule, send), Contact Lists (S3 import and analysis), Media Files, Organizations and hierarchy, Brands, Campaigns, Tracking Domains, Phone Numbers, Analytics, and Billing.\n\nAuthentication is an API key passed in the `X-API-Key` header. Keys are generated from the dashboard at Admin \u2192 API Keys and are prefixed `pc_live_`. All POST and PATCH endpoints that mutate state are designed to be safe to retry, with optional `Idempotency-Key` headers for stronger guarantees. Rate limit is 100 requests per minute per key (60-second sliding window; write-only keys 60/min, delete-only keys 30/min — the `X-RateLimit-Limit` header reports your key's exact limit).\n\nWebhooks emit `message.sent`, `message.delivered`, `message.failed`, `message.replied`, and `link.clicked` events. Payloads are HMAC-signed; validate the signature before trusting any payload.\n\nA Model Context Protocol (MCP) server is available at https://docs.politicalcomms.com/mcp for AI agents that need to search the documentation programmatically. The developer hub at https://politicalcomms.com/developers/ has quickstart examples in cURL, raw HTTP, and Python.", "version": "1.0.0", "termsOfService": "https://politicalcomms.com/terms/", "contact": { "name": "Political Comms Support", "email": "support@politicalcomms.com", "url": "https://docs.politicalcomms.com" }, "license": { "name": "Proprietary", "url": "https://politicalcomms.com/terms/" }, "x-logo": { "url": "https://politicalcomms.com/images/brand/pcomms-logo-left-of-text.png", "altText": "Political Comms", "backgroundColor": "#ffffff", "href": "https://politicalcomms.com/" }, "x-mcp": { "url": "https://docs.politicalcomms.com/mcp", "discovery_url": "https://docs.politicalcomms.com/.well-known/mcp", "transport": "http", "auth": "none", "tools": [ "search_political_comms", "query_docs_filesystem_political_comms", "submit_feedback" ] } }, "servers": [ { "url": "https://api.politicalcomms.com/v1", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Organizations", "description": "List descendant organizations and hierarchy." }, { "name": "Brands", "description": "List brands across your organization hierarchy." }, { "name": "Campaigns", "description": "List campaigns across your organization hierarchy." }, { "name": "Tracking Domains", "description": "List active link-tracking domains. Use the returned ids as `link_tracking_domain_id` on project create/update." }, { "name": "Phone Numbers", "description": "List phone numbers across 10DLC campaigns and toll-free verifications." }, { "name": "Toll-Free Verifications", "description": "List toll-free verifications (carrier registrations) across your organization hierarchy." }, { "name": "Contact Lists", "description": "List, import, and analyze contact lists." }, { "name": "Media Files", "description": "List, import, and fetch media files." }, { "name": "Projects", "description": "Create, edit, test, schedule, and inspect projects." }, { "name": "Analytics", "description": "Message statistics and delivery performance." }, { "name": "Billing", "description": "Usage and billing data across your organization." } ], "paths": { "/organizations": { "get": { "tags": [ "Organizations" ], "summary": "List Organizations", "description": "List all descendant organizations accessible to your API key.", "operationId": "listOrganizations", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": "string" }, "parent_org_name": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string" } }, "additionalProperties": true } } } }, "example": { "success": true, "data": [ { "id": "org_abc123", "display_name": "Regional Office East", "parent_org_name": "Smith Campaign 2024", "status": "active", "created_at": "2024-02-01T10:00:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/hierarchy": { "get": { "tags": [ "Organizations" ], "summary": "Get Hierarchy", "description": "Get the full organization hierarchy with brands and campaigns.", "operationId": "getHierarchy", "parameters": [ { "$ref": "#/components/parameters/OrganizationIdCamel" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": "string" }, "brands": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "children": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true } } }, "example": { "success": true, "data": { "id": "org_root", "display_name": "Smith Campaign 2024", "brands": [ { "id": "brand_abc123", "brand_name": "Smith PAC", "campaigns": [ { "id": "camp_xyz789", "name": "Fall 2025 GOTV" } ] } ], "children": [ { "id": "org_child_1", "display_name": "Regional Office East", "brands": [], "children": [] } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/brands": { "get": { "tags": [ "Brands" ], "summary": "List Brands", "description": "List all brands. Optionally filter by organization.", "operationId": "listBrands", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "brand_name": { "type": "string" }, "org_id": { "type": "string" }, "org_name": { "type": "string" }, "tcr_brand_id": { "type": "string" }, "status": { "type": "string" }, "identity_status": { "type": "string" }, "created_at": { "type": "string" } }, "additionalProperties": true } } } }, "example": { "success": true, "data": [ { "id": "brand_abc123", "brand_name": "Smith PAC", "org_id": "org_123", "org_name": "Smith Campaign 2024", "tcr_brand_id": "BTCRMFG", "status": "OK", "identity_status": "VETTED_VERIFIED", "created_at": "2024-01-15T11:00:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/campaigns": { "get": { "tags": [ "Campaigns" ], "summary": "List Campaigns", "description": "List all campaigns. Filter by organization or brand.", "operationId": "listCampaigns", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/BrandId" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "brand_id": { "type": "string" }, "brand_name": { "type": "string" }, "org_id": { "type": "string" }, "org_name": { "type": "string" }, "campaign_status": { "type": "string" }, "created_at": { "type": "string" } }, "additionalProperties": true } } } }, "example": { "success": true, "data": [ { "id": "camp_xyz789", "name": "Fall 2025 GOTV", "brand_id": "brand_abc123", "brand_name": "Smith PAC", "org_id": "org_123", "org_name": "Smith Campaign 2024", "campaign_status": "MNO_PROVISIONED", "created_at": "2024-01-20T09:00:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/tracking-domains": { "get": { "tags": [ "Tracking Domains" ], "summary": "List Tracking Domains", "description": "List active tracking domains across accessible organizations. Optional filter by organization.", "operationId": "listTrackingDomains", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "org_id": { "type": "string" }, "org_name": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string" } }, "additionalProperties": true } } } }, "example": { "success": true, "data": [ { "id": "01HX0000000000000000000005", "domain": "link.smithpac.com", "org_id": "org_123", "org_name": "Smith Campaign 2024", "status": "active", "created_at": "2024-02-10T14:00:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/phone-numbers": { "get": { "tags": [ "Phone Numbers" ], "summary": "List Phone Numbers", "description": "List all phone numbers across both channels: 10DLC numbers (owned via a campaign) and toll-free numbers (owned via a toll-free verification). Each row carries a `channel` and an `owner_type` indicating what it belongs to. The `campaign_id`/`campaign_name`/`brand_id`/`brand_name` fields are populated for 10DLC numbers and null for toll-free; `toll_free_verification_id`/`toll_free_registration_name`/`tf_verification_status` are populated for toll-free numbers and null for 10DLC. Filter by organization, brand, or campaign (brand/campaign filters apply to 10DLC numbers only), and optionally by `channel` or `owner_type`.", "operationId": "listPhoneNumbers", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/BrandId" }, { "$ref": "#/components/parameters/CampaignId" }, { "name": "channel", "in": "query", "required": false, "description": "Filter by messaging channel", "schema": { "type": "string", "enum": [ "10dlc", "toll-free", "short-code", "rcs" ] } }, { "name": "owner_type", "in": "query", "required": false, "description": "Filter by what the number belongs to: a 10DLC campaign, a toll-free verification, or neither (purchased but not yet attached)", "schema": { "type": "string", "enum": [ "campaign", "toll_free_registration", "unassigned" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "channel": { "type": "string" }, "owner_type": { "type": "string" }, "campaign_id": { "type": [ "string", "null" ] }, "campaign_name": { "type": [ "string", "null" ] }, "brand_id": { "type": [ "string", "null" ] }, "brand_name": { "type": [ "string", "null" ] }, "toll_free_verification_id": { "type": [ "string", "null" ] }, "tf_verification_status": { "type": [ "string", "null" ] }, "toll_free_registration_name": { "type": [ "string", "null" ] }, "org_id": { "type": "string" }, "org_name": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string" } }, "additionalProperties": true } } } }, "example": { "success": true, "data": [ { "id": "pn_abc123", "number": "+12025551234", "channel": "10dlc", "owner_type": "campaign", "campaign_id": "camp_xyz789", "campaign_name": "Fall 2025 GOTV", "brand_id": "brand_abc123", "brand_name": "Smith PAC", "toll_free_verification_id": null, "tf_verification_status": null, "toll_free_registration_name": null, "org_id": "org_123", "org_name": "Smith Campaign 2024", "status": "active", "created_at": "2024-03-01T08:00:00Z" }, { "id": "pn_def456", "number": "+18005551234", "channel": "toll-free", "owner_type": "toll_free_registration", "campaign_id": null, "campaign_name": null, "brand_id": null, "brand_name": null, "toll_free_verification_id": "tfv_abc123", "tf_verification_status": "verified", "toll_free_registration_name": "Smith Campaign TFN", "org_id": "org_123", "org_name": "Smith Campaign 2024", "status": "active", "created_at": "2024-03-02T08:00:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/toll-free-verifications": { "get": { "tags": [ "Toll-Free Verifications" ], "summary": "List Toll-Free Verifications", "description": "List toll-free verifications (the carrier registrations behind your toll-free numbers) across your organization hierarchy. Filter by organization or by submission status.", "operationId": "listTollFreeVerifications", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "name": "status", "in": "query", "required": false, "description": "Filter by submission status", "schema": { "type": "string", "enum": [ "draft", "In Progress", "Verified", "Rejected" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "verification_request_id": { "type": "string" }, "org_id": { "type": "string" }, "org_name": { "type": "string" }, "business_name": { "type": "string" }, "use_case": { "type": "string" }, "phone_number_count": { "type": "integer" }, "submitted_at": { "type": "string" }, "verified_at": { "type": "string" }, "created_at": { "type": "string" } }, "additionalProperties": true } } } }, "example": { "success": true, "data": [ { "id": "tfv_abc123", "name": "Smith Campaign TFN", "status": "Verified", "verification_request_id": "TFV-1234567890", "org_id": "org_123", "org_name": "Smith Campaign 2024", "business_name": "Smith for Senate", "use_case": "Political", "phone_number_count": 2, "submitted_at": "2024-02-20T09:00:00Z", "verified_at": "2024-02-28T17:30:00Z", "created_at": "2024-02-19T10:00:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/toll-free-verifications/{id}": { "get": { "tags": [ "Toll-Free Verifications" ], "summary": "Get Toll-Free Verification", "description": "Fetch a single toll-free verification, including the phone numbers it covers and any rejection reason.", "operationId": "getTollFreeVerification", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "verification_request_id": { "type": "string" }, "org_id": { "type": "string" }, "org_name": { "type": "string" }, "business_name": { "type": "string" }, "use_case": { "type": "string" }, "phone_number_count": { "type": "integer" }, "phone_number_ids": { "type": "array", "items": { "type": "string" } }, "rejection_reason": { "type": [ "string", "null" ] }, "submitted_at": { "type": "string" }, "verified_at": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "additionalProperties": true } } }, "example": { "success": true, "data": { "id": "tfv_abc123", "name": "Smith Campaign TFN", "status": "Verified", "verification_request_id": "TFV-1234567890", "org_id": "org_123", "org_name": "Smith Campaign 2024", "business_name": "Smith for Senate", "use_case": "Political", "phone_number_count": 2, "phone_number_ids": [ "pn_def456", "pn_ghi789" ], "rejection_reason": null, "submitted_at": "2024-02-20T09:00:00Z", "verified_at": "2024-02-28T17:30:00Z", "created_at": "2024-02-19T10:00:00Z", "updated_at": "2024-02-28T17:30:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/contact-lists": { "get": { "tags": [ "Contact Lists" ], "summary": "List Contact Lists", "description": "List all contact lists. Filter by organization or brand.", "operationId": "listContactLists", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/BrandId" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "list_name": { "type": "string" }, "org_id": { "type": "string" }, "brand_id": { "type": "string" }, "contact_count": { "type": "integer" }, "status": { "type": "string" }, "created_at": { "type": "string" } }, "additionalProperties": true } } } }, "example": { "success": true, "data": [ { "id": "cl_abc123", "list_name": "Spring Outreach List", "org_id": "org_123", "brand_id": "brand_abc123", "contact_count": 12500, "status": "ready", "created_at": "2025-03-15T10:00:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/contact-lists/{id}": { "get": { "tags": [ "Contact Lists" ], "summary": "Get Contact List", "description": "Fetch a single contact list including import progress and analysis results.", "operationId": "getContactList", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "list_name": { "type": "string" }, "org_id": { "type": "string" }, "brand_id": { "type": "string" }, "status": { "type": "string" }, "contact_count": { "type": "integer" }, "import_progress": { "type": "object", "additionalProperties": true }, "analysis": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string" } }, "additionalProperties": true } } }, "example": { "success": true, "data": { "id": "cl_abc123", "list_name": "Spring Outreach List", "org_id": "org_123", "brand_id": "brand_abc123", "status": "ready", "contact_count": 12500, "import_progress": { "rows_total": 12500, "rows_imported": 12500, "rows_skipped": 0 }, "analysis": { "mobile": 11200, "landline": 800, "voip": 350, "invalid": 150, "last_run_at": "2025-03-15T10:05:00Z" }, "created_at": "2025-03-15T10:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/contact-lists/import": { "post": { "tags": [ "Contact Lists" ], "summary": "Import Contact List", "description": "Asynchronous job: import a CSV from a client-supplied presigned S3 or public HTTPS URL. Returns immediately with the created resource; poll `GET /contact-lists/{id}` until `status` is `ready`.", "operationId": "importContactList", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source_url", "list_name", "phone_column" ], "properties": { "source_url": { "type": "string", "format": "uri" }, "organization_id": { "type": "string", "description": "Target organization for the import. Defaults to the organization that owns the API key. Required only when targeting a sub-organization under an agency-tier parent; the API key must have access to the sub-organization (otherwise the request returns 403 ORG_ACCESS_DENIED)." }, "brand_id": { "type": "string", "description": "Optional. When provided, the list is scoped to this brand and the brand's organization is used (must match `organization_id` if both are sent, otherwise returns 400 BRAND_ORG_MISMATCH)." }, "list_name": { "type": "string" }, "phone_column": { "type": "string" }, "merge_tags": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "address": { "type": "string" }, "address_line_2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "csv_column": { "type": "string" }, "merge_tag": { "type": "string" } } } } } } } }, "example": { "source_url": "https://example.com/path/to/list.csv", "organization_id": "01HX0000000000000000000000", "brand_id": "01HX0000000000000000000001", "list_name": "Spring Outreach List", "phone_column": "phone", "merge_tags": { "first_name": "first_name", "last_name": "last_name", "address": "street", "address_line_2": "street2", "city": "city", "state": "state", "zip": "zip", "custom_fields": [ { "csv_column": "donor_tier", "merge_tag": "tier" } ] } } } } }, "responses": { "200": { "description": "Import accepted (poll the contact list for `ready` status)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "list_name": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string" } }, "additionalProperties": true } } }, "example": { "success": true, "data": { "id": "cl_abc123", "list_name": "Spring Outreach List", "status": "importing", "created_at": "2025-03-15T10:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/contact-lists/{id}/analyze": { "post": { "tags": [ "Contact Lists" ], "summary": "Analyze Contact List", "description": "Asynchronous job: trigger LRN mobile/landline/VoIP/invalid analysis for an imported list. Returns immediately; poll `GET /contact-lists/{id}` for analysis results. Billable.", "operationId": "analyzeContactList", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "responses": { "200": { "description": "Analysis queued", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "analysis_status": { "type": "string" }, "queued_at": { "type": "string" } }, "additionalProperties": true } } }, "example": { "success": true, "data": { "id": "cl_abc123", "analysis_status": "queued", "queued_at": "2025-03-15T10:10:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/media": { "get": { "tags": [ "Media Files" ], "summary": "List Media Files", "description": "List all media files. Filter by organization or brand.", "operationId": "listMedia", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/BrandId" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "org_id": { "type": "string" }, "brand_id": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "status": { "type": "string" }, "url": { "type": "string" }, "created_at": { "type": "string" } }, "additionalProperties": true } } } }, "example": { "success": true, "data": [ { "id": "med_abc123", "name": "spring-outreach-hero", "org_id": "org_123", "brand_id": "brand_abc123", "content_type": "image/jpeg", "size_bytes": 248320, "status": "ready", "url": "https://media.politicalcomms.com/med_abc123.jpg", "created_at": "2025-03-10T12:00:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "tags": [ "Media Files" ], "summary": "Import Media", "description": "Asynchronous job: import media from a client-supplied presigned S3 or public HTTPS URL. Server fetches, stores, and runs the optimization pipeline. Returns immediately; poll `GET /media/{id}` until `status` is `ready`.", "operationId": "importMedia", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source_url" ], "properties": { "source_url": { "type": "string", "format": "uri" }, "organization_id": { "type": "string", "description": "Target organization for the media file. Defaults to the organization that owns the API key. Required only when targeting a sub-organization under an agency-tier parent; the API key must have access to the sub-organization (otherwise the request returns 403 ORG_ACCESS_DENIED)." }, "brand_id": { "type": "string", "description": "Optional. When provided, the media file is scoped to this brand and the brand's organization is used (must match `organization_id` if both are sent, otherwise returns 400 BRAND_ORG_MISMATCH)." }, "name": { "type": "string" } } }, "example": { "source_url": "https://example.com/path/to/image.jpg", "organization_id": "01HX0000000000000000000000", "brand_id": "01HX0000000000000000000001", "name": "spring-outreach-hero" } } } }, "responses": { "200": { "description": "Import accepted (poll the media file for `ready` status)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string" } }, "additionalProperties": true } } }, "example": { "success": true, "data": { "id": "med_abc123", "name": "spring-outreach-hero", "status": "importing", "created_at": "2025-03-10T12:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/media/{id}": { "get": { "tags": [ "Media Files" ], "summary": "Get Media File", "description": "Fetch a single media file including readiness + metadata.", "operationId": "getMedia", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "org_id": { "type": "string" }, "brand_id": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "status": { "type": "string" }, "url": { "type": "string" }, "created_at": { "type": "string" } }, "additionalProperties": true } } }, "example": { "success": true, "data": { "id": "med_abc123", "name": "spring-outreach-hero", "org_id": "org_123", "brand_id": "brand_abc123", "content_type": "image/jpeg", "size_bytes": 248320, "width": 1920, "height": 1080, "status": "ready", "url": "https://media.politicalcomms.com/med_abc123.jpg", "created_at": "2025-03-10T12:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/projects": { "get": { "tags": [ "Projects" ], "summary": "List Projects", "description": "List all projects. Filter by organization, brand, or campaign.", "operationId": "listProjects", "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/BrandId" }, { "$ref": "#/components/parameters/CampaignId" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaign_id": { "type": "string" }, "campaign_name": { "type": "string" }, "brand_id": { "type": "string" }, "brand_name": { "type": "string" }, "org_id": { "type": "string" }, "org_name": { "type": "string" }, "message_text": { "type": "string" }, "created_at": { "type": "string" } }, "additionalProperties": true } } } }, "example": { "success": true, "data": [ { "id": "proj_abc123", "name": "GOTV Blast - Oct 15", "campaign_id": "camp_xyz789", "campaign_name": "Fall 2025 GOTV", "brand_id": "brand_abc123", "brand_name": "Smith PAC", "org_id": "org_123", "org_name": "Smith Campaign 2024", "message_text": "Hi {first_name}, vote Tuesday!", "created_at": "2025-10-10T09:00:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "tags": [ "Projects" ], "summary": "Create Project", "description": "Create a new project in draft status. Broadcast type only.\n\n**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`.\n\n**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).\n\nWhen `link_tracking_enabled` is `true`, `link_tracking_destination_url` and `link_tracking_domain_id` become required.", "operationId": "createProject", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "organization_id", "phone_number_ids", "name", "protocol", "contact_list_ids", "message_text" ], "properties": { "organization_id": { "type": "string" }, "channel": { "type": "string", "enum": [ "10dlc", "toll-free" ], "default": "10dlc", "description": "Messaging channel. Defaults to 10dlc." }, "brand_id": { "type": "string", "description": "Required when channel=10dlc; omit when channel=toll-free." }, "campaign_id": { "type": "string", "description": "Required when channel=10dlc; omit when channel=toll-free." }, "toll_free_verification_id": { "type": "string", "description": "Required when channel=toll-free; omit when channel=10dlc. Must match the verification behind the chosen phone_number_ids." }, "phone_number_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 49, "description": "Sending phone number IDs (1-49). New conversations are spread randomly across them; each recipient is then pinned to one number (sticky sender)." }, "phone_number_id": { "type": "string", "deprecated": true, "description": "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." }, "name": { "type": "string" }, "protocol": { "type": "string", "enum": [ "sms", "mms" ] }, "contact_list_ids": { "type": "array", "items": { "type": "string" } }, "suppression_list_ids": { "type": "array", "items": { "type": "string" } }, "message_text": { "type": "string" }, "media_ids": { "type": "array", "items": { "type": "string" } }, "link_tracking_enabled": { "type": "boolean" }, "link_tracking_destination_url": { "type": "string", "format": "uri" }, "link_tracking_domain_id": { "type": "string" }, "link_tracking_param_field": { "type": "string", "maxLength": 64, "description": "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." } } }, "examples": { "10dlc": { "summary": "10DLC project (brand + campaign)", "value": { "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" } }, "toll-free": { "summary": "Toll-free project (verification)", "value": { "organization_id": "01HX0000000000000000000000", "channel": "toll-free", "toll_free_verification_id": "01HX00000000000000000000T0", "phone_number_ids": [ "01HX00000000000000000000T1" ], "name": "Spring Outreach (TFN)", "protocol": "sms", "contact_list_ids": [ "01HX0000000000000000000004" ], "suppression_list_ids": [], "message_text": "Hi {first_name}, early voting starts Monday.", "media_ids": [] } } } } } }, "responses": { "200": { "description": "Project created (in draft status)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "channel": { "type": "string" }, "organization_id": { "type": "string" }, "brand_id": { "type": "string" }, "campaign_id": { "type": "string" }, "toll_free_verification_id": { "type": [ "string", "null" ] }, "phone_number_ids": { "type": "array", "items": { "type": "string" } }, "protocol": { "type": "string" }, "message_text": { "type": "string" }, "created_at": { "type": "string" } }, "additionalProperties": true } } }, "example": { "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" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/projects/stats": { "get": { "tags": [ "Projects" ], "summary": "Get Project Stats (all)", "description": "Get project statistics for a date range across the hierarchy.", "operationId": "getAllProjectStats", "parameters": [ { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "$ref": "#/components/parameters/OrganizationIdCamel" }, { "$ref": "#/components/parameters/BrandIdCamel" }, { "$ref": "#/components/parameters/CampaignIdCamel" }, { "name": "status", "in": "query", "required": false, "description": "Filter by status: draft, active, completed, archived, all", "schema": { "type": "string", "enum": [ "draft", "active", "completed", "archived", "all" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "totals": { "type": "object", "additionalProperties": true }, "projects": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true } } }, "example": { "success": true, "data": { "totals": { "projects": 14, "sent": 1452300, "delivered": 1438700, "undeliverable": 13600, "replies": 124400, "opt_outs": 8650, "clicks": 67200 }, "projects": [ { "id": "proj_abc123", "name": "GOTV Blast - Oct 15", "status": "completed", "sent": 125000, "delivered": 123900, "undeliverable": 1100, "replies": 11200, "opt_outs": 720, "clicks": 5840 } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/projects/{id}": { "get": { "tags": [ "Projects" ], "summary": "Get Project", "description": "Fetch a single project.", "operationId": "getProject", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "channel": { "type": "string" }, "campaign_id": { "type": "string" }, "campaign_name": { "type": "string" }, "brand_id": { "type": "string" }, "brand_name": { "type": "string" }, "toll_free_verification_id": { "type": [ "string", "null" ] }, "org_id": { "type": "string" }, "org_name": { "type": "string" }, "phone_number_ids": { "type": "array", "items": { "type": "string" } }, "protocol": { "type": "string" }, "message_text": { "type": "string" }, "media_ids": { "type": "array" }, "contact_list_ids": { "type": "array", "items": { "type": "string" } }, "suppression_list_ids": { "type": "array" }, "link_tracking_enabled": { "type": "boolean" }, "link_tracking_destination_url": { "type": "string" }, "link_tracking_domain_id": { "type": "string" }, "link_tracking_param_field": { "type": "string" }, "scheduled_at": { "type": "string" }, "scheduled_timezone": { "type": "string" }, "created_at": { "type": "string" } }, "additionalProperties": true } } }, "example": { "success": true, "data": { "id": "proj_abc123", "name": "GOTV Blast - Oct 15", "status": "completed", "channel": "10dlc", "campaign_id": "camp_xyz789", "campaign_name": "Fall 2025 GOTV", "brand_id": "brand_abc123", "brand_name": "Smith PAC", "toll_free_verification_id": null, "org_id": "org_123", "org_name": "Smith Campaign 2024", "phone_number_ids": [ "pn_abc123", "pn_def456" ], "protocol": "sms", "message_text": "Hi {first_name}, vote Tuesday! Polls open 7am-7pm.", "media_ids": [], "contact_list_ids": [ "cl_abc123" ], "suppression_list_ids": [], "link_tracking_enabled": true, "link_tracking_destination_url": "https://smithpac.example.com/vote", "link_tracking_domain_id": "01HX0000000000000000000005", "link_tracking_param_field": "voter_id", "scheduled_at": "2025-10-15T14:00:00Z", "scheduled_timezone": "America/New_York", "created_at": "2025-10-10T09:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "tags": [ "Projects" ], "summary": "Update Project", "description": "Update a project while in `draft` or `awaiting_test`. `organization_id` / `brand_id` / `campaign_id` / `channel` / `toll_free_verification_id` are immutable after creation; including them in the body returns a 400. All other fields are partial: send only the keys you want to change.", "operationId": "updateProject", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "message_text": { "type": "string" }, "protocol": { "type": "string", "enum": [ "sms", "mms" ] }, "phone_number_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 49, "description": "Replace the project's sending phone numbers (1-49). New conversations rotate across them; existing conversations keep their already-assigned sticky number." }, "phone_number_id": { "type": "string", "deprecated": true, "description": "Deprecated. Use phone_number_ids. A single id is treated as a one-element phone_number_ids." }, "contact_list_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "suppression_list_ids": { "type": "array", "items": { "type": "string" } }, "media_ids": { "type": "array", "items": { "type": "string" } }, "link_tracking_enabled": { "type": "boolean" }, "link_tracking_destination_url": { "type": [ "string", "null" ], "format": "uri" }, "link_tracking_domain_id": { "type": [ "string", "null" ] }, "link_tracking_param_field": { "type": [ "string", "null" ], "maxLength": 64, "description": "Contact field appended as a redirect query param on tracking links ('phone', a custom-field name, or null for none)." } } }, "example": { "name": "Spring Outreach (revised)", "message_text": "Hi {first_name}, early voting starts Monday. Learn more: {link}", "media_ids": [] } } } }, "responses": { "200": { "description": "Project updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "message_text": { "type": "string" }, "updated_at": { "type": "string" } }, "additionalProperties": true } } }, "example": { "success": true, "data": { "id": "proj_abc123", "name": "Spring Outreach (revised)", "status": "draft", "message_text": "Hi {first_name}, early voting starts Monday. Learn more: {link}", "updated_at": "2026-03-21T09:30:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/projects/{id}/stats": { "get": { "tags": [ "Projects" ], "summary": "Get Project Stats (single)", "description": "Aggregate metrics for a single project (sent, delivered, undeliverable, clicks, replies, opt-outs).", "operationId": "getProjectStats", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "project_id": { "type": "string" }, "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "undeliverable": { "type": "integer" }, "replies": { "type": "integer" }, "opt_outs": { "type": "integer" }, "clicks": { "type": "integer" }, "unique_clicks": { "type": "integer" }, "delivery_rate": { "type": "number" }, "reply_rate": { "type": "number" }, "click_rate": { "type": "number" } }, "additionalProperties": true } } }, "example": { "success": true, "data": { "project_id": "proj_abc123", "sent": 125000, "delivered": 123900, "undeliverable": 1100, "replies": 11200, "opt_outs": 720, "clicks": 5840, "unique_clicks": 5120, "delivery_rate": 0.9912, "reply_rate": 0.0904, "click_rate": 0.0471 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/projects/{id}/test": { "post": { "tags": [ "Projects" ], "summary": "Test Project", "description": "Send test message(s). Pass `test_contacts` as an array of 1-50 `{ phone }` objects. Merge fields in the message template are rendered from a sample contact in the project's contact list, not from the request.", "operationId": "testProject", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "test_contacts" ], "properties": { "test_contacts": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string" } } } } } }, "example": { "test_contacts": [ { "phone": "+15555550100" } ] } } } }, "responses": { "200": { "description": "Test sent", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "project_id": { "type": "string" }, "tests_sent": { "type": "integer" }, "sent_to": { "type": "array", "items": { "type": "string" } }, "queued_at": { "type": "string" } }, "additionalProperties": true } } }, "example": { "success": true, "data": { "project_id": "proj_abc123", "tests_sent": 1, "sent_to": [ "+15555550100" ], "queued_at": "2026-03-20T11:05:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/projects/{id}/schedule": { "post": { "tags": [ "Projects" ], "summary": "Schedule Project", "description": "Transition a project to `scheduled` status.", "operationId": "scheduleProject", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scheduled_at", "scheduled_timezone" ], "properties": { "scheduled_at": { "type": "string", "format": "date-time" }, "scheduled_timezone": { "type": "string", "example": "America/New_York" } } }, "example": { "scheduled_at": "2026-05-01T13:00:00-04:00", "scheduled_timezone": "America/New_York" } } } }, "responses": { "200": { "description": "Project scheduled", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "scheduled_at": { "type": "string" }, "scheduled_timezone": { "type": "string" } }, "additionalProperties": true } } }, "example": { "success": true, "data": { "id": "proj_abc123", "status": "scheduled", "scheduled_at": "2026-05-01T13:00:00-04:00", "scheduled_timezone": "America/New_York" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/projects/{id}/unschedule": { "post": { "tags": [ "Projects" ], "summary": "Unschedule Project", "description": "Transition a scheduled project back to `ready`.", "operationId": "unscheduleProject", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "responses": { "200": { "description": "Project unscheduled", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "scheduled_at": { "type": [ "string", "null" ] }, "scheduled_timezone": { "type": [ "string", "null" ] } }, "additionalProperties": true } } }, "example": { "success": true, "data": { "id": "proj_abc123", "status": "ready", "scheduled_at": null, "scheduled_timezone": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/messages/stats": { "get": { "tags": [ "Analytics" ], "summary": "Get Message Stats", "description": "Get message statistics aggregated by status with daily breakdowns.", "operationId": "getMessageStats", "parameters": [ { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "$ref": "#/components/parameters/OrganizationIdCamel" }, { "$ref": "#/components/parameters/BrandIdCamel" }, { "$ref": "#/components/parameters/CampaignIdCamel" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "totals": { "type": "object", "additionalProperties": true }, "daily": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true } } }, "example": { "success": true, "data": { "totals": { "sent": 1452300, "delivered": 1438700, "undeliverable": 13600, "replies": 124400, "opt_outs": 8650 }, "daily": [ { "date": "2026-01-01", "sent": 48400, "delivered": 47950, "undeliverable": 450, "replies": 4150, "opt_outs": 290 }, { "date": "2026-01-02", "sent": 51200, "delivered": 50720, "undeliverable": 480, "replies": 4280, "opt_outs": 310 } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ledger/usage": { "get": { "tags": [ "Billing" ], "summary": "Get Usage", "description": "Get usage and billing data by organization.", "operationId": "getLedgerUsage", "parameters": [ { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "$ref": "#/components/parameters/OrganizationIdCamel" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "organization_id": { "type": "string" }, "organization_name": { "type": "string" }, "period": { "type": "object", "additionalProperties": true }, "totals": { "type": "object", "additionalProperties": true }, "by_category": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true } } }, "example": { "success": true, "data": { "organization_id": "org_123", "organization_name": "Smith Campaign 2024", "period": { "start_date": "2026-01-01", "end_date": "2026-01-31" }, "totals": { "messages_sent": 1452300, "sms_charges": 14523.0, "mms_charges": 0.0, "carrier_lookup_charges": 125.0, "10dlc_charges": 129.5, "total_charges": 14777.5 }, "by_category": [ { "category": "sms", "units": 1452300, "amount": 14523.0 }, { "category": "carrier_lookup", "units": 25000, "amount": 125.0 }, { "category": "10dlc", "units": 1, "amount": 129.5 } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ledger/usage/by-initiator": { "get": { "tags": [ "Billing" ], "summary": "Get Usage by Initiator", "description": "Get usage grouped by initiating organization.", "operationId": "getLedgerUsageByInitiator", "parameters": [ { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "$ref": "#/components/parameters/OrganizationIdCamel" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "period": { "type": "object", "additionalProperties": true }, "by_initiator": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true } } }, "example": { "success": true, "data": { "period": { "start_date": "2026-01-01", "end_date": "2026-01-31" }, "by_initiator": [ { "initiator_org_id": "org_child_1", "initiator_org_name": "Regional Office East", "messages_sent": 580000, "total_charges": 5800.0 }, { "initiator_org_id": "org_child_2", "initiator_org_name": "Regional Office West", "messages_sent": 872300, "total_charges": 8723.0 } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Authenticate every request by passing your API key in the X-API-Key header. Keys are scoped to your organization hierarchy." } }, "parameters": { "IdPath": { "name": "id", "in": "path", "required": true, "description": "Resource ID", "schema": { "type": "string" } }, "OrganizationId": { "name": "organization_id", "in": "query", "required": false, "description": "Filter to a specific descendant organization", "schema": { "type": "string" } }, "BrandId": { "name": "brand_id", "in": "query", "required": false, "description": "Filter to a specific brand", "schema": { "type": "string" } }, "CampaignId": { "name": "campaign_id", "in": "query", "required": false, "description": "Filter to a specific campaign", "schema": { "type": "string" } }, "OrganizationIdCamel": { "name": "organizationId", "in": "query", "required": false, "description": "Filter to a specific descendant organization", "schema": { "type": "string" } }, "BrandIdCamel": { "name": "brandId", "in": "query", "required": false, "description": "Filter to a specific brand", "schema": { "type": "string" } }, "CampaignIdCamel": { "name": "campaignId", "in": "query", "required": false, "description": "Filter to a specific campaign", "schema": { "type": "string" } }, "StartDate": { "name": "startDate", "in": "query", "required": true, "description": "Start date in YYYY-MM-DD format", "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, "EndDate": { "name": "endDate", "in": "query", "required": true, "description": "End date in YYYY-MM-DD format", "schema": { "type": "string", "format": "date", "example": "2026-01-31" } } }, "responses": { "Unauthorized": { "description": "API key is missing, malformed, or revoked. Do not retry with the same credential; a human operator must issue a new key in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": "The provided API key is invalid or has been revoked", "code": "INVALID_API_KEY", "statusCode": 401 } } } }, "BadRequest": { "description": "Invalid parameters or malformed request. Do not retry without fixing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": "Invalid request parameters", "code": "BAD_REQUEST", "statusCode": 400 } } } }, "NotFound": { "description": "Resource does not exist. Verify the ID against a fresh list call before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": "Resource not found", "code": "NOT_FOUND", "statusCode": 404 } } } }, "RateLimited": { "description": "Rate limit exceeded (100 requests per minute per key on a 60-second sliding window; write-only keys 60/min, delete-only keys 30/min). Sleep for the Retry-After seconds before retrying, never tighter than once per second.", "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window (100 per minute for default keys; the value reflects this key's exact limit).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp (seconds) when a full window will have elapsed. The window slides, so capacity frees up continuously before this.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying (only on 429 responses).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": "Rate limit exceeded", "message": "Maximum 100 requests per 60 seconds", "code": "RATE_LIMIT_EXCEEDED", "statusCode": 429, "retryAfter": 12 } } } }, "Forbidden": { "description": "The key is valid but lacks access to this resource or organization hierarchy. Do not retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": "API key lacks the permission scope this endpoint requires", "code": "PERMISSION_DENIED", "statusCode": 403 } } } }, "InternalError": { "description": "Internal server error. Safe to retry with exponential backoff and jitter (1 second base, 60 second cap, 5 attempts). Send an Idempotency-Key on writes so retries cannot double-apply. Check https://status.politicalcomms.com before treating repeated failures as a client bug. If it persists, email support@politicalcomms.com with the X-Request-ID response header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "description": "Structured error object returned on non-2xx responses.", "required": [ "success", "error", "code", "statusCode" ], "properties": { "success": { "type": "boolean", "description": "Always false for error responses." }, "error": { "type": "string", "description": "Human-readable description of what went wrong." }, "code": { "type": "string", "description": "Machine-readable error code, e.g. INVALID_API_KEY or RATE_LIMIT_EXCEEDED." }, "statusCode": { "type": "integer", "description": "HTTP status code of the response." } } } } } }