{"openapi":"3.0.3","info":{"title":"LynSMS API","version":"1.0.0","summary":"Production SMS API for sending, tracking, and managing messages at scale.","description":"The LynSMS REST API lets you send SMS messages, track delivery, manage sender IDs, configure webhooks, and rotate API keys from any HTTP-capable language.\n\nAll endpoints live under `\/api\/v1` and accept and return JSON. Authentication is via bearer API keys (see Authentication).","contact":{"name":"LynSMS Support","url":"https:\/\/lynsms.com\/support","email":"support@lynsms.com"},"license":{"name":"Proprietary"}},"servers":[{"url":"https:\/\/lynsms.com\/api\/v1","description":"Production"}],"tags":[{"name":"Messages","description":"Send and retrieve SMS messages."},{"name":"Account","description":"Account, balance, and usage."},{"name":"Senders","description":"Manage sender IDs."},{"name":"API Keys","description":"Create and rotate API keys."},{"name":"Webhooks","description":"Configure webhook endpoints and inspect events."}],"security":[{"BearerAuth":[]}],"paths":{"\/messages\/send":{"post":{"tags":["Messages"],"summary":"Send a single SMS","description":"Dispatches one SMS through the optimal provider for the destination, with automatic fallback if the primary provider fails.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/SendMessageRequest"},"examples":{"basic":{"summary":"Basic send","value":{"to":"+12025550143","from":"LynSMS","body":"Welcome to LynSMS \u2014 your code is 482194."}}}}}},"responses":{"201":{"description":"Message accepted for delivery.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MessageEnvelope"}}}},"400":{"$ref":"#\/components\/responses\/InvalidRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"402":{"$ref":"#\/components\/responses\/InsufficientBalance"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/RateLimited"},"500":{"$ref":"#\/components\/responses\/ServerError"}}}},"\/messages\/bulk":{"post":{"tags":["Messages"],"summary":"Send a message to many recipients","description":"Sends the same body to up to 1,000 recipients. Each recipient is sent as an individual message and reported back in the response.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/BulkMessageRequest"}}}},"responses":{"201":{"description":"Bulk send result.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/BulkResultEnvelope"}}}},"400":{"$ref":"#\/components\/responses\/InvalidRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"402":{"$ref":"#\/components\/responses\/InsufficientBalance"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/RateLimited"}}}},"\/messages\/{id}":{"get":{"tags":["Messages"],"summary":"Retrieve a message","parameters":[{"$ref":"#\/components\/parameters\/MessageId"}],"responses":{"200":{"description":"The requested message.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MessageEnvelope"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/messages":{"get":{"tags":["Messages"],"summary":"List messages","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","sent","delivered","failed","undelivered"]}},{"name":"to","in":"query","schema":{"type":"string"}},{"name":"created_after","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"created_before","in":"query","schema":{"type":"string","format":"date-time"}},{"$ref":"#\/components\/parameters\/Page"},{"$ref":"#\/components\/parameters\/Limit"}],"responses":{"200":{"description":"Paged list of messages.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MessageListEnvelope"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"}}}},"\/account":{"get":{"tags":["Account"],"summary":"Get the authenticated account","responses":{"200":{"description":"Account details.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AccountEnvelope"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"}}}},"\/balance":{"get":{"tags":["Account"],"summary":"Get the current account balance","responses":{"200":{"description":"Current balance.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/BalanceEnvelope"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"}}}},"\/usage":{"get":{"tags":["Account"],"summary":"Get message usage statistics","parameters":[{"name":"period","in":"query","schema":{"type":"string","enum":["day","month","all"],"default":"month"}}],"responses":{"200":{"description":"Usage statistics.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/UsageEnvelope"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"}}}},"\/senders":{"get":{"tags":["Senders"],"summary":"List sender IDs","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","approved","rejected","suspended"]}},{"$ref":"#\/components\/parameters\/Page"},{"$ref":"#\/components\/parameters\/Limit"}],"responses":{"200":{"description":"Paged list of senders.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/SenderListEnvelope"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"}}}},"\/senders\/create":{"post":{"tags":["Senders"],"summary":"Register a new sender ID","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CreateSenderRequest"}}}},"responses":{"201":{"description":"Sender created (pending approval).","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/SenderEnvelope"}}}},"400":{"$ref":"#\/components\/responses\/InvalidRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"}}}},"\/senders\/{id}":{"get":{"tags":["Senders"],"summary":"Retrieve a sender","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sender details.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/SenderEnvelope"}}}},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/api-keys":{"get":{"tags":["API Keys"],"summary":"List API keys","responses":{"200":{"description":"List of API keys on this account.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ApiKeyListEnvelope"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"}}}},"\/api-keys\/create":{"post":{"tags":["API Keys"],"summary":"Create a new API key","description":"The full plaintext key is returned **only once** in the response. Store it securely; it cannot be retrieved later.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CreateApiKeyRequest"}}}},"responses":{"201":{"description":"API key created.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CreatedApiKeyEnvelope"}}}},"400":{"$ref":"#\/components\/responses\/InvalidRequest"},"403":{"$ref":"#\/components\/responses\/Forbidden"}}}},"\/api-keys\/{id}":{"delete":{"tags":["API Keys"],"summary":"Revoke an API key","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Key revoked.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/DeletedEnvelope"}}}},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhook endpoints","responses":{"200":{"description":"Webhook endpoints.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/WebhookEndpointListEnvelope"}}}}}}},"\/webhooks\/create":{"post":{"tags":["Webhooks"],"summary":"Create a webhook endpoint","description":"The `signing_secret` is returned **only when created**. Use it to verify the `LynSMS-Signature` header on incoming webhooks.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CreateWebhookRequest"}}}},"responses":{"201":{"description":"Endpoint created.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/WebhookEndpointWithSecretEnvelope"}}}}}}},"\/webhooks\/{id}":{"get":{"tags":["Webhooks"],"summary":"Retrieve a webhook endpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook endpoint.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/WebhookEndpointEnvelope"}}}},"404":{"$ref":"#\/components\/responses\/NotFound"}}},"delete":{"tags":["Webhooks"],"summary":"Delete a webhook endpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Endpoint deleted.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/DeletedEnvelope"}}}}}}},"\/events":{"get":{"tags":["Webhooks"],"summary":"List webhook events","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["message.sent","message.delivered","message.failed"]}},{"$ref":"#\/components\/parameters\/Page"},{"$ref":"#\/components\/parameters\/Limit"}],"responses":{"200":{"description":"Paged list of events.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/EventListEnvelope"}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key passed as `Authorization: Bearer <KEY>`. Keys start with `ds_live_`."}},"parameters":{"MessageId":{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"msg_VyB2pNkX0wnA9aTrLqDh1Z3Fc"}},"Page":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}},"responses":{"InvalidRequest":{"description":"Invalid request.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"Forbidden":{"description":"API key lacks required permission.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"InsufficientBalance":{"description":"Insufficient balance to send.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"RateLimited":{"description":"Rate limit exceeded.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"ServerError":{"description":"Internal server error.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}},"schemas":{"Meta":{"type":"object","properties":{"request_id":{"type":"string"},"api_version":{"type":"string","example":"v1"}}},"Error":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","authorization_error","balance_error","rate_limit_error","provider_error","api_error"]},"code":{"type":"string","example":"invalid_request"},"message":{"type":"string"},"param":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"$ref":"#\/components\/schemas\/Meta"}}},"Message":{"type":"object","properties":{"id":{"type":"string","example":"msg_VyB2pNkX0wnA9aTrLqDh1Z3Fc"},"object":{"type":"string","example":"message"},"to":{"type":"string"},"from":{"type":"string"},"body":{"type":"string"},"status":{"type":"string","enum":["pending","sent","delivered","failed","undelivered"]},"cost":{"type":"number","format":"float"},"currency":{"type":"string","example":"USD"},"provider":{"type":"string","example":"twilio"},"provider_message_id":{"type":"string"},"attempts":{"type":"integer"},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"sent_at":{"type":"string","format":"date-time","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"failed_at":{"type":"string","format":"date-time","nullable":true}}},"Sender":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","example":"sender"},"sender_id":{"type":"string"},"type":{"type":"string","enum":["alphanumeric","numeric","short_code","long_code"]},"country_code":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","approved","rejected","suspended"]},"approved_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","example":"api_key"},"name":{"type":"string"},"key_hint":{"type":"string","example":"ds_live_a1b2...c3d4"},"is_active":{"type":"boolean"},"permissions":{"type":"array","items":{"type":"string"}},"rate_limit":{"type":"integer"},"last_used_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","example":"webhook_endpoint"},"url":{"type":"string","format":"uri"},"description":{"type":"string","nullable":true},"events":{"type":"array","items":{"type":"string","enum":["message.sent","message.delivered","message.failed"]}},"is_active":{"type":"boolean"},"failure_count":{"type":"integer"},"last_success_at":{"type":"string","format":"date-time","nullable":true},"last_failure_at":{"type":"string","format":"date-time","nullable":true},"disabled_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"Event":{"type":"object","properties":{"id":{"type":"string","example":"evt_..."},"object":{"type":"string","example":"event"},"type":{"type":"string","enum":["message.sent","message.delivered","message.failed"]},"created_at":{"type":"string","format":"date-time"},"data":{"$ref":"#\/components\/schemas\/Message"}}},"SendMessageRequest":{"type":"object","required":["to","from","body"],"properties":{"to":{"type":"string","description":"E.164 phone number.","example":"+12025550143"},"from":{"type":"string","description":"Sender ID. Up to 11 alphanumeric or a numeric long code.","example":"LynSMS"},"body":{"type":"string","maxLength":1600},"route_id":{"type":"integer","nullable":true},"provider":{"type":"string","enum":["twilio","sinch","infobip","clicksend","smsglobal","bulkgate","eurobate","silverstreet","suresms"],"nullable":true,"description":"Preferred provider (still falls back if it fails with a retryable error)."},"reference":{"type":"string","nullable":true,"description":"Your own correlation id."}}},"BulkMessageRequest":{"type":"object","required":["recipients","from","body"],"properties":{"recipients":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":1000},"from":{"type":"string"},"body":{"type":"string"},"route_id":{"type":"integer","nullable":true},"provider":{"type":"string","enum":["twilio","sinch","infobip","clicksend","smsglobal","bulkgate","eurobate","silverstreet","suresms"],"nullable":true}}},"CreateSenderRequest":{"type":"object","required":["sender_id"],"properties":{"sender_id":{"type":"string","maxLength":16},"type":{"type":"string","enum":["alphanumeric","numeric","short_code","long_code"]},"country_code":{"type":"string","minLength":2,"maxLength":2}}},"CreateApiKeyRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"},"example":["sms:send","sms:read"]},"rate_limit":{"type":"integer","minimum":1,"maximum":6000},"daily_limit":{"type":"integer","minimum":1,"nullable":true},"monthly_limit":{"type":"integer","minimum":1,"nullable":true},"allowed_ips":{"type":"array","items":{"type":"string"},"nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true}}},"CreateWebhookRequest":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["*","message.sent","message.delivered","message.failed"]}}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"pages":{"type":"integer"},"has_more":{"type":"boolean"}}},"Envelope":{"type":"object","properties":{"success":{"type":"boolean","example":true},"meta":{"$ref":"#\/components\/schemas\/Meta"}}},"MessageEnvelope":{"allOf":[{"$ref":"#\/components\/schemas\/Envelope"},{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Message"}}}]},"MessageListEnvelope":{"allOf":[{"$ref":"#\/components\/schemas\/Envelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Message"}},"pagination":{"$ref":"#\/components\/schemas\/Pagination"}}}]},"BulkResultEnvelope":{"allOf":[{"$ref":"#\/components\/schemas\/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","example":"bulk_result"},"total":{"type":"integer"},"sent":{"type":"integer"},"failed":{"type":"integer"},"messages":{"type":"array","items":{"$ref":"#\/components\/schemas\/Message"}}}}}}]},"AccountEnvelope":{"allOf":[{"$ref":"#\/components\/schemas\/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","example":"account"},"email":{"type":"string"},"name":{"type":"string"},"company_name":{"type":"string"},"country":{"type":"string"},"status":{"type":"string"},"kyc_verified":{"type":"boolean"},"balance":{"type":"number"},"currency":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}}]},"BalanceEnvelope":{"allOf":[{"$ref":"#\/components\/schemas\/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","example":"balance"},"balance":{"type":"number"},"currency":{"type":"string"},"as_of":{"type":"string","format":"date-time"}}}}}]},"UsageEnvelope":{"allOf":[{"$ref":"#\/components\/schemas\/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","example":"usage"},"period":{"type":"string"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"currency":{"type":"string"},"totals":{"type":"object","properties":{"messages":{"type":"integer"},"cost":{"type":"number"}}},"by_status":{"type":"object","additionalProperties":{"type":"integer"}}}}}}]},"SenderEnvelope":{"allOf":[{"$ref":"#\/components\/schemas\/Envelope"},{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Sender"}}}]},"SenderListEnvelope":{"allOf":[{"$ref":"#\/components\/schemas\/Envelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Sender"}},"pagination":{"$ref":"#\/components\/schemas\/Pagination"}}}]},"ApiKeyListEnvelope":{"allOf":[{"$ref":"#\/components\/schemas\/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/ApiKey"}}}}}}]},"CreatedApiKeyEnvelope":{"allOf":[{"$ref":"#\/components\/schemas\/Envelope"},{"type":"object","properties":{"data":{"allOf":[{"$ref":"#\/components\/schemas\/ApiKey"},{"type":"object","properties":{"plain_key":{"type":"string","description":"Full plaintext key \u2014 shown only once."},"plain_key_notice":{"type":"string"}}}]}}}]},"DeletedEnvelope":{"allOf":[{"$ref":"#\/components\/schemas\/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string"},"deleted":{"type":"boolean","example":true}}}}}]},"WebhookEndpointEnvelope":{"allOf":[{"$ref":"#\/components\/schemas\/Envelope"},{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/WebhookEndpoint"}}}]},"WebhookEndpointWithSecretEnvelope":{"allOf":[{"$ref":"#\/components\/schemas\/Envelope"},{"type":"object","properties":{"data":{"allOf":[{"$ref":"#\/components\/schemas\/WebhookEndpoint"},{"type":"object","properties":{"signing_secret":{"type":"string","description":"HMAC SHA-256 signing secret. Returned only on creation."}}}]}}}]},"WebhookEndpointListEnvelope":{"allOf":[{"$ref":"#\/components\/schemas\/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/WebhookEndpoint"}}}}}}]},"EventListEnvelope":{"allOf":[{"$ref":"#\/components\/schemas\/Envelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Event"}},"pagination":{"$ref":"#\/components\/schemas\/Pagination"}}}]}}},"x-webhooks":{"message.sent":{"post":{"summary":"Sent to your endpoint when a message is accepted by an upstream provider.","requestBody":{"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Event"}}}},"responses":{"200":{"description":"Return 2xx within 10s to acknowledge."}}}},"message.delivered":{"post":{"summary":"Sent when the carrier confirms delivery (via DLR).","requestBody":{"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Event"}}}},"responses":{"200":{"description":"Return 2xx within 10s to acknowledge."}}}},"message.failed":{"post":{"summary":"Sent when delivery fails permanently.","requestBody":{"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Event"}}}},"responses":{"200":{"description":"Return 2xx within 10s to acknowledge."}}}}}}