Messaging Token Validation API
https://api.swisscom.com/
Messaging APIs
Messaging cluster
This call will start the SMS Token validation process by sending a validation token to a 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 the user recieved the validation token by calling Validate SMS Token.
post /messaging/v1/tokenvalidation/
This call will start the SMS Token validation process by sending a validation token to a 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 the user recieved the validation token by calling Validate SMS Token.
Headers
- client_id: required (string)
Identifies the client by its client_id.
Example:
client_id: w3WYENmGgyW2QYfjGAx23DKnpHAVT57
- Content-Type: required (string)
Required header to receive JSON data back.
Example:
Content-Type: application/json
- Accept: required (string)
Required header to receive JSON data back.
Example:
Accept: application/json
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object" ,
"required": [
"to"
],
"properties": {
"to": {
"description": "Mobile number which should be verified. 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. ",
"type": "string"
},
"text": {
"description": "Appears as text in SMS. %TOKEN% is the placeholder for the generated token.",
"type": "string"
},
"tokenType": {
"description": "Describes what kind of token should be generated.",
"enum": [
"SHORT_NUMERIC",
"SHORT_ALPHANUMERIC",
"SHORT_SMALL_AND_CAPITAL",
"LONG_CRYPTIC"
]
},
"expireTime": {
"description": "Expire time of the token in seconds.",
"type": "integer",
"minimum": 0,
"maximum": 86400
},
"tokenLength": {
"description": "The size of the token. It is mandatory for all SHORT_* tokenTypes.",
"type": "integer",
"minimum": 1,
"maximum": 12
}
}
}
Example:
{
"to":"+41791544781",
"text":"Verification code: %TOKEN% \r\n Expires in 60 seconds.",
"tokenType":"SHORT_ALPHANUMERIC",
"expireTime":60,
"tokenLength":6
}
HTTP status code 201
HTTP status code 400
Bad Request. Invalid request.
Headers
- SCS-Request-ID: (string)
The request ID is used to trace API requests to the backends and correlate it with the corresponding response. It corresponds to the provided request ID in the request header. It will be generated by the API if non was provided.
Example:
myrequestid-123456789
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-03/schema",
"type": "object" ,
"properties": {
"uuid": {
"description": "The UUID of the client software",
"type": "string",
"required": false
},
"status": {
"description": "The http status code, e.g. 400",
"type": "string",
"required": true
},
"code": {
"description": "The error code, e.g. INVALID_PARAMETER",
"type": "string",
"required": true
},
"message": {
"description": "The error message",
"type": "string",
"required": true
},
"detail": {
"description": "The error detail",
"type": "string",
"required": false
}
}
}
Example:
{
"status": "400",
"code": "INVALID_REQUEST",
"message": "The request could not be understood due to malformed syntax. Correct the request syntax and try again.",
"detail": ""
}
HTTP status code 401
Unauthorized. No permission to resource or invalid api key.
Headers
- SCS-Request-ID: (string)
The request ID is used to trace API requests to the backends and correlate it with the corresponding response. It corresponds to the provided request ID in the request header. It will be generated by the API if non was provided.
Example:
myrequestid-123456789
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-03/schema",
"type": "object" ,
"properties": {
"uuid": {
"description": "The UUID of the client software",
"type": "string",
"required": false
},
"status": {
"description": "The http status code, e.g. 400",
"type": "string",
"required": true
},
"code": {
"description": "The error code, e.g. INVALID_PARAMETER",
"type": "string",
"required": true
},
"message": {
"description": "The error message",
"type": "string",
"required": true
},
"detail": {
"description": "The error detail",
"type": "string",
"required": false
}
}
}
Example:
{
"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": ""
}
HTTP status code 403
Forbidden. No permission for requested resource.
Headers
- SCS-Request-ID: (string)
The request ID is used to trace API requests to the backends and correlate it with the corresponding response. It corresponds to the provided request ID in the request header. It will be generated by the API if non was provided.
Example:
myrequestid-123456789
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-03/schema",
"type": "object" ,
"properties": {
"uuid": {
"description": "The UUID of the client software",
"type": "string",
"required": false
},
"status": {
"description": "The http status code, e.g. 400",
"type": "string",
"required": true
},
"code": {
"description": "The error code, e.g. INVALID_PARAMETER",
"type": "string",
"required": true
},
"message": {
"description": "The error message",
"type": "string",
"required": true
},
"detail": {
"description": "The error detail",
"type": "string",
"required": false
}
}
}
Example:
{
"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": ""
}
HTTP status code 404
Not Found. The server has not found anything matching the Request-URI.
Headers
- SCS-Request-ID: (string)
The request ID is used to trace API requests to the backends and correlate it with the corresponding response. It corresponds to the provided request ID in the request header. It will be generated by the API if non was provided.
Example:
myrequestid-123456789
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-03/schema",
"type": "object" ,
"properties": {
"uuid": {
"description": "The UUID of the client software",
"type": "string",
"required": false
},
"status": {
"description": "The http status code, e.g. 400",
"type": "string",
"required": true
},
"code": {
"description": "The error code, e.g. INVALID_PARAMETER",
"type": "string",
"required": true
},
"message": {
"description": "The error message",
"type": "string",
"required": true
},
"detail": {
"description": "The error detail",
"type": "string",
"required": false
}
}
}
Example:
{
"status": "404",
"code": "INVALID_REQUEST_RESOURCE",
"message": "The requested resource does not exist. Verify that the resource URI is correctly spelled.",
"detail": ""
}
HTTP status code 405
Method Not Allowed. The resource is not accessible via the given method. For example, the client sent a POST request to a resource that only implements GET.
Headers
- SCS-Request-ID: (string)
The request ID is used to trace API requests to the backends and correlate it with the corresponding response. It corresponds to the provided request ID in the request header. It will be generated by the API if non was provided.
Example:
myrequestid-123456789
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-03/schema",
"type": "object" ,
"properties": {
"uuid": {
"description": "The UUID of the client software",
"type": "string",
"required": false
},
"status": {
"description": "The http status code, e.g. 400",
"type": "string",
"required": true
},
"code": {
"description": "The error code, e.g. INVALID_PARAMETER",
"type": "string",
"required": true
},
"message": {
"description": "The error message",
"type": "string",
"required": true
},
"detail": {
"description": "The error detail",
"type": "string",
"required": false
}
}
}
Example:
{
"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": ""
}
HTTP status code 406
Invalid Header Accept. The provided Accept-type is not equal the accepted. E.g. application/zip instead of application/json.
Headers
- SCS-Request-ID: (string)
The request ID is used to trace API requests to the backends and correlate it with the corresponding response. It corresponds to the provided request ID in the request header. It will be generated by the API if non was provided.
Example:
myrequestid-123456789
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-03/schema",
"type": "object" ,
"properties": {
"uuid": {
"description": "The UUID of the client software",
"type": "string",
"required": false
},
"status": {
"description": "The http status code, e.g. 400",
"type": "string",
"required": true
},
"code": {
"description": "The error code, e.g. INVALID_PARAMETER",
"type": "string",
"required": true
},
"message": {
"description": "The error message",
"type": "string",
"required": true
},
"detail": {
"description": "The error detail",
"type": "string",
"required": false
}
}
}
Example:
{
"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": ""
}
HTTP status code 429
Too Many Requests. Quota for this service has been exhausted. Message must contain further details.
Headers
- SCS-Request-ID: (string)
The request ID is used to trace API requests to the backends and correlate it with the corresponding response. It corresponds to the provided request ID in the request header. It will be generated by the API if non was provided.
Example:
myrequestid-123456789
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-03/schema",
"type": "object" ,
"properties": {
"uuid": {
"description": "The UUID of the client software",
"type": "string",
"required": false
},
"status": {
"description": "The http status code, e.g. 400",
"type": "string",
"required": true
},
"code": {
"description": "The error code, e.g. INVALID_PARAMETER",
"type": "string",
"required": true
},
"message": {
"description": "The error message",
"type": "string",
"required": true
},
"detail": {
"description": "The error detail",
"type": "string",
"required": false
}
}
}
Example:
{
"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": ""
}
HTTP status code 500
Internal Server Error. Server is misconfigured, or generic error message.
Headers
- SCS-Request-ID: (string)
The request ID is used to trace API requests to the backends and correlate it with the corresponding response. It corresponds to the provided request ID in the request header. It will be generated by the API if non was provided.
Example:
myrequestid-123456789
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-03/schema",
"type": "object" ,
"properties": {
"uuid": {
"description": "The UUID of the client software",
"type": "string",
"required": false
},
"status": {
"description": "The http status code, e.g. 400",
"type": "string",
"required": true
},
"code": {
"description": "The error code, e.g. INVALID_PARAMETER",
"type": "string",
"required": true
},
"message": {
"description": "The error message",
"type": "string",
"required": true
},
"detail": {
"description": "The error detail",
"type": "string",
"required": false
}
}
}
Example:
{
"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": ""
}
HTTP status code 503
Service Unavailable. The server is currently unable to handle the request due to temporary overloading or maintenance. Typically back-end is unavailable.
Headers
- SCS-Request-ID: (string)
The request ID is used to trace API requests to the backends and correlate it with the corresponding response. It corresponds to the provided request ID in the request header. It will be generated by the API if non was provided.
Example:
myrequestid-123456789
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-03/schema",
"type": "object" ,
"properties": {
"uuid": {
"description": "The UUID of the client software",
"type": "string",
"required": false
},
"status": {
"description": "The http status code, e.g. 400",
"type": "string",
"required": true
},
"code": {
"description": "The error code, e.g. INVALID_PARAMETER",
"type": "string",
"required": true
},
"message": {
"description": "The error message",
"type": "string",
"required": true
},
"detail": {
"description": "The error detail",
"type": "string",
"required": false
}
}
}
Example:
{
"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": ""
}
Validate the token sent to the MSISDN number by the Send SMS Token call. This call is made after the Send SMS Token call to validate the token sent to the end user via SMS.
get /messaging/v1/tokenvalidation/{msisdn}/{token}
Validate the token sent to the MSISDN number by the Send SMS Token call. This call is made after the Send SMS Token call to validate the token sent to the end user via SMS.
URI Parameters
- msisdn: required (string)
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 (string)
Token to verify.
Headers
- client_id: required (string)
Identifies the client by its client_id.
Example:
client_id: w3WYENmGgyW2QYfjGAx23DKnpHAVT57
- Accept: required (string)
Required header to receive JSON data back.
Example:
Accept: application/json
HTTP status code 200
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object" ,
"required": [
"validation"
],
"properties": {
"validation": {
"description": "Whether token validation was successful",
"enum": [
"SUCCESS",
"FAILED"
]
}
}
}
Example:
{
"validation": "SUCCESS"
}
HTTP status code 400
Bad Request. Invalid request.
Headers
- SCS-Request-ID: (string)
The request ID is used to trace API requests to the backends and correlate it with the corresponding response. It corresponds to the provided request ID in the request header. It will be generated by the API if non was provided.
Example:
myrequestid-123456789
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-03/schema",
"type": "object" ,
"properties": {
"uuid": {
"description": "The UUID of the client software",
"type": "string",
"required": false
},
"status": {
"description": "The http status code, e.g. 400",
"type": "string",
"required": true
},
"code": {
"description": "The error code, e.g. INVALID_PARAMETER",
"type": "string",
"required": true
},
"message": {
"description": "The error message",
"type": "string",
"required": true
},
"detail": {
"description": "The error detail",
"type": "string",
"required": false
}
}
}
Example:
{
"status": "400",
"code": "INVALID_REQUEST",
"message": "The request could not be understood due to malformed syntax. Correct the request syntax and try again.",
"detail": ""
}
HTTP status code 401
Unauthorized. No permission to resource or invalid api key.
Headers
- SCS-Request-ID: (string)
The request ID is used to trace API requests to the backends and correlate it with the corresponding response. It corresponds to the provided request ID in the request header. It will be generated by the API if non was provided.
Example:
myrequestid-123456789
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-03/schema",
"type": "object" ,
"properties": {
"uuid": {
"description": "The UUID of the client software",
"type": "string",
"required": false
},
"status": {
"description": "The http status code, e.g. 400",
"type": "string",
"required": true
},
"code": {
"description": "The error code, e.g. INVALID_PARAMETER",
"type": "string",
"required": true
},
"message": {
"description": "The error message",
"type": "string",
"required": true
},
"detail": {
"description": "The error detail",
"type": "string",
"required": false
}
}
}
Example:
{
"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": ""
}
HTTP status code 403
Forbidden. No permission for requested resource.
Headers
- SCS-Request-ID: (string)
The request ID is used to trace API requests to the backends and correlate it with the corresponding response. It corresponds to the provided request ID in the request header. It will be generated by the API if non was provided.
Example:
myrequestid-123456789
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-03/schema",
"type": "object" ,
"properties": {
"uuid": {
"description": "The UUID of the client software",
"type": "string",
"required": false
},
"status": {
"description": "The http status code, e.g. 400",
"type": "string",
"required": true
},
"code": {
"description": "The error code, e.g. INVALID_PARAMETER",
"type": "string",
"required": true
},
"message": {
"description": "The error message",
"type": "string",
"required": true
},
"detail": {
"description": "The error detail",
"type": "string",
"required": false
}
}
}
Example:
{
"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": ""
}
HTTP status code 404
Not Found. The server has not found anything matching the Request-URI.
Headers
- SCS-Request-ID: (string)
The request ID is used to trace API requests to the backends and correlate it with the corresponding response. It corresponds to the provided request ID in the request header. It will be generated by the API if non was provided.
Example:
myrequestid-123456789
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-03/schema",
"type": "object" ,
"properties": {
"uuid": {
"description": "The UUID of the client software",
"type": "string",
"required": false
},
"status": {
"description": "The http status code, e.g. 400",
"type": "string",
"required": true
},
"code": {
"description": "The error code, e.g. INVALID_PARAMETER",
"type": "string",
"required": true
},
"message": {
"description": "The error message",
"type": "string",
"required": true
},
"detail": {
"description": "The error detail",
"type": "string",
"required": false
}
}
}
Example:
{
"status": "404",
"code": "INVALID_REQUEST_RESOURCE",
"message": "The requested resource does not exist. Verify that the resource URI is correctly spelled.",
"detail": ""
}
HTTP status code 405
Method Not Allowed. The resource is not accessible via the given method. For example, the client sent a POST request to a resource that only implements GET.
Headers
- SCS-Request-ID: (string)
The request ID is used to trace API requests to the backends and correlate it with the corresponding response. It corresponds to the provided request ID in the request header. It will be generated by the API if non was provided.
Example:
myrequestid-123456789
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-03/schema",
"type": "object" ,
"properties": {
"uuid": {
"description": "The UUID of the client software",
"type": "string",
"required": false
},
"status": {
"description": "The http status code, e.g. 400",
"type": "string",
"required": true
},
"code": {
"description": "The error code, e.g. INVALID_PARAMETER",
"type": "string",
"required": true
},
"message": {
"description": "The error message",
"type": "string",
"required": true
},
"detail": {
"description": "The error detail",
"type": "string",
"required": false
}
}
}
Example:
{
"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": ""
}
HTTP status code 406
Invalid Header Accept. The provided Accept-type is not equal the accepted. E.g. application/zip instead of application/json.
Headers
- SCS-Request-ID: (string)
The request ID is used to trace API requests to the backends and correlate it with the corresponding response. It corresponds to the provided request ID in the request header. It will be generated by the API if non was provided.
Example:
myrequestid-123456789
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-03/schema",
"type": "object" ,
"properties": {
"uuid": {
"description": "The UUID of the client software",
"type": "string",
"required": false
},
"status": {
"description": "The http status code, e.g. 400",
"type": "string",
"required": true
},
"code": {
"description": "The error code, e.g. INVALID_PARAMETER",
"type": "string",
"required": true
},
"message": {
"description": "The error message",
"type": "string",
"required": true
},
"detail": {
"description": "The error detail",
"type": "string",
"required": false
}
}
}
Example:
{
"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": ""
}
HTTP status code 429
Too Many Requests. Quota for this service has been exhausted. Message must contain further details.
Headers
- SCS-Request-ID: (string)
The request ID is used to trace API requests to the backends and correlate it with the corresponding response. It corresponds to the provided request ID in the request header. It will be generated by the API if non was provided.
Example:
myrequestid-123456789
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-03/schema",
"type": "object" ,
"properties": {
"uuid": {
"description": "The UUID of the client software",
"type": "string",
"required": false
},
"status": {
"description": "The http status code, e.g. 400",
"type": "string",
"required": true
},
"code": {
"description": "The error code, e.g. INVALID_PARAMETER",
"type": "string",
"required": true
},
"message": {
"description": "The error message",
"type": "string",
"required": true
},
"detail": {
"description": "The error detail",
"type": "string",
"required": false
}
}
}
Example:
{
"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": ""
}
HTTP status code 500
Internal Server Error. Server is misconfigured, or generic error message.
Headers
- SCS-Request-ID: (string)
The request ID is used to trace API requests to the backends and correlate it with the corresponding response. It corresponds to the provided request ID in the request header. It will be generated by the API if non was provided.
Example:
myrequestid-123456789
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-03/schema",
"type": "object" ,
"properties": {
"uuid": {
"description": "The UUID of the client software",
"type": "string",
"required": false
},
"status": {
"description": "The http status code, e.g. 400",
"type": "string",
"required": true
},
"code": {
"description": "The error code, e.g. INVALID_PARAMETER",
"type": "string",
"required": true
},
"message": {
"description": "The error message",
"type": "string",
"required": true
},
"detail": {
"description": "The error detail",
"type": "string",
"required": false
}
}
}
Example:
{
"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": ""
}
HTTP status code 503
Service Unavailable. The server is currently unable to handle the request due to temporary overloading or maintenance. Typically back-end is unavailable.
Headers
- SCS-Request-ID: (string)
The request ID is used to trace API requests to the backends and correlate it with the corresponding response. It corresponds to the provided request ID in the request header. It will be generated by the API if non was provided.
Example:
myrequestid-123456789
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-03/schema",
"type": "object" ,
"properties": {
"uuid": {
"description": "The UUID of the client software",
"type": "string",
"required": false
},
"status": {
"description": "The http status code, e.g. 400",
"type": "string",
"required": true
},
"code": {
"description": "The error code, e.g. INVALID_PARAMETER",
"type": "string",
"required": true
},
"message": {
"description": "The error message",
"type": "string",
"required": true
},
"detail": {
"description": "The error detail",
"type": "string",
"required": false
}
}
}
Example:
{
"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": ""
}