Swisscom Messaging Api Product
Page last updated:
Swisscom Messaging API Product: SMS, MFA, Campaigns
Product Page
More infos on our Product page: https://sms.scapp.swisscom.com/
Digital Marketplace
Subscribe to the Messaging SMS APIs on the Swisscom Digital Marketplace.
SMS
Send SMS and check their status, we provide the product called Text Messaging:
Token Validation
Validate a phone number with a token as MFA, we provide the product called Phone Number Validation:
API Resources
Below more technical details about the APIs, the most current documentation is on the Product Pages on the Digital Marketplace.
Sending SMS
POST /messaging/sms
curl -X POST https://api.swisscom.com/messaging/sms -H 'SCS-Version: 2' -H 'client_id: {YourClientID}' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'SCS-Request-ID: {YourRequestID}' -d '{"to": "{YourPhoneNumber}", "text": "YourMessageText."}'
Request
Headers
client_idrequired (See authentication)SCS-Versionrequired (Must be2)Content-Typerequired (E.g.application/json)Acceptrequired (Must beapplication/json)SCS-Request-IDoptional (Can be used to trace your request to our API. Only relevant if you need support from our team so they know which request to look into.)
Body Example (application/json)
{
"to": "+41791234567",
"text": "Greetings from Swisscom!"
}
If you need updates about the SMS state (e.g. SMS was received), you can set the callBackUrl parameter. You will receive an HTTP PUT request to this URL, for any state change of this SMS.
Success Responses
201 Response
no content
Error Responses
400, 401, 403, 404, 405, 406, 429, 500, 503
Most updated error response you can find on the documention on Swisscom Digital Markeplace
Get status information for an SMS
GET /messaging/sms/{messageId}
curl https://api.swisscom.com//messaging/sms/{messageId} -H 'SCS-Version: 2' -H 'client_id: {YourClientID}' -H 'Accept: application/json' -H 'SCS-Request-ID: {YourRequestID}'
Request
Headers
SCS-Versionrequired (Must be2)client_idrequired (See authentication)Acceptrequired (Defaults toapplication/json)SCS-Request-IDoptional (Can be used to trace your request to our API. Only relevant if you need support from our team so they know which request to look into.)
URI Parameters
messageId(MessageId of the SMS. You will receive this in the location header of the initial post to send the sms.)
Success Responses
201 Response Example (application/json)
{
"messageId": "0001",
"status": "201",
...
}
Error Responses
Initiate SMS Token Validation process
POST /messaging/tokenvalidation
curl -X POST https://api.swisscom.com/messaging/tokenvalidation -H 'SCS-Version: 2' -H 'client_id: MyClientID' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'SCS-Request-ID: {YourRequestID}' -d '{"to":"+41791234567", "text":"Take this token: %TOKEN%", "tokenType":"SHORT_NUMERIC", "expireTime":120,"tokenLength":6}'
This call will start the SMS Token validation process by sending a validation token to an MSISDN. The validation token is a random string of characters that is sent to the user’s mobile phone. After making this call, your application can then verify that the user recieved the validation token by calling the Validate SMS Token endpoint.
Request
Headers
SCS-Versionrequired (Must be2)client_idrequired (See authentication)Content-Typerequired (E.g.application/json)Acceptoptional (Defaults toapplication/json)SCS-Request-IDoptional (Can be used to trace your request to our API. Only relevant if you need support from our team so they know which request to look into.)
Body Example (application/json)
{
"to": "+41791544781",
"text": "Verification code: %TOKEN% \r\n Expires in 60 seconds.",
"tokenType": "SHORT_ALPHANUMERIC",
"expireTime": 60,
"tokenLength": 6
}
Use %TOKEN% as a placeholder for where the actual token should go.
Success Responses
201 Response
no content
Error Responses
400, 401, 403, 404, 405, 406, 429, 500, 503
Validate SMS token
GET /messaging/tokenvalidation/{msisdn}/{token}
curl https://api.swisscom.com/messaging/tokenvalidation/{YourMsisdn}/{YourReceivedToken} -H 'SCS-Version: 2' -H 'client_id: {YourClientID}' -H 'Accept: application/json' -H 'SCS-Request-ID: {YourRequestID}'
Validate a token sent to the MSISDN number using the Send SMS Token endpoint. This call is made after the Send SMS Token call to validate the token sent to the end user via SMS.
Request
Headers
client_idrequired (See authentication)SCS-Versionrequired (Must be2)Acceptrequired (Must beapplication/json)SCS-Request-IDoptional (Can be used to trace your request to our API. Only relevant if you need support from our team so they know which request to look into.)
URI Parameters
msisdnrequired (The token depending phone number. A valid number starts with 0, 00 or + and must contain 7 to 15 digits. Local numbers (prefix 0) are handled with international code +41 by default.)tokenrequired (The token to verify.)
Success Responses
200 Response Example (application/json)
{
"validation": "SUCCESS"
}
Error Responses
400, 401, 403, 404, 405, 406, 500, 503
Error Handling
Error Response Examples
400 (Bad Request. Invalid request.)
{
"status": "400",
"code": "INVALID_REQUEST",
"message": "The request could not be understood due to malformed syntax. Correct the request syntax and try again.",
"detail": ""
}
401 (Unauthorized. No permission to access resource or invalid API key.)
{
"status": "401",
"code": "INVALID_AUTHENTICATION_CREDENTIALS",
"message": "Authentication credentials missing or incorrect. Check that you are using the correct authentication method and that you have permission to the given resource and your app key is approved.",
"detail": ""
}
403 (Forbidden. No permission to access requested resource.)
{
"status": "403",
"code": "FORBIDDEN_RESOURCE",
"message": "The server understood the request, but is refusing to fulfill it. Check that you have permission to the given resource.",
"detail": ""
}
404 (Not Found. The server has not found a resource matching the Request-URI.)
{
"status": "404",
"code": "INVALID_REQUEST_RESOURCE",
"message": "The requested resource does not exist. Verify that the resource URI is correctly spelled.",
"detail": ""
}
405 (Method Not Allowed. The resource is not accessible via the given HTTP method. For example, the client sent a POST request to a resource that only supports GET.)
{
"status": "405",
"code": "INVALID_REQUEST_METHOD",
"message": "The resource is not accessible via the given method. Check the documentation or the Allow header for allowed methods.",
"detail": ""
}
406 (Invalid Header Accept. The provided Accept-type is not supported by the resource.)
{
"status": "406",
"code": "INVALID_HEADER_ACCEPT",
"message": "The requested resource is only capable of generating content not acceptable according to the Accept headers sent in the request. Make sure the request has an Accept header with a media type supported by the API. Check the developer portal for supported media types.",
"detail": ""
}
429 (Too Many Requests. Quota for this service has been exhausted. Message must contain further details.)
{
"status": "429",
"code": "EXPIRED_QUOTA",
"message": "Your quota for this service has been exhausted. Try again later or contact support at developer-support@swisscom.com.",
"detail": ""
}
500 (Internal Server Error. The server has run into an unexpected condition.)
{
"status": "500",
"code": "INTERNAL_SERVER_ERROR",
"message": "The server encountered an unexpected condition which prevented it from fulfilling the request. Try again later or contact support at developer-support@swisscom.com.",
"detail": ""
}
503 (Service Unavailable. The server is currently unable to handle the request due to temporary overloading or maintenance. Typically, back end is unavailable.)
{
"status": "503",
"code": "UNAVAILABLE_SERVICE",
"message": "The server is currently unable to handle the request due to temporary overloading or maintenance. Try again later or contact support at developer-support@swisscom.com.",
"detail": ""
}