smart-messaging.html.md.erb

---
title: Swisscom Messaging Api Product
owner: API
---

# Swisscom Messaging API Product: SMS, MFA, Campaigns

## <a id='productpage'></a> Product Page
More infos on our Product page: https://sms.scapp.swisscom.com/

[![img](./img/sms-dashboard.png)](https://sms.scapp.swisscom.com/)

## <a id='digitalmarketplace'></a> Digital Marketplace
Subscribe to the Messaging SMS APIs on the [Swisscom Digital Marketplace](https://digital.swisscom.com). 

[![img](./img/dm.png)](https://digital.swisscom.com)

## <a id='sms'></a> SMS

Send SMS and check their status, we provide the product called [Text Messaging](https://digital.swisscom.com/products/text-messaging/info):

[![img](./img/dm-messaging.png)](https://digital.swisscom.com/products/text-messaging/info)

## <a id='tokenvalidation'></a> Token Validation

Validate a phone number with a token as MFA, we provide the product called [Phone Number Validation](https://digital.swisscom.com/products/phone-number-validation/info):

[![img](./img/dm-tokenvalidation.png)](https://digital.swisscom.com/products/phone-number-validation/info)

## <a id='API'></a> API Resources
Below more technical details about the APIs, the most current documentation is on the Product Pages on the Digital Marketplace.

### Sending SMS

```txt
POST /messaging/sms
```

<pre class="terminal">
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."}'
</pre>

#### Request

##### Headers

* `client_id` required (See [authentication](#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)

```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

```txt
no content
```

#### Error Responses

[400](#400), [401](#401), [403](#403), [404](#404), [405](#405), [406](#406), [429](#429), [500](#500), [503](#503)

Most updated error response you can find on the documention on Swisscom Digital Markeplace

### Get status information for an SMS

```txt
GET /messaging/sms/{messageId}
```

<pre class="terminal">
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}'
</pre>

#### Request

##### Headers

* `SCS-Version` required (Must be `2`)
* `client_id` required (See [authentication](#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)

```json
{
  "messageId": "0001",
  "status": "201",
  ...
}
```

#### Error Responses

[401](#401), [403](#403), [404](#404), [405](#405), [500](#500), [503](#503)

### Initiate SMS Token Validation process

```txt
POST /messaging/tokenvalidation
```

<pre class="terminal">
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}'
</pre>

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](#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)

```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

```txt
no content
```

#### Error Responses

[400](#400), [401](#401), [403](#403), [404](#404), [405](#405), [406](#406), [429](#429), [500](#500), [503](#503)

### Validate SMS token

```txt
GET /messaging/tokenvalidation/{msisdn}/{token}
```

<pre class="terminal">
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}'
</pre>

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](#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)

```json
{
  "validation": "SUCCESS"
}
```

#### Error Responses

[400](#400), [401](#401), [403](#403), [404](#404), [405](#405), [406](#406),  [500](#500), [503](#503)

## <a id='error-handling'></a> Error Handling

### Error Response Examples

#### <a id='400'></a> 400 (Bad Request. Invalid request.)

```json
{
  "status": "400",
  "code": "INVALID_REQUEST",
  "message": "The request could not be understood due to malformed syntax. Correct the request syntax and try again.",
  "detail": ""
}
```

#### <a id='401'></a> 401 (Unauthorized. No permission to access resource or invalid API key.)

```json
{
  "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": ""
}
```

#### <a id='403'></a> 403 (Forbidden. No permission to access requested resource.)

```json
{
  "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": ""
}
```

#### <a id='404'></a> 404 (Not Found. The server has not found a resource matching the Request-URI.)

```json
{
  "status": "404",
  "code": "INVALID_REQUEST_RESOURCE",
  "message": "The requested resource does not exist. Verify that the resource URI is correctly spelled.",
  "detail": ""
}
```

#### <a id='405'></a> 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.)

```json
{
  "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": ""
}
```

#### <a id='406'></a> 406 (Invalid Header Accept. The provided Accept-type is not supported by the resource.)

```json
{
  "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": ""
}
```

#### <a id='429'></a> 429 (Too Many Requests. Quota for this service has been exhausted. Message must contain further details.)

```json
{
  "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": ""
}
```

#### <a id='500'></a> 500 (Internal Server Error. The server has run into an unexpected condition.)

```json
{
  "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": ""
}
```

#### <a id='503'></a> 503 (Service Unavailable. The server is currently unable to handle the request due to temporary overloading or maintenance. Typically, back end is unavailable.)

```json
{
  "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": ""
}
```