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/

img

Digital Marketplace

Subscribe to the Messaging SMS APIs on the Swisscom Digital Marketplace.

img

SMS

Send SMS and check their status, we provide the product called Text Messaging:

img

Token Validation

Validate a phone number with a token as MFA, we provide the product called Phone Number Validation:

img

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_id required (See authentication)
  • SCS-Version required (Must be 2)
  • Content-Type required (E.g. application/json)
  • Accept required (Must be application/json)
  • SCS-Request-ID optional (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-Version required (Must be 2)
  • client_id required (See authentication)
  • Accept required (Defaults to application/json)
  • SCS-Request-ID optional (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

401, 403, 404, 405, 500, 503

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-Version required (Must be 2)
  • client_id required (See authentication)
  • Content-Type required (E.g. application/json)
  • Accept optional (Defaults to application/json)
  • SCS-Request-ID optional (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_id required (See authentication)
  • SCS-Version required (Must be 2)
  • Accept required (Must be application/json)
  • SCS-Request-ID optional (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
  • msisdn required (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.)
  • token required (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": ""
}
View the source for this page in GitHub