{"openapi":"3.0.3","info":{"title":"SMS Broadcast API","description":"API for managing SMS broadcasts, lists, metrics, and AI-powered content generation in ActiveCampaign","version":"3.0.0","contact":{"name":"ActiveCampaign Support","url":"https://www.activecampaign.com"}},"servers":[{"url":"https://{yourAccountName}.api-us1.com/api/3","description":"US-based Users","variables":{"yourAccountName":{"default":"yourAccountName"}}}],"paths":{"/sms/credits":{"get":{"tags":["Credits"],"summary":"Get current sms credit use data","description":"Retrieve the current period's sms credit usage and remaining balance","operationId":"getSmsCreditData","responses":{"200":{"description":"Sms Credits for this period","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsResponse"}}}}}}},"/sms/broadcasts":{"get":{"tags":["Broadcasts"],"summary":"Get all broadcast messages","description":"Gets a paged list of all of a customer's broadcast messages with optional filtering","operationId":"listBroadcasts","parameters":[{"name":"offset","in":"query","description":"Offset for pagination","schema":{"type":"integer","default":0}},{"name":"limit","in":"query","description":"Number of items to return","schema":{"type":"integer","default":20}},{"name":"filters[name]","in":"query","description":"Filter by broadcast name","schema":{"type":"string"}},{"name":"filters[status]","in":"query","description":"Filter by broadcast status","schema":{"type":"string","enum":["draft","scheduled","sent","pending_review","sending"]}},{"name":"filters[type]","in":"query","description":"Filter by broadcast type (future feature)","schema":{"type":"string"}},{"name":"orders[field]","in":"query","description":"Order results by field (ASC or DESC)","schema":{"type":"string","enum":["ASC","DESC"]}},{"name":"start_date","in":"query","description":"Filter by start date (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","description":"Filter by end date (YYYY-MM-DD)","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastListResponse"}}}},"403":{"description":"Insufficient permissions"}}},"post":{"tags":["Broadcasts"],"summary":"Create a new broadcast message","description":"Creates a new SMS broadcast message","operationId":"createBroadcast","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastCreateRequest"}}}},"responses":{"201":{"description":"Broadcast created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastMessage"}}}},"400":{"description":"Invalid request data"},"403":{"description":"Insufficient permissions"}}}},"/sms/broadcasts/{id}":{"get":{"tags":["Broadcasts"],"summary":"Get broadcast message","description":"Retrieves the full details for one broadcast message","operationId":"getBroadcast","parameters":[{"name":"id","in":"path","required":true,"description":"Broadcast ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastMessage"}}}},"403":{"description":"Insufficient permissions"},"404":{"description":"Broadcast not found"}}},"put":{"tags":["Broadcasts"],"summary":"Update broadcast message","description":"Updates an existing broadcast message","operationId":"updateBroadcast","parameters":[{"name":"id","in":"path","required":true,"description":"Broadcast ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastUpdateRequest"}}}},"responses":{"200":{"description":"Broadcast updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastMessage"}}}},"403":{"description":"Insufficient permissions"},"404":{"description":"Broadcast not found"}}},"delete":{"tags":["Broadcasts"],"summary":"Delete broadcast message","description":"Performs a soft-delete on the requested message","operationId":"deleteBroadcast","parameters":[{"name":"id","in":"path","required":true,"description":"Broadcast ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Broadcast deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastMessage"}}}},"403":{"description":"Insufficient permissions"},"404":{"description":"Broadcast not found"}}}},"/sms/lists":{"get":{"tags":["Broadcasts"],"summary":"Get all broadcast lists","description":"Gets a paged list of all broadcast lists (SMS channel)","operationId":"listBroadcastLists","parameters":[{"name":"offset","in":"query","description":"Offset for pagination","schema":{"type":"integer","default":0}},{"name":"limit","in":"query","description":"Number of items to return","schema":{"type":"integer","default":20}},{"name":"filters[name]","in":"query","description":"Filter by list name","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastListsResponse"}}}}}}},"/sms/broadcasts/ai":{"post":{"tags":["AI","Broadcasts"],"summary":"Create AI-generated broadcast","description":"Creates a broadcast using AI based on prompt and tone","operationId":"createAIBroadcast","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIBroadcastRequest"}}}},"responses":{"200":{"description":"AI broadcast request initiated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIBroadcastResponse"}}}}}},"put":{"summary":"Update broadcast with AI","description":"Updates an existing broadcast using AI","operationId":"updateAIBroadcast","tags":["AI","Broadcasts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIBroadcastUpdateRequest"}}}},"responses":{"200":{"description":"AI broadcast update request initiated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIBroadcastResponse"}}}}}}},"/sms/broadcasts/ai/{Id}":{"get":{"tags":["AI","Broadcasts"],"summary":"Get AI broadcast request status","description":"Returns the current status of the AI process execution","operationId":"getAIBroadcastStatus","parameters":[{"name":"Id","in":"path","required":true,"description":"Request ID from AI broadcast creation","schema":{"type":"string"}}],"responses":{"200":{"description":"Status retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIBroadcastStatus"}}}}}}},"/sms/broadcasts/metrics":{"post":{"tags":["Metrics","Broadcasts"],"summary":"Get all broadcast metrics","description":"Returns metrics for specified broadcast IDs","operationId":"getBroadcastMetrics","parameters":[{"name":"start_date","in":"query","description":"Start date for metrics (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","description":"End date for metrics (YYYY-MM-DD)","schema":{"type":"string","format":"date"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"integer"}}}}}}},"responses":{"200":{"description":"Metrics retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastMetricsResponse"}}}}}}},"/sms/broadcasts/metrics/snapshot":{"get":{"tags":["Metrics","Snapshots","Broadcasts"],"summary":"Get broadcast snapshot","description":"Returns snapshot data for all broadcasts","operationId":"getBroadcastSnapshot","parameters":[{"name":"start_date","in":"query","description":"Start date for snapshot (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","description":"End date for snapshot (YYYY-MM-DD)","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Snapshot retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotResponse"}}}}}},"post":{"tags":["Metrics","Snapshots","Broadcasts"],"summary":"Get broadcast snapshot","description":"Returns snapshot for specified broadcast IDs","operationId":"getBroadcastSnapshotByIds","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"integer"}}}}}}},"responses":{"200":{"description":"Snapshot retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotResponse"}}}}}}},"/sms/broadcasts/metrics/{broadcastId}/failures":{"get":{"tags":["Failures","Broadcasts","Metrics"],"summary":"Get broadcast failure details","description":"Returns grouping and counts of failures for the broadcast","operationId":"getBroadcastFailures","parameters":[{"name":"broadcastId","in":"path","required":true,"description":"Broadcast ID","schema":{"type":"integer"}},{"name":"start_date","in":"query","description":"Start date (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","description":"End date (YYYY-MM-DD)","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Failure details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureDetailsResponse"}}}}}}},"/sms/broadcasts/{broadcastId}/recipients":{"get":{"tags":["Recipients","Broadcasts"],"summary":"Get broadcast recipients","description":"Fetch all contacts who were sent a specific broadcast","operationId":"getBroadcastRecipients","parameters":[{"name":"broadcastId","in":"path","required":true,"description":"Broadcast ID","schema":{"type":"integer"}},{"name":"start_date","in":"query","description":"Start date (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","description":"End date (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"filters[deliverability][]","in":"query","description":"Filter by deliverability status","schema":{"type":"array","items":{"type":"string","enum":["deliveries","failures"]}}},{"name":"filters[engagement][]","in":"query","description":"Filter by engagement type","schema":{"type":"array","items":{"type":"string","enum":["clicks","replies","optOuts"]}}},{"name":"search","in":"query","description":"Search contacts by name or phone","schema":{"type":"string"}},{"name":"order[field]","in":"query","description":"Order by field","schema":{"type":"string","enum":["name","phone","sentDate","clicks","deliverability","optOut","replies"]}},{"name":"offset","in":"query","description":"Offset for pagination","schema":{"type":"integer","default":0}},{"name":"limit","in":"query","description":"Number of items to return","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Recipients retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecipientsResponse"}}}}}}},"/sms/broadcasts/export":{"post":{"tags":["Metrics","Exports","Broadcasts"],"summary":"Export broadcast metrics","description":"Export broadcast performance metrics as CSV","operationId":"exportBroadcastMetrics","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"integer"}}}}}}},"responses":{"200":{"description":"Export generated successfully","content":{"text/csv":{"schema":{"type":"string"}}}}}}},"/sms/broadcasts/{broadcastId}/recipients/export":{"post":{"tags":["Recipients","Exports","Broadcasts","Metrics"],"summary":"Export broadcast recipients","description":"Export recipient data as CSV including full contact records","operationId":"exportBroadcastRecipients","parameters":[{"name":"broadcastId","in":"path","required":true,"description":"Broadcast ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"engagement":{"type":"array","items":{"type":"string"}},"deliverability":{"type":"array","items":{"type":"string"}},"search":{"type":"string"},"order":{"type":"object"}}}}}},"responses":{"200":{"description":"Export generated successfully","content":{"text/csv":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"BroadcastMessage":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the broadcast"},"name":{"type":"string","description":"Name of the broadcast"},"address_id":{"type":"integer","nullable":true,"description":"ID used to get sender name"},"body":{"type":"string","description":"SMS message content"},"media_urls":{"type":"array","items":{"type":"string","format":"uri"},"description":"Media URLs for MMS messages"},"preview_url":{"type":"string","format":"uri","description":"URL for message preview"},"shorten_track_links_enabled":{"type":"boolean","description":"Whether link shortening is enabled"},"status":{"type":"string","enum":["draft","scheduled","sent","pending_review","sending"],"description":"Current status of the broadcast"},"sent_date":{"type":"string","format":"date-time","nullable":true,"description":"Date when broadcast was sent"},"scheduled_date":{"type":"string","format":"date-time","nullable":true,"description":"Scheduled send date (UTC)"},"custom_run_id":{"type":"string","format":"uuid","nullable":true,"description":"custom run id generated from segmentMatchSome endpoint"},"custom_segment_id":{"type":"string","format":"uuid","nullable":true,"description":"custom segment id generated from segmentsV2 endpoint and passing in a valid audience"},"scheduled_by":{"type":"integer","nullable":true,"description":"User ID who scheduled the broadcast"},"sent_to_count":{"type":"integer","nullable":true,"description":"Number of recipients"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp"},"created_by":{"type":"integer","description":"User ID who created the broadcast"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"},"updated_by":{"type":"integer","description":"User ID who last updated"},"deleted_at":{"type":"string","format":"date-time","nullable":true,"description":"Deletion timestamp (for soft deletes)"},"sift_approved":{"type":"integer","description":"Sift approval status"},"arc_approved":{"type":"integer","description":"ARC approval status"},"quiet_hours_enabled":{"type":"integer","nullable":true,"description":"Whether quiet hours are enabled"},"list_ids":{"type":"array","items":{"type":"integer"},"description":"Associated list IDs"},"segment_id":{"type":"string","nullable":true,"description":"Segment ID (can be UUID or integer string)"},"label_ids":{"type":"array","items":{"type":"integer"},"nullable":true,"description":"Associated label IDs"}}},"BroadcastCreateRequest":{"type":"object","required":["name","body"],"properties":{"name":{"type":"string","description":"Name of the broadcast"},"address_id":{"type":"integer","nullable":true,"description":"ID for sender name"},"body":{"type":"string","description":"SMS message content"},"media_urls":{"type":"array","items":{"type":"string","format":"uri"},"description":"Media URLs for MMS"},"preview_url":{"type":"string","format":"uri"},"shorten_track_links_enabled":{"type":"boolean"},"status":{"type":"string","enum":["draft"]},"scheduled_date":{"type":"string","format":"date-time"},"sent_to_count":{"type":"integer"},"list_ids":{"type":"array","items":{"type":"integer"}},"segment_id":{"type":"string"},"custom_segment_id":{"type":"string","description":"custom segment id generated from segmentsV2 endpoint and passing in a valid audience","format":"uuid","nullable":true},"label_ids":{"type":"array","items":{"type":"integer"}}}},"BroadcastUpdateRequest":{"type":"object","properties":{"name":{"type":"string"},"address_id":{"type":"integer","nullable":true},"body":{"type":"string"},"media_urls":{"type":"array","items":{"type":"string","format":"uri"}},"preview_url":{"type":"string","format":"uri"},"shorten_track_links_enabled":{"type":"boolean"},"status":{"type":"string","description":"Status of the broadcast. pending_review starts kicks off the broadcast to be sent","enum":["draft","pending_review"]},"scheduled_date":{"type":"string","format":"date-time"},"sent_to_count":{"type":"integer"},"list_ids":{"type":"array","items":{"type":"integer"}},"segment_id":{"type":"string"},"custom_run_id":{"type":"string","description":"custom run id generated from segmentMatchSome endpoint and passing a valid segment id","format":"uuid","nullable":true},"custom_segment_id":{"type":"string","description":"custom segment id generated from segmentsV2 endpoint and passing in a valid audience","format":"uuid","nullable":true},"label_ids":{"type":"array","items":{"type":"integer"}}}},"BroadcastListResponse":{"type":"object","properties":{"broadcasts":{"type":"array","items":{"$ref":"#/components/schemas/BroadcastMessage"}},"meta":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of broadcasts"}}}}},"BroadcastList":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subscriber_count":{"type":"integer"}}},"BroadcastListsResponse":{"type":"object","properties":{"lists":{"type":"array","items":{"$ref":"#/components/schemas/BroadcastList"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}},"AIBroadcastRequest":{"type":"object","required":["source","prompt","tone"],"properties":{"source":{"type":"string","enum":["ai_index","sms_index","ai_builder"]},"prompt":{"type":"string","description":"User prompt for AI generation"},"tone":{"type":"string","description":"Desired tone for the message"}}},"AIBroadcastUpdateRequest":{"type":"object","required":["source","prompt","tone","broadcastId"],"properties":{"source":{"type":"string","enum":["ai_index","sms_index","ai_builder"]},"prompt":{"type":"string"},"tone":{"type":"string"},"broadcastId":{"type":"integer"}}},"AIBroadcastResponse":{"type":"object","properties":{"requestId":{"type":"string","description":"External identifier to track the request"}}},"AIBroadcastStatus":{"type":"object","properties":{"source":{"type":"string","enum":["ai_index","sms_index","ai_builder"]},"status":{"type":"string","enum":["in_progress","error","success"]},"broadcastId":{"type":"integer","nullable":true}}},"BroadcastMetrics":{"type":"object","properties":{"id":{"type":"integer"},"sends":{"type":"integer"},"deliveries":{"type":"integer"},"replies":{"type":"integer"},"failures":{"type":"integer"},"optOuts":{"type":"integer"},"clicks":{"type":"integer"}}},"BroadcastMetricsResponse":{"type":"object","properties":{"metrics":{"type":"array","items":{"$ref":"#/components/schemas/BroadcastMetrics"}}}},"SnapshotResponse":{"type":"object","properties":{"snapshot":{"type":"object","properties":{"campaigns":{"type":"integer"},"sends":{"type":"integer"},"deliveries":{"type":"integer"},"clicks":{"type":"integer"},"replies":{"type":"integer"},"failures":{"type":"integer"},"optOuts":{"type":"integer"}}}}},"FailureDetail":{"type":"object","properties":{"errorCode":{"type":"string"},"errorSource":{"type":"string","enum":["ac","twilio"]},"count":{"type":"integer"}}},"FailureDetailsResponse":{"type":"object","properties":{"failures":{"type":"array","items":{"$ref":"#/components/schemas/FailureDetail"}}}},"Recipient":{"type":"object","properties":{"id":{"type":"integer","description":"Contact ID"},"name":{"type":"string"},"phoneNumber":{"type":"string"},"sentDate":{"type":"string","format":"date-time","description":"Timestamp in CST"},"clicks":{"type":"integer"},"deliverability":{"type":"string","enum":["delivered","failed"]},"replies":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"date":{"type":"string","format":"date-time","description":"Timestamp in CST"}}}},"optOut":{"type":"string","enum":["yes","no"]},"details":{"type":"object","properties":{"errorCode":{"type":"string"},"errorSource":{"type":"string","enum":["ac","twilio"]}}}}},"RecipientsResponse":{"type":"object","properties":{"recipients":{"type":"array","items":{"$ref":"#/components/schemas/Recipient"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}},"CreditsResponse":{"type":"object","properties":{"smsCredits":{"type":"object","properties":{"period":{"type":"string","example":"month"},"nextRefillDate":{"type":"string","example":"2026-02-26 15:06:25"},"includedThisPeriod":{"type":"integer","example":1000},"usedThisPeriod":{"type":"integer","example":71},"extra":{"type":"integer","example":9040},"available":{"type":"integer","example":9969}}}}}},"securitySchemes":{"ApiToken":{"type":"apiKey","name":"Api-Token","in":"header","description":"Your ActiveCampaign API token"}}},"security":[{"ApiToken":[]}]}