{"openapi":"3.0.3","info":{"title":"Instacall Commercial SMS & Telecom API","version":"1.0.0","description":"Enterprise-grade REST API with 100% portal feature parity. Manage single & batch SMS, campaigns, contact groups, 2-way chat, wallet ledger, analytics reports, sub-accounts, and carrier intelligence.","contact":{"name":"Instacall Telecom API Support","url":"https://instacall.digital","email":"support@instacall.digital"}},"servers":[{"url":"https://smsc.instacall.digital","description":"Production SMS API (HTTPS)"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"tags":[{"name":"Messages","description":"Single SMS dispatch and message lifecycle tracking"},{"name":"Batch Messaging","description":"High-volume multi-recipient campaigns and status polling"},{"name":"Carrier Intelligence & Lookup","description":"SipSmart LRN carrier dip, OCN, and portability verification"},{"name":"Campaigns & Blasts","description":"Campaign creation, dispatch, blast execution history, and pause/resume control"},{"name":"Contact Groups & Contacts","description":"Contact lists, bulk contact management, and phone intelligence audits"},{"name":"Two-Way Chat (1-to-1)","description":"Conversational messaging threads, history, and real-time replies"},{"name":"Account & Wallet Ledger","description":"Real-time balance, assigned DIDs, and historical transaction statements"},{"name":"Reports & Analytics","description":"Aggregated performance metrics, delivery rates, and carrier breakdown"},{"name":"Team & Sub-Accounts","description":"Manage managers and team member access programmatically"},{"name":"Webhooks","description":"Real-time DLR & Inbound MO webhooks with HMAC-SHA256 signatures"}],"paths":{"/api/v1/messages":{"post":{"tags":["Messages"],"summary":"Send a single SMS message","description":"Dispatches an outbound SMS with real-time routing, carrier LRN dip, and instant refund on carrier failure.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to","from","body"],"properties":{"to":{"type":"string","example":"+1234567890"},"from":{"type":"string","example":"13078551234"},"body":{"type":"string","example":"Hello from Instacall API!"},"callback_url":{"type":"string","format":"uri","example":"https://customer.api/dlr"}}}}}},"responses":{"201":{"description":"Message queued and dispatched"},"400":{"description":"Invalid phone number or insufficient funds"},"401":{"description":"Unauthorized"}}},"get":{"tags":["Messages"],"summary":"List message history (SMS Logs)","description":"Paginated message logs with filtering by status, date, and phone numbers.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"status","in":"query","schema":{"type":"string","enum":["QUEUED","SENT","DELIVERED","FAILED"]}},{"name":"to","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Message logs list"}}}},"/api/v1/messages/{id}":{"get":{"tags":["Messages"],"summary":"Retrieve single message status","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Message details and carrier status"},"404":{"description":"Message not found"}}}},"/api/v1/messages/batch":{"post":{"tags":["Batch Messaging"],"summary":"Send a batch of SMS messages","description":"Queue up to 1,000 distinct messages in a single API call.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["messages"],"properties":{"from":{"type":"string","example":"13078551234"},"messages":{"type":"array","items":{"type":"object","required":["to","body"],"properties":{"to":{"type":"string","example":"+1234567890"},"body":{"type":"string","example":"Batch alert message"},"from":{"type":"string","example":"13078551234"}}}}}}}}},"responses":{"202":{"description":"Batch accepted and queued"}}}},"/api/v1/messages/batch/{batch_id}":{"get":{"tags":["Batch Messaging"],"summary":"Poll batch processing status and progress","parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Batch breakdown and completion statistics"}}}},"/api/v1/lookup/{number}":{"get":{"tags":["Carrier Intelligence & Lookup"],"summary":"Query carrier identity and LRN","parameters":[{"name":"number","in":"path","required":true,"schema":{"type":"string"},"example":"+1234567890"}],"responses":{"200":{"description":"Live carrier, OCN, line type, and portability information"}}}},"/api/v1/campaigns":{"get":{"tags":["Campaigns & Blasts"],"summary":"List customer campaigns","responses":{"200":{"description":"Customer campaigns with message templates and statistics"}}},"post":{"tags":["Campaigns & Blasts"],"summary":"Create a new campaign","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","message_template"],"properties":{"name":{"type":"string","example":"Black Friday VIP Promo"},"message_template":{"type":"string","example":"Hi {name}, enjoy 50% off today!"},"status":{"type":"string","enum":["ACTIVE","INACTIVE"],"default":"ACTIVE"}}}}}},"responses":{"201":{"description":"Campaign created successfully"}}}},"/api/v1/campaigns/{id}":{"get":{"tags":["Campaigns & Blasts"],"summary":"Get campaign details","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Campaign details with recent blast executions"}}},"put":{"tags":["Campaigns & Blasts"],"summary":"Update campaign","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"message_template":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","INACTIVE"]}}}}}},"responses":{"200":{"description":"Campaign updated successfully"}}}},"/api/v1/campaigns/{id}/dispatch":{"post":{"tags":["Campaigns & Blasts"],"summary":"Dispatch campaign blast to a contact group","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["group_id"],"properties":{"group_id":{"type":"string","example":"grp_12345"},"from_numbers":{"type":"array","items":{"type":"string"},"example":["13078551234"]},"internal_route_id":{"type":"string"}}}}}},"responses":{"202":{"description":"Blast enqueued for processing"}}}},"/api/v1/campaigns/blasts":{"get":{"tags":["Campaigns & Blasts"],"summary":"List campaign blast execution logs","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"List of past blasts with deliverability and cost statistics"}}}},"/api/v1/campaigns/blasts/{blast_id}":{"get":{"tags":["Campaigns & Blasts"],"summary":"Get single campaign blast statistics","parameters":[{"name":"blast_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Blast details, status breakdown, and cost"}}}},"/api/v1/campaigns/blasts/{blast_id}/pause":{"post":{"tags":["Campaigns & Blasts"],"summary":"Pause in-flight campaign blast","parameters":[{"name":"blast_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Blast paused"}}}},"/api/v1/campaigns/blasts/{blast_id}/resume":{"post":{"tags":["Campaigns & Blasts"],"summary":"Resume paused campaign blast","parameters":[{"name":"blast_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Blast resumed"}}}},"/api/v1/contacts/groups":{"get":{"tags":["Contact Groups & Contacts"],"summary":"List contact groups","responses":{"200":{"description":"Contact groups with member counts"}}},"post":{"tags":["Contact Groups & Contacts"],"summary":"Create a new contact group","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"VIP Retail Buyers"}}}}}},"responses":{"201":{"description":"Group created successfully"}}}},"/api/v1/contacts/groups/{id}":{"get":{"tags":["Contact Groups & Contacts"],"summary":"Get contact group details","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Group info and contact count"}}},"delete":{"tags":["Contact Groups & Contacts"],"summary":"Delete contact group","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Group deleted successfully"}}}},"/api/v1/contacts/groups/{id}/contacts":{"get":{"tags":["Contact Groups & Contacts"],"summary":"List contacts in a group","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"search","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated contacts in group"}}},"post":{"tags":["Contact Groups & Contacts"],"summary":"Add contacts to group (single or bulk array)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","required":["phone_number"],"properties":{"phone_number":{"type":"string","example":"12125551234"},"name":{"type":"string","example":"Jane Doe"},"email":{"type":"string","example":"jane@example.com"}}}}}}}}},"responses":{"201":{"description":"Contacts imported successfully"}}}},"/api/v1/contacts/groups/{id}/audit":{"post":{"tags":["Contact Groups & Contacts"],"summary":"Audit contact group (detect wireless, landline, VoIP)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Group carrier and line type audit results"}}}},"/api/v1/contacts/{id}":{"delete":{"tags":["Contact Groups & Contacts"],"summary":"Delete single contact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Contact deleted"}}}},"/api/v1/chats/conversations":{"get":{"tags":["Two-Way Chat (1-to-1)"],"summary":"List conversation threads","description":"Fetch two-way chat threads grouped by remote counterparty phone number.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Conversation threads with unread indicators"}}}},"/api/v1/chats/messages":{"get":{"tags":["Two-Way Chat (1-to-1)"],"summary":"Get conversation message history","parameters":[{"name":"number","in":"query","required":true,"schema":{"type":"string"},"example":"+1234567890"},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Chronological message history"}}},"post":{"tags":["Two-Way Chat (1-to-1)"],"summary":"Send 1-to-1 conversational message","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to","body"],"properties":{"to":{"type":"string","example":"+1234567890"},"from":{"type":"string","example":"13078551234"},"body":{"type":"string","example":"Thanks for reaching out! How can we assist you?"}}}}}},"responses":{"201":{"description":"1-to-1 message sent"}}}},"/api/v1/account/balance":{"get":{"tags":["Account & Wallet Ledger"],"summary":"Get account balance","responses":{"200":{"description":"Real-time wallet balance and currency"}}}},"/api/v1/account/numbers":{"get":{"tags":["Account & Wallet Ledger"],"summary":"List customer virtual numbers / DIDs","responses":{"200":{"description":"Assigned virtual phone numbers"}}}},"/api/v1/wallet/transactions":{"get":{"tags":["Account & Wallet Ledger"],"summary":"Get financial transaction statements","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"type","in":"query","schema":{"type":"string","enum":["CREDIT","DEBIT","REFUND"]}}],"responses":{"200":{"description":"Transaction history ledger"}}}},"/api/v1/reports/summary":{"get":{"tags":["Reports & Analytics"],"summary":"Get SMS deliverability and spend report","parameters":[{"name":"time_filter","in":"query","schema":{"type":"string","enum":["today","yesterday","7d","30d","this_month"]}},{"name":"start_date","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"end_date","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Aggregated analytics, deliverability rates, and carrier breakdown"}}}},"/api/v1/team":{"get":{"tags":["Team & Sub-Accounts"],"summary":"List team managers and sub-accounts","responses":{"200":{"description":"Team members list"}}}},"/api/v1/team/invite":{"post":{"tags":["Team & Sub-Accounts"],"summary":"Create or invite a team manager","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email","password"],"properties":{"name":{"type":"string","example":"Alex Smith"},"email":{"type":"string","example":"alex@company.com"},"password":{"type":"string","example":"SecurePass123!"},"role":{"type":"string","enum":["MANAGER","USER"],"default":"USER"}}}}}},"responses":{"201":{"description":"Team member created"}}}},"/api/v1/team/{id}":{"delete":{"tags":["Team & Sub-Accounts"],"summary":"Remove a team member","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Team member deleted"}}}},"/api/v1/account/webhook":{"get":{"tags":["Webhooks"],"summary":"Get customer webhook endpoint","responses":{"200":{"description":"Configured webhook URL and secret status"}}},"post":{"tags":["Webhooks"],"summary":"Create or update webhook endpoint","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","example":"https://myapi.com/webhooks/sms"},"secret":{"type":"string","example":"whsec_custom_secret"}}}}}},"responses":{"200":{"description":"Webhook configuration saved"}}},"delete":{"tags":["Webhooks"],"summary":"Delete customer webhook endpoint","responses":{"200":{"description":"Webhook deleted"}}}},"/api/v1/account/webhook/test":{"post":{"tags":["Webhooks"],"summary":"Send test ping to customer webhook","responses":{"200":{"description":"Test ping execution result with response latency"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Instacall API Key header (x-api-key: ic_...)"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API-Key","description":"Standard Bearer Token (Authorization: Bearer ic_...)"}}}}