SMPP Documentation
SMPP
Welcome to the Silverstreet SMPP API!
The Silverstreet SMPP API offers an SMPP SERVER connection with the Silverstreet gateway using our standard authentication system and error codes.
Introduction
Terminology
Term | Description |
---|---|
Mobile Originated (MO) |
A message sent (originating) from a mobile handset to an application via Silverstreet. |
Mobile Terminated (MT) |
A message sent from an application to (terminating on) a mobile handset via Silverstreet. |
Customer |
A registered Silverstreet customer utilising the Silverstreet API for message delivery and receipt. |
Destination Address |
This is the number to which the mobile user sent the message. |
Source Address |
The from address that appears on the user’s handset. Also known as the originating number, MSISDN or originator ID. |
Shortcode |
A short number which is common across all the operators for a specific region. |
Subscriber |
The handset that will be paying for the premium rate MT service. |
Gateway |
A network operator, third party or Silverstreet’s own short message service centre (SMSC). |
SMPP CLIENT |
The initiating party of the SMPP connection (Called ESME in SMPP v3.4 Protocol Specification) |
SMPP SERVER |
The responding party of the SMPP connection to the SMPP CLIENT (Called SMSC in SMPP v3.4) |
UDH |
User Data Header |
Recipient
|
End user, handset that belongs to the MSISDN. |
Registration
Customers in need of high security can use our SMPP gateway over SSL (Secure Socket Layer) for SMS delivery. SSL is the same proven encryption layer used by online banking services, so your message data is safely encrypted while sent over public Internet. Customer are initially restricted to two binds per account they can make to SMPP SERVERs.
Item | Description |
---|---|
URL |
smpp.silverstreet.com |
Port |
2675 |
SSL Port |
8445 |
Operation
We are SMPP 3.4 protocol compliant, for standard SMS, Number Lookup and SMS Mobile Originated (MO) functionality.
The following lists the PDU (Protocol Data Unit) commands supported by the Silverstreet SMPP SERVERs.
Client-to-Server | Server-to-Client |
---|---|
Bind Operations | |
BIND_TRANSMITTER |
BIND_TRANSMITTER_RESP |
BIND_RECEIVER |
BIND_RECEIVER_RESP |
BIND_TRANSCEIVER |
BIND_TRANSCEIVER_RESP |
UNBIND |
UNBIND_RESP (Optional) |
Message and Delivery Report Operations | |
SUBMIT_SM |
SUBMIT_SM_RESP |
DELIVER_SM_RESP |
DELIVER_SM |
Keep Alive Operations | |
ENQUIRE_LINK |
ENQUIRE_LINK_RESP |
Connecting via SMPP requires a detailed understanding of the SMPP Protocol. A more detailed understanding of SMPP 3.4 specification is available from smsforum.net and smpp.org . The SMPP v3.4 specification can be downloaded here
Bind Operation
Establishing network connection or bind operation connects your client software to the server.
here are 2 options available when binding to Silverstreet. Binds can be made using the TX transmitter and RX receiver pair from SMPP 3.3, or bind using the TRX transceiver mode new to SMPP 3.4.
BIND PDU types supported by Silverstreet’s SMPP SERVERs:
SMPP Action | Description |
---|---|
BIND_TRANSMITTER |
TX (Transmitter), SMPP CLIENT sends MT messages through this bind. MO messages not supported through this bind. |
BIND_TRANSMITTER_RESP |
SMPP SERVER sends response of bind request. |
BIND_RECEIVER |
RX (Receiver),SMPP CLIENT receives delivery notifications and MO messages through this bind. MT messages not supported through this bind. |
BIND_RECEIVER_RESP |
SMPP SERVER sends response of bind request. |
BIND_TRANSCEIVER |
TRX (Transceiver) availble from SMPP 3.4 and above, allows SMPP CLIENT to send MT messages and receive MO messages as well as delivery notifications to and from Silverstreet’s SMPP SERVERs. |
BIND_TRANSCEIVER_RESP |
Availble from SMPP 3.4 and above, SMPP SERVER sends response of bind request. |
The following parameters should be used for connecting to Silverstreet’s SMPP SERVERs.
Item | Restriction | Description |
---|---|---|
system_id |
Maximum of 15 characters. | Your Silverstreet account username. This parameter is used to identify a SMPP CLIENT of Silverstreet at bind time. |
password |
Maximum of 8 characters. | Your Silverstreet account password. Used by Silverstreet to authenticate the identity of the binding SMPP CLIENT. |
system_type |
Maximum of 12 characters. | Optional,used to categorise the type of SMPP CLIENT binding to Silverstreet. |
Unbind Operation
Disonnect network connection or unbind operation disconnect your client software to the server. This operation is optional as SMPP connection is always connected.
SMPP Action | Description |
---|---|
UNBIND |
Initiated by SMPP CLIENT, to request for disconnection from the Silverstreet SMPP SERVERs. |
UNBIND_RESP |
(Optional) Used by Silverstreet SMPP SERVERs to reply to the unbind request initiated by the SMPP CLIENT. |
Keep Alive
SMPP is always connected with keep alive setting.
SMPP Action | Description | |
---|---|---|
ENQUIRE_LINK |
Initiated by the SMPP CLIENT to check the communication link between the SMPP CLIENT and Silverstreet’s SMPP SERVERs. | ENQUIRE_LINK |
ENQUIRE_LINK_RESP |
Issued by Silverstreet SMPP SERVERs as a response to an ENQUIRE_LINK request. |
Submit Message
This operation is used by the SMPP CLIENT to submit a message to Silverstreet’s SMPP SERVERs.
Item | Description |
---|---|
SUBMIT_SM |
Initiated by the SMPP CLIENT for message sending. |
SUBMIT_SM_RESP |
Sent by Silverstreet’s SMPP SERVERs to the SMPP CLIENT, to respond to the SMPP CLIENT’s SUBMIT_SM, including a Message ID. |
TON and NPI
TON and NPI Settings. The following TON and NPI values are defined:
Type | TON | NPI | ||
---|---|---|---|---|
Value (Binary) | Value (Decimal) | Value (Binary) | Value (Decimal) | |
Source Address | source_addr_ton | source_addr_npi | ||
National | 00000010 | 2 | 00000001 | 1 |
International | 00000001 | 1 | 00000001 | 1 |
Alphanumeric | 00000101 | 5 | 00000000 | 0 |
Destination Address | dest_addr_ton | dest_addr_npi | ||
ALL | 00000001 | 1 | 00000001 | 1 |
source_addr
Accounts with fixed source addresses: This field may be set to NULL to allow Silverstreet’s SMPP SERVERs to default the source address on the submitted message, based on the fixed source address of the affected network (this is requested by Customers or Account Managers).
Accounts with dynamic source addresses: This field may be set to NULL to allow Silverstreet’s SMPP SERVERs to set the source address of the submitted message by default, to 13013.
esm_class
Used to indicate special message attributes associated with the message. Usually used when a SMPP CLIENT sends concatenated (long) messages. Example: esm_class = 64 or 67 indicates the message should contain an UDH value.
data_coding
This parameter varies based on what message type is sent.
Value | Description |
---|---|
0 |
SMSC default alphabet |
4 |
Binary message (8-bit binary) |
8 |
Unicode message (UCS-2) |
The following table describes the values that need to be set for the esm_class and data_coding parameters, depending on what type of content is to be sent.
Message type | esm_class (Binary) | data_coding (Binary) |
---|---|---|
Text |
00000000 | 00000000 |
Flash |
00000000 | 11110000 |
Unicode |
00000000 | 00001000 |
Binary |
00000000 | 00000100 |
Concatenated (long) SMS |
01000000 or 01000011 | (Refer to the above four message types) |
registered_delivery
Value | Description |
---|---|
0 |
No delivery notification requested |
1 |
Requesting for final delivery notifications |
17 |
Requesting for intermediate and final delivery notifications |
message_id
This field contains a unique message identifier reference which is assigned by Silverstreet’s SMPP SERVERs to each submitted message PDU, SUBMIT_SM. Returned by Silverstreet’s SMPP SERVERs in SUBMIT_SM_RESP and DELIVER_SM_RESP PDUs. Example: 2.19693.4f8656ef7d3067.51000940.1921633333 (Maximum length provided by Silverstreet’s SMPP SERVERs is 42 characters - VARCHAR)
validity_period
Messages will be retried for delivery for the duration of the validity period set – after which EXPIRED status will be returned (Gateway timeout dependent). If validity_period is not set, it will be defaulted to 72 hours.
Delivery Notification
If the registered_delivery parameter is set to 1 in the original SUBMIT_SM PDU, a DELIVER_SM containing the delivery notification will be sent to the SMPP CLIENT when the message has reached the final status. If the registered_delivery parameter value is set to 17, both final and intermediate delivery notifications will be sent to the SMPP CLIENT.
This operation is issued to send Delivery Notifications to a SMPP CLIENT.
SMPP Action | Description |
---|---|
DELIVER_SM |
Initiated by Silverstreet’s SMPP SERVERs to the SMPP CLIENT for message delivery notification. |
DELIVER_SM_RESP |
Used by SMPP CLIENT to respond to the DELIVER_SM from Silverstreet‘s SMPP SERVERs, to acknowledge receipt of DELIVER_SM. |
Example: The format of the delivery notification is as follows:
id: 2.19693.4f8656ef7d3067.51000940.1921633333 sub:001 dlvrd:001 submit date:1210251406 done date: 1210251408
stat:DELIVRD err:000 text:
The optional field receipted_message_id contains a duplication of the Message ID contained in the short_message parameter. Intermediate delivery notifications are returned by Silverstreet’s SMPP SERVERs and the SMPP CLIENT has to be adapted to this. Silverstreet’s SMPP SERVERs include an optional parameter in the delivery notification, 0X1400, which contains the current MCC/MNC of the MSISDN. This value appears after the text field of the short_message parameter. Via this parameter our Customers can determine as to whether the MSISDN is ported or not. The SMPP CLIENT has to be adapted to this.
Value | Description |
---|---|
id |
The Message ID of the delivery notification - to be mapped to original message ID in the submit_sm_resp PDU. Maximum length: 42 characters – VARCHAR |
sub |
Number of submitted messages – This will always be 001 as submit_multi is not supported. |
dlvrd |
Number of delivered messages - This will always be 001 as submit_multi is not supported. |
submit date |
Message submission date |
done date |
Message delivery date (SMSC timestamp) |
stat |
The status of the delivery notification (maximum 7 characters) |
err |
The error code of the delivery notification for failed message delivery in hexadecimal representation |
text |
Contains additional information, appended from optional parameter(s) to the short_message parameter of delivery notifications from Silverstreet. For example: Network code (MCC/MNC) and message ID. |
Mobile Originated
Mobile Originated (DELIVER_SM OPERATION), When a SMS MO is to be sent from the Silverstreet system to the client, a DELIVER_SM containing the message will be sent to the SMPP CLIENT.
This operation is issued to send Delivery Notifications to a SMPP CLIENT.
SMPP Action | Description |
---|---|
DELIVER_SM |
Initiated by Silverstreet’s SMPP SERVERs to the SMPP CLIENT for SMS MO notification. |
DELIVER_SM_RESP |
Used by SMPP CLIENT to respond to the DELIVER_SM from Silverstreet‘s SMPP SERVERs, to acknowledge receipt of DELIVER_SM. |
Number Lookup Query
To perform a Number Lookup query, a SUBMIT_SM PDU must be send.
Destination address will be used for the number to be looked up. Validity period can be set to override the default validity. The default validity for streaming accounts is 5 minutes and for bulk accounts 72 hours. All other fields are ignored. This includes e.g. the registered delivery field as always a result is send back to the customer.
SMPP Action | Description |
---|---|
SUBMIT_SM |
Initiated by the SMPP CLIENT for Number Lookup. Set the field ‘service_type’ to ‘hlr’. |
SUBMIT_SM_RESP |
Sent by Silverstreet’s SMPP SERVERs to the SMPP CLIENT, to respond to the SMPP CLIENT’s SUBMIT_SM, including a Message ID. |
Number Lookup Result
For Number Lookup always a result is send back. Regardless of the value of the registered_delivery parameter.
This operation is issued to send Number Lookup results to a SMPP CLIENT.
SMPP Action | Description |
---|---|
DELIVER_SM |
Initiated by Silverstreet’s SMPP SERVERs to the SMPP CLIENT for a Number Lookup result. The field ‘service_type’ is set to ‘hlr’. |
DELIVER_SM_RESP |
Used by SMPP CLIENT to respond to the DELIVER_SM from Silverstreet‘s SMPP SERVERs, to acknowledge receipt of DELIVER_SM. |
Example: The format of the Number Lookup result is as follows:
id: 2.19693.4f8656ef7d3067.51000940.1921633333 sub:001 dlvrd:001 submit
date:1210251406 done date: 1210251408 stat:DELIVRD err:000 text:
Value | Description |
---|---|
id |
The Message ID of the Number Lookup result - to be mapped to original message ID in the submit_sm_resp PDU. Maximum length: 42 characters – VARCHAR |
sub |
Number of submitted Number Lookup queries – This will always be 001 as submit_multi is not supported. |
dlvrd |
Number of delivered Number Lookup queries - This will always be 001 as submit_multi is not supported. |
submit date |
Number Lookup submission date. |
done date |
Number Lookup result date (SMSC timestamp) |
stat |
The status of the Number Lookup result (maximum 7 characters) |
err |
The error code of Number Lookup result for failed queries in hexadecimal representation. |
text |
Always empty. |
Depending on the agreements made with Silverstreet and if the information is available, you will receive one or more of the following parameters as a TLV field:
Value | Description |
---|---|
0x1400 |
The network code of the found operator. The network code is build up out of the MCC and MNC. Example: 20404 |
0x1401 |
The name of the found operator preceded by the country name. Example: (Netherlands) Vodafone |
0x1402 |
The two-digit ISO country code of the country of the found operator. Example: nl |
0x1403 |
The MSC the number is currently signed into. |
0x1404 |
The IMSI of the number. |
Appendix
Appendixes gives extra information about SMPP
Delivery Status
The following are statuses returned by Silverstreet’s SMPP SERVERs within the deliver_sm PDU, in the ‘stat’ field.
Value | Message Status | Description |
---|---|---|
DELIVRD |
Delivered | Delivered to the Gateway or network (and subsequently delivered to the recipient). |
REJECTD |
Rejected | An error occurred delivering the message to the handset – and rejected by the Gateway or Destination Operator. |
EXPIRED |
Expired | Message has expired, generally due to validity period expiry or specifically due to Gateway related issues. |
ENROUTE |
Enroute | Message is being retried at the Gateway’s end. |
BUFFERD |
Buffered | Message is queued by the Gateway to be sent |
ACCEPTD |
Accepted | Message sent to the Gateway or Destination Operator (but not yet delivered to the recipient). |
UNDELIV |
Undeliverable | Message is unable to be delivered to the recipient. |
DELETED |
Deleted | Message is deleted by the Gateway due to specific reasons at the Gateway’s end. |
UNKNOWN |
Unknown | The message status Is unknown. Status is none of the above. |
Error Codes
The following lists the error messages generated by the Silverstreet SMPP SERVERs. These error codes are included in both intermediate and final delivery notifications. For further information about these error codes and vocabulary, please refer to the GSM protocol specification.
Reason Code | Description |
---|---|
0 |
No error |
1 |
Absent subscriber (network cannot contact recipient) |
2 |
Handset memory exceeded |
3 |
Equipment protocol error |
4 |
Equipment not equipped with short-message capability |
5 |
Unknown service centre (unknown Destination Operator) |
6 |
Service centre congestion (congestion at Destination Operator) |
7 |
Invalid SME (Short Message Entity) address |
8 |
Subscriber is not a SC subscriber (Number belongs to a different destination network but HLR is not updated) |
9 |
Unknown subscriber (Recipient number is unknown in the HLR) |
10 |
Illegal subscriber (The mobile station failed authentication) |
11 |
Teleservice not provisioned (Mobile subscription identified by the MSISDN number does not include short message services) |
12 |
Illegal equipment (Recipient number check failed, blacklisted or not whitelisted) |
13 |
Call barred (Operator barred the recipient number) |
14 |
Facility not supported (a Gateway entity does not support MT short message service) |
15 |
Recipient busy for MT short message |
16 |
System failure |
17 |
Message waiting list at HLR is full |
18 |
Data missing |
19 |
Unexpected data value |
20 |
Resource limitation at Recipient or Destination Operator |
21 |
TCAP error (Duplicate invoke ID) |
22 |
TCAP error (Not supported service) |
23 |
TCAP error (Mistyped parameter) |
24 |
TCAP error (Resource Limitation) |
25 |
TCAP error (TCAP initiating release) |
26 |
TCAP error (Unexpected response from peer) |
27 |
TCAP error (Service completion failure) |
28 |
TCAP error (No response from peer) |
29 |
TCAP error (Invalid response received) |
30 |
Unidentified recipient |
31 |
Service temporary not available |
32 |
Illegal error code |
33 |
Network timeout |
34 |
Operation Barred (From the Destination Operator) |
35 |
Delivery failed |
36 |
Error in mobile station |
37 |
PLMN system failure |
38 |
HLR system failure |
39 |
VLR system failure |
40 |
Controlling MSC failure (Error in the MSC where the user is located) |
41 |
Visited MSC failure (Error in the visited MSC) |
42 |
MNP other operator not allowed (MSISDN is ported, delivery via this SMSC not permitted) |
43 |
Subscriber temporarily unreachable (While roaming) |
44 |
Message store busy |
45 |
SME Interface busy |
46 |
Closed user group reject |
47 |
Network failure |
48 |
Deferred Delivery (Message has not been delivered and is part of a deferred delivery schedule) |
49 |
Error getting route |
50 |
Insufficient credit |
51 |
Rejected Destination |
52 |
Rejected Unknown Reason |
53 |
Rejected due to routing issue |
54 |
Rejected due to blocking issue |
55 |
Rejected due to no price |
56 |
Rejected due to not enough credits |
57 |
Rejected due to spam filter |
58 |
Rejected due to flooding |
59 |
UNKNOWN TCType,SMS |
60 |
UNKNOWN TCType,SRI |
61 |
UNKNOWN |
62 |
Failure due to submission towards AA19 destination |
63 |
Sent to SME but unable to confirm |
64 |
Replaced at the SMSC |
65 |
Quality service not available |
66 |
Error in SMSC |
67 |
Rejected by operator due to validity period expiry |
68 |
Intermediate state notification that the message has not yet been delivered due to a phone related problem but is being retried. |
69 |
Cannot determine whether this message has been delivered or has failed due to lack of final delivery state information from the operator. |
70 |
Specific content is not permitted on the network/shortcode |
71 |
Subscriber cannot receive adult content because of a parental lock |
72 |
Failure due to ported combinations being unreachable. |
73 |
Roaming subscriber. |
74 |
Failure due to ported combinations being blocked for client (Client has been blacklisted from the ported destination). |
75 |
Abort from HLR |
76 |
Source address is blacklisted or not supported |
77 |
Operation barred |
78 |
Facility not provided |
79 |
Invalid absolute validity period |
80 |
SMS centre received |
81 |
Invalid PDU format |
82 |
Local Cancel (Temporary problem/Lost reach) |
83 |
Rejected due to duplicate |
84 |
Maximum Connection Reached |
85 |
Information Not Available |
86 |
Message waiting list full |
87 |
Short Term Denial |
999 |
If the SMSC does not return error codes to use on permanently or temporarily failed messages, then the Silverstreet SMPP SERVERs will return the hexadecimal error code 03E7 (999 in decimal) to the SMPP CLIENT. |
HTTP API Documentation
Introduction
Welcome to the Silverstreet HTTP API!
This document provides developers with instructions for integrating Silverstreet HTTP API. Silverstreet HTTP API supports both HTTPS and HTTPS.
SSL | Host |
---|---|
no | http://api.silverstreet.com |
yes | https://api.silverstreet.com |
SMS MT
This document provides developers with instructions for integrating Silverstreet SMS-MT services into varios solutions using the Silverstreet SMS MT HTTP API. The Silverstreet SMS-MT HTTP API supports GET and HTTP POST via both HTTP and HTTPS.
The maximum length of a HTTP GET request is 4.096 bytes. When you send a SMS to multiple destinations you have to consider this maximum length. When you exceed the length you have to use HTTP POST.
Properties
Mandatory parameter must be included upon submission.
Property | Type | Description |
---|---|---|
username |
String | The username to connect to the API.The maximum length is 20 characters. |
password |
String | The password to connect to the API.The maximum length is 20 characters. |
destination |
String | Comma separated the destination(s) of the SMS. There is no limit on the maximum destinations which can be specified. The destination must be in international format, without leading 00 or +. (Example: ) |
sender |
String | The sender of the SMS. The maximum length of the sender is 16 for numeric (including +) and 11 for alphanumeric. Allowed characters are a-z, A-Z and 0-9. |
body |
String | The body of the SMS. For text SMS (bodytype 1 and 2) only GSM 7- bit alphabet is allowed.
For Unicode or binary SMS only
hex- numeric is allowed. The maximum length of the body is:
|
Optional parameter can be included upon submission.
Property | Type | Description |
---|---|---|
bodytype |
Integer | The type of the body of the SMS. Possible values are:
|
reference |
String | A unique reference for the SMS. The reference will be returned with the delivery report. When multiple destinations are specified they will have the same reference. The maximum length of the reference can be 30 characters and is in UTF-8. This field is mandatory when you want to receive delivery reports. |
dlr |
Integer | If a delivery reports should be returned or not. When set to 0 no delivery reports will be returned, when set 1 to delivery reports will be returned. |
udh |
Integer | The User Data Header. Cannot be used when the concat parameter is set. The UDH is used for sending binary SMS or concatenated text SMS. A correct UDH contains out of hex-numeric characters. For more information about the UDH, check the GSM 03.40 specification. |
validity |
Integer | The relative validity of the SMS in minutes. If not specified a default validity will be used by the system. The default validity SMS is 3 days. The maximum validity is 7 days. |
service |
Integer | SMS service tag to be used as billing reference on statistics and invoice. The maximum length of the service can be 30 characters and is in UTF-8. |
pid |
Integer | Protocol identifier. For more information about the PID, check the GSM 03.40 specification. |
dcs |
Integer | Data coding scheme. For more information about the DCS, check the GSM 03.38 specification. |
concat |
Integer | Split the body into multiple parts. Allowed value is 1. For bodytype 1 (text) and 2 (flash) the system will split the messages up into parts of 153 characters each. For bodytype 4 (Unicode) the system will split the message up into parts of 67 characters. Bodytype 3 (binary) is not supported for this functionality. The system will automatically generate a UDH for each message part. When concat is used no UDH can be set. The body will be split into maximum 9 parts. |
senderton |
Integer | With the sender TON and sender NPI parameter you can specify the sender type. The most
common values are:
|
sendernpi |
Integer | See sender TON parameter for more information. |
Submit SMS MT
When submitting a simple SMS, the API will split up long SMS into multiple parts as an SMS has a maximum length. Check our tutorial 'Concatenated/long SMS' for more information on concatenated SMS.
HTTP Endpoint
GET
GET /send.php
You can simply use the GET method to submit the SMS with sample below
http://api.silverstreet.com/send.php?username=<username>&password=<password>&destination=&sender=hello&body=hello%20world
POST
POST /send.php
Submit a simple SMS:
curl -X POST https://api.silverstreet.com/send.php \
-d 'username=<username>'\
-d 'password=<password>'\
-d 'sender=hello'\
-d 'body=hello%20world.'\
-d 'destination=,'
The response will look like this:
01
Response Code
When the SMS is sent, the system will give a response to the call. The returned response code can have the following values:
Code | Description |
---|---|
01 |
The SMS is successfully accepted by the system. It doesn’t mean that the SMS is successfully delivered to the handset. The delivery result will be reported via a delivery report. |
100 |
Parameter(s) are missing. |
110 |
Bad combination of parameters. |
120 |
Invalid parameter(s). |
130 |
Insufficient credits for the account. |
SMS MT Callback URL
After a SMS is successfully received by the system, a result will be send back to you. This will be via the callback URL for your account. When for a SMS multiple destinations are specified, for each destination a separate delivery report will be send.
The delivery reports will be send by the system with source IP address 195.88.18.2
. This IP
should be whitelisted on
your side. you can set your callback URL in Account settings of portal.
Your system has to respond with OK
when a delivery result is send to your system. In case a
different response is
given the URL will be retried. A URL will be retried maximum 25 times with an increasing interval.
Properties
The following parameters will be returned:
Property | Description |
---|---|
REFERENCE |
The reference specified when sending the SMS to the system. |
STATUS |
The status of the SMS. The status can be one of the following values
|
REASON |
When the status is not ‘Delivered’, a reason code will be returned. |
DESTINATION |
The recipient number the SMS was sent to. |
TIMESTAMP |
The timestamp the SMS was delivered at the destination. The timestamp is in the format YYYYMMDDHHIISS in UTC. |
OPERATOR |
The network code of the operator of the mobile number. |
Example
http://www.yoururl.com/callback?
REFERENCE=12345678&STATUS=Delivered&REASON=&
DESTINATION=&TIMESTAMP=&
OPERATOR=
When the parameter ‘concat’ is set when the message is send to the Silverstreet platform, the following parameters are also returned:
Property | Description |
---|---|
PART_NUMBER |
The part number of the concatenated message. |
PARTS_TOTAL |
Total number of parts of the concatenated message. |
Example with concat set
http://www.yoururl.com/callback?
REFERENCE=12345678&STATUS=Delivered&REASON=&
DESTINATION=&TIMESTAMP=&
OPERATOR=&PART_NUMBER=1&PARTS_TOTAL=3
Encoding
This encoding is reference for the GET submission.
Character | Encoding | Character | Encoding | Character | Encoding | Character | Encoding |
---|---|---|---|---|---|---|---|
Δ | %10 | : | %3A | ^ | %5E | ¥ | %A5 |
Φ | %12 | ; | %3B | _ | %5F | § | %A7 |
Γ | %13 | < | %3C | a | %61 | ¿ | %BF |
Λ | %14 | = | %3D | b | %62 | À | %C0 |
Ω | %15 | > | %3E | c | %63 | Ä | %C4 |
Π | %16 | ? | %3F | d | %64 | Å | %C5 |
Ψ | %17 | @ | %40 | e | %65 | Æ | %C6 |
Σ | %18 | A | %41 | f | %66 | Ç | %C7 |
Θ | %19 | B | %42 | g | %67 | È | %C8 |
Ξ | %1A | C | %43 | h | %68 | É | %C9 |
Space |
%20 | D | %44 | i | %69 | Ì | %CC |
! | %21 | E | %45 | j | %6A | Ñ | %D1 |
" | %22 | F | %46 | k | %6B | Ò | %D2 |
# | %23 | G | %47 | l | %6C | Ö | %D6 |
$ | %24 | H | %48 | m | %6D | Ø | %D8 |
% | %25 | I | %49 | n | %6E | Ù | %D9 |
& | %26 | J | %4A | o | %6F | Ü | %DC |
' | %27 | K | %4B | p | %70 | ß | %DF |
( | %28 | L | %4C | q | %71 | ä | %E4 |
) | %29 | M | %4D | r | %72 | å | %E5 |
* | %2A | N | %4E | s | %73 | æ | %E6 |
+ | %2B | O | %4F | t | %74 | é | %E9 |
, | %2C | P | %50 | u | %75 | ñ | %F1 |
- | %2D | Q | %51 | v | %76 | ö | %F6 |
. | %2E | R | %52 | w | %77 | ø | %F8 |
/ | %2F | S | %53 | x | %78 | ü | %FC |
0 | %30 | T | %54 | y | %79 | Line Feed, New Line |
%0A |
1 | %31 | U | %55 | z | %7A | ESC |
%1B |
2 | %32 | V | %56 | { | %7B | Form Feed |
%0C |
3 | %33 | W | %57 | | | %7C | CR |
%0D |
4 | %34 | X | %58 | } | %7D | CR2 |
|
5 | %35 | Y | %59 | ~ | %7E | SS22 |
|
6 | %36 | Z | %5A | € | %80 | ||
7 | %37 | [ | %5B | ¡ | %A1 | ||
8 | %38 | \ | %5C | £ | %A3 | ||
9 | %39 | ] | %5D | ¤ | %A4 |
CR is invisible character, FF should act the same as LF. Below are color legend.
Color | Description |
---|---|
Character | You should encode it. |
Character | You can send as it is without URL encode it. |
Character | You must encode it or data may come out unexpectedly. |
Character | Reserved URI character, you should always URL encode those. |
Character | Not supported character. Not normal keyboard character and not visible. |
Character | Those available in windows 1252, we will be using same encode. For characters out of the scope, we will use GSM3.38 encode for URL encode. |
Number Lookup
This document provides developers with instructions for integrating Silverstreet Number Lookup services into varios solutions using the Silverstreet Number Lookup HTTP API. The Silverstreet SMS-MT HTTP API supports GET and HTTP POST via both HTTP and HTTPS.
Properties
Mandatory parameter must be included upon submission.
Property | Type | Description |
---|---|---|
username |
String | The username to connect to the API.The maximum length is 20 characters. |
password |
String | The password to connect to the API.The maximum length is 20 characters. |
number |
String | Comma separated the destination(s) of the SMS. There is no limit on the maximum destinations which can be specified. The destination must be in international format, without leading 00 or +. (Example: ) |
Optional parameter can be included upon submission.
Property | Type | Description |
---|---|---|
reference |
String | A unique reference for the number lookup query. The reference will be returned with the number lookup result. When multiple numbers are specified they will have the same reference. The maximum length of the reference can be 30 characters and is in UTF-8. |
validity |
Integer | The relative validity of the number lookup query in minutes. If not specified a default validity will be used by the system. The default validity for streaming queries is 5 minutes and for bulk queries 3 days. The maximum validity is 7 days. |
url |
String | This will overrule the default callback URL for the account. A valid URL shall be specified. The URL can be HTTP and HTTPS. Example: http://www.yourdomain.com/callback |
email |
String | This will overrule the default callback email for the account. A valid email shall be specified. Example: name@yourdomain.com |
noresult |
- | If set, the result will not be returned. No value have to be specified. |
Submit Query
HTTP Endpoint
GET
GET /numberlookup.php
You can simply use the GET method to submit the number lookup query with sample below
http://api.silverstreet.com/numberlookup.php?username=<username>&password=<password>&destination=&sender=hello&body=hello%20world
POST
POST /numberlookup.php
Submit a simple query:
curl -X POST https://api.silverstreet.com/numberlookup.php \
-d 'username=<username>'\
-d 'password=<password>'\
-d 'number=,'
The response will look like this:
01
Response Code
When the number lookup query is performed, the system will give a response to the call. The returned response code can have the following values:
Code | Description |
---|---|
01 |
The query is successfully accepted by the system. |
100 |
Parameter(s) are missing. The missing parameters will be listed. |
110 |
Bad combination of parameters. |
120 |
Invalid parameter(s). The invalid parameters will be listed. |
130 |
Insufficient credits for the account. |
140 |
The IP you are using to call the number lookup API is not allowed for the account. |
150 |
Number lookup is not allowed for the account. |
160 |
Both url and email are specified where only one of the two can be
specified.
|
170 |
The noresult parameter is used but has an incorrect value.
|
180 |
The noresult parameter is used and also the url or
email parameter which is not allowed.
|
Result Callback
After a number lookup query is successfully received by the system, a result will be send back to you. This can either be via a callback URL or email. When for a number lookup query multiple numbers are specified, for each number a separate result will be send. When you have specified the no result option, you will not receive the result.
By URL
The delivery reports will be send by the system with source IP address 195.88.18.2
. This IP
should be whitelisted on
your side. you can set your callback URL in Account settings of portal.
Your call back URL has to respond with OK
when a delivery result is send to your system. In
case a
different response is
given the URL will be retried. A URL will be retried maximum 25 times with an increasing interval.
Properties
The following parameters will be returned:
Property | Description |
---|---|
Number |
The number of the number lookup query. |
REFERENCE |
Only return when specified at the number lookup query. The reference specified when sending the number lookup query to the system. |
STATUS |
The status of the number lookup query. The status can be one of the following values
|
REASON |
When the status is not ‘Delivered’, a reason code will be returned. |
TIMESTAMP |
The timestamp the SMS was delivered at the destination. The timestamp is in the format YYYYMMDDHHIISS in UTC. |
Example
http://www.yoururl.com/callback?
NUMBER=&REFERENCE=12345678&STATUS=Delivered&
REASON=&TIMESTAMP=
Depending on the agreements made with Silverstreet and if the information is available, the following parameters may also returned:
Property | Description |
---|---|
IMSI |
The IMSI of the number. |
NETWORKCODE |
The network code of the found operator. The network code is build up out of the MCC and the MNC. Example: 20404 |
OPERATOR |
The name of the found operator preceded by the country name. Example: (Netherlands) Vodafone |
COUNTRYCODE |
The two-digit ISO country code of the country of the found operator. Example: nl |
MSC |
The MSC the number is currently signed into. |
Example with more information
http://www.yoururl.com/callback?
NUMBER=&REFERENCE=12345678&STATUS=Delivered&
REASON=&TIMESTAMP=&
NETWORKCODE=&COUNTRYCODE=nl
By Email
When you have specified a callback email you will receive an email send from ‘dlr@silverstreet.com’ with
the subject Number lookup results for number <number>
. The content of the email can
contain the same fields as the
possible
parameters in case a callback URL is specified. The email will be in html format.
Title | Content |
---|---|
Subject |
Number lookup results for number
|
Body |
Number Reference 12345678 Status Delivered Reason Network code 12345 Operator (Netherlands) KPN Country code nl Best regards, __________________________ Silverstreet Active Media Karolusstraat 20a 4903 RJ Oosterhout The Netherlands [P]: +31 (0)13-4690886 [F]: +31 (0)13-4690887 www.silverstreet.com info@silverstreet.com |
Incoming SMS (MO)
When a SMS MO is sent to a customer, a HTTP URL is called at customer’s system. The URL that is used for this call is configured at Silverstreet’s messaging platform, which is linked to the mobile phone number (MSISDN) the MO was sent to, and optionally, to the keyword and sub-keyword if used.
Integrated with MT and MO message would enable 2-way communcication (sending and receiving) in supported country or location.
Callback
The delivery reports will be send by the system with source IP address 195.88.18.2
. This IP
should be whitelisted on
your side.
The customer’s system has to respond with HTTP status 200 and the text OK
when a SMS MO is
received by
customer’s
system. If any other response is returned by the customer’s system, the URL will be retried for a
maximum of 10 times
with an increasing interval between the retries. The retry period will end 72 hours after the first
attempt.
Properties
The following parameters will be returned:
Property | Description |
---|---|
SENDER |
The mobile number (MSISDN) of the SMS MO was sent from in internal format. Example: . |
KEYWORD |
The keyword with which the SMS MO starts. This field is empty in case there was no need to check on a keyword (catch all). |
BODY |
The message of the SMS MO. |
MSGTYPE |
The message type of the BODY. Possible values are 0 for plain text and 8 for Unicode (Base64 encoded). |
OPERATOR |
The network code (MCC + MNC) of the operator of the sender. Example: 20408 for operator (The Netherlands) KPN. |
TIMESTAMP |
The time the SMS MO was received by the SMSC. The timestamp is in the format YYYYMMDDHHIISS. |
RECIPIENT |
The mobile number (MSDISDN) of the recipient of the SMS MO in international format. Example: . |
UDH |
The UDH of the SMS MO if received by the system. Example: 050003CC0201 for a concatenated SMS MO. |
Example
http://www.yoururl.com/callback?
SENDER=&KEYWORD=test&BODY=Test%20message&
TIMESTAMP=&OPERATOR=&
MSGTYPE=8&RECIPIENT=
Credit Check
Check your account credit using the http API
Properties
Mandatory parameter must be included upon submission.
Property | Type | Description |
---|---|---|
username |
String | The username to connect to the API.The maximum length is 20 characters. |
password |
String | The password to connect to the API.The maximum length is 20 characters. |
Query
Submit the query to the end point to retrieve your account credit balance.
HTTP Endpoint
GET
GET /creditcheck.php
You can simply use the GET method to query the account balance with sample below
http://api.silverstreet.com/creditcheck.php?username=<username>&password=<password>
POST
POST /creditcheck.php
Response Code
When the credit balance request is sent, the system will give a response to the call.
When the request is successful, an XML will be returned. The balance field contains the credits balance of the account in the configured currency of the account.
Credit Check Result
<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet type="text/xsl" href="creditcheck.xsl"?>
<credits>
<balance>372.50</balance>
</credits>
The following responses can be given in case of an error:
Code | Description |
---|---|
100 |
Parameter(s) are missing. |
110 |
Bad combination of parameters. |
120 |
Invalid parameter(s). |
Mail2SMS
Introduction
Welcome to the Silverstreet Mail2SMS!
Silverstreet Mail2SMS service intelligently converts your email to SMS and delivers the message to your recipients’ handset.
Registration
You are required to provide following information to setup your Mail2SMS account.
Item | Description |
---|---|
Account Name |
You can let us know which account you would like this message to charge to. |
Sender Email Address or Hosts |
This is to set up who can send us the email to deliver the SMS. you can set up individual email or a hosts of emails. Email Address: e.g. testing@silverstreet.com or Host: e.g. *@silverstreet.com |
Sender ID |
You may set a prefferred sender id, if you do not have any preferred Sender ID, we will provide a random numeric sender ID. |
Type of Delivery Report |
Type of Delivery Report would like to receive, you can choose 1 from the below list
|
Delivery Report Email |
Email address to receive delivery reports: e.g. delivery_report@silverstreet.com |
Delivery Report URL |
URL to receive delivery reports: e.g. yoururl.com/callback |
Submit
Upon registration, you can then send messages with emails.
Item | Description |
---|---|
To |
Key-in <MSISDN>@sms.silverstreet.com. E.g. 60193345678@sms.silverstreet.com, The mobile numbers must be in international format without 00 or + in front. For multiple recipients, all email addresses in the To or Cc of the email (Bcc is not supported). |
Subject |
If left empty, the Sender ID, which has been generated during account setup will be displayed to the recipient. Otherwise, key in preferred Sender ID. |
Content |
1 SMS consists of a maximum of 160 characters; therefore if the email content
is more than 160 characters, the SMS will be delivered as a concatenated SMS,
which means it will be split up into the required number of messages. The whole body of the email will be used except when the end tag ‘*****’ is used. Only the text till the end tag will be used for the body of the SMS in that case. The system checks if the SMS should be send as Unicode or as a normal SMS. |
Reseller
Silverstreet is constantly looking for new ways to grow its network of resellers and partners in any way that makes sense for all parties involved.
As a Silverstreet reseller, you can easily launch your own Mail2SMS platform especially when you have a network of potential clients who can benefit from the use of Mail2SMS and to ensure that your contacts are properly supported for their mobile needs while you collect a recurring revenue stream for the business generated!
Following the simple steps to become Mail2SMS reseller
- You need to create a host email. e.g. *@sms.company.com
- Forward the email to mail2sms@sms.silverstreet.com
- Provide “From Email Address” and “From Name” information to Silverstreet
- Delivery reports returned to your customer via email will be sent from your “From-Email-Address”
API Documentation
Introduction
Welcome to the Silverstreet API!
The REST API communicates exclusively in JSON over SSL (HTTPS). Request and response data are JSON formatted using UTF-8 encoding and URL encoded values. The only requirement to use our API is to create an account on our portal.
All endpoint URLs begin with a domain name. Which domain name you have to use depends on the location you have created your Silverstreet application for.
Currently we have the following API nodes:
Location | Host | Callback host |
---|---|---|
Singapore | api-asia-01.silverstreet.com | api-asia-01-out.silverstreet.com |
Frankfurt | api-eu-01.silverstreet.com | api-eu-01-out.silverstreet.com |
If you are located in Africa, North- or South America, it doesn’t mean you can’t use our services. You can still connect with one of the available nodes.
When our API performs a callback to deliver message results to you, it will come from the callback host listed above. Please make sure that you have white listed the callback hosts to ensure we can deliver the results to you.
It is recommended that you use the media type designation of application/json
.
Silverstreet has API nodes at different locations in the world. For some services when you create a service, you have to select for which node. Your service will only be available on that node.
Service | Select node |
---|---|
Address Book |
Yes |
Push |
Yes |
Email |
Yes |
SMS |
No |
Number Lookup |
No |
Verification |
No |
VMN App |
No |
Authentication
To authorize, use this code:
curl /v1/wallet/getbalance \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>"
With each API call you will need to authenticate yourself via HTTP
Basic Authentication. You can do this by setting the request headers. In
the request headers you can set the username and password for the
authentication. The user name and password must be base64 encoded. For
the username you have to fill in silverstreet
. If you use
one of our libraries or SDK's the username will be done for you, you
just have to create an instance and set your API key and node you want
to connect to. The base64 encoding of the username and password will be
done by cURL and our libraries and SDK's automatically.
Errors
Example error response:
{
"errorCode": 103,
"type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
"title": "Unprocessable Entity",
"status": 422,
"detail": "Invalid token."
}
The Silverstreet API uses standard HTTP status codes to indicate success or failure of your API calls. API calls, which are successful, have a HTTP status code in the range of 2xx. API calls, which have a failure, have a HTTP status code in the range of 4xx. The Silverstreet API can at least return HTTP status codes as shown in the table below. For some status codes an errorCode is added as well.
HTTP Status code | Error code | Description |
---|---|---|
200 | The HTTP call is successful. | |
201 | The Verification, SMS or Number Lookup is successfully created. | |
204 | The SMS delivery reports and number lookup results are successfully confirmed or the backup codes are successfully deleted. | |
400 | The data you have submitted could not be properly JSON decoded. | |
401 | You have provided an invalid API key. Get the correct API key from our portal (https://portal.silverstreet.com/applications). | |
402 | 303 | Your wallet is out of credit. Please topup your wallet to ensure you can use our service again. |
403 | 301 | Your account is disabled. Please contact our support team to help you further on this. |
403 | 302 | Your account is not enabled for the service. You can enable the service in our portal (https://portal.silverstreet.com/accounts). |
404 | The Verification, SMS or Number Lookup with the specified messageId was not found. | |
406 | Cannot honor Accept type specified, only Accept header 'application/json' is supported. See Authentication example how to set it. | |
409 | You have requested to create backup codes via a HTTP POST but the used identifier already exists. If you want to overwrite the existing entity use HTTP PUT instead. | |
415 | Invalid content-type specified, only Content-type header 'application/json' is supported. See Authentication example how to set it. | |
422 | 103 | Invalid token. The token entered by the user does not match with the token sent by our API to the user. |
423 | 101 | The token you tried to verify was already verified, you are only allowed to check a certain token once. |
423 | 102 | The token you tried to verify is expired. The token was not entered by the user within the required time (validity). |
423 | 104 | The token you tried to verify is failed. The reason why it is failed is for example because the Verification service of the account is disabled. In that case no token is sent and the user entered a random token. |
429 | You are sending too fast and your calls are throttled. | |
5xx | An internal system error occurred. When this happens you can retry submitting the message. |
Credit balance
Credit balances are represented as follows:
{
"credit": ,
"currencyCode": "usd",
"freeVerifications": ,
"wallet": "Default wallet"
}
Properties
Property | Type | Description |
---|---|---|
credit |
Float | Not null. The current credit balance of your wallet. Can be negative in certain situations. |
currencyCode |
String | Not null. This is a 3-digit ISO 4217 code of the currency of your wallet. |
freeVerifications |
Integer | Not null. The number of free verifications you have left for this month. |
wallet |
String | Not null. The name of your wallet. |
Get balance
Retrieve the credit balance of your wallet:
curl /v1/wallet/getbalance \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>"
The response looks like this:
{
"credit": ,
"currencyCode": "usd",
"freeVerifications": ,
"wallet": "Default wallet"
}
Retrieve the credit balance of your wallet.
HTTP Endpoint
GET /v1/wallet/getbalance
Arguments
None.
Balance alarm webhook
The data we will send to you looks like this:
{
"credit": ,
"currencyCode": "usd",
"freeVerifications": ,
"wallet": "Default wallet"
}
In case you have configured a balance alarm with a webhook, the system will do a HTTP
POST
to the configured URL.
Verification
Verifications are represented as follows:
{
"applicationTag": "Default application",
"tokenLength": 6,
"tokenType": "numeric",
"createdDateTime": "",
"dcs": 0,
"issuer": null,
"language": null,
"messageId": "eu-01-1.25569.ver583ed178a52521.24988267",
"reasonCode": null,
"recipient": "",
"salesPrice": 0,
"salesPriceCurrencyCode": "eur",
"sender": "Silver",
"senderNpi": 0,
"senderTon": 5,
"sessionId": "3f2d893f-a663-4919-9472-e8b7f4b61fa7",
"status": "success",
"statusCode": 1,
"tag": null,
"bodyTemplate": "Your verification token is: %token%",
"type": "sms",
"validity": 30,
"validUntilDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/verification\/submit\/eu-01-1.25569.ver583ed178a52521.24988267"
}
}
}
Properties
Property | Type | Description |
---|---|---|
applicationTag |
String | Not null. The application used for sending the verification. |
tokenLength |
Integer | Can be null. The length of the token as specified when sending the verification or the default value (6). |
tokenType |
String | Can be null. The type of the token as specified when sending the verification or the default value (numeric). |
createdDateTime |
String | Not null. The datetime the verification was received by the API. The datetime is in ISO-8601 format. |
dcs |
Integer | Can be null. The DCS value as specified when sending the verification. |
issuer |
String | Can be null. The issuer name as specified when sending the verification. |
language |
String | Can be null. Currently not used yet. |
messageId |
String | Not null. The unique identifier, generated by the API, of the verification. |
reasonCode |
Integer | Can be null. When the verification is rejected or failed a reasonCode can be given explaining the cause of the rejection. See further down below for an overview of possible reasonCodes. |
recipient |
String | Not null. The phone number as specified when sending the verification, the token must be send to. |
salesPrice |
Float | Can be null. The sales price of the verification. When the verification was a free monthly verification the sales price is 0. |
salesPriceCurrencyCode |
String | Can be null. The currency code of the salesPrice field. The currency code is defined by the currency of your wallet. The currencyCode is in the 3-digit ISO 4217 code format. |
sender |
String | Can be null. The sender of the token in case of an SMS as specified
when sending the verification or the default value. The default value
for the sender is Silver . |
senderNpi |
Integer | Can be null. The senderNpi of the token in case of an SMS as specified when sending the verification or the automatically detected value by the API. See our tutorial 'Sender' for more information. |
senderTon |
Integer | Can be null. The senderTon of the token in case of an SMS as specified when sending the verification or the automatically detected value by the API. See our tutorial 'Sender' for more information. |
sessionId |
String | Not null. The sessionId generated by the API when it was left out with the verification request or the sessionId you specified at the verification request. See 'Verification session' for more information. |
status |
String | Not null. The status of the verification. The status and
statusCode fields are bound together. Possible values are listed in the
table
below. |
statusCode |
Integer | Not null. See status field for more information. |
tag |
String | Can be null. The tag as specified when sending the verification. |
bodyTemplate |
String | Can be null. The tag value as specified when sending the verification or the default value (Your verification token is: %token%) |
type |
String | Not null. The type as specified when sending the verification or the default value (sms) |
validity |
Integer | Not null. The validity in seconds as specified when sending the verification or the default value (60). |
validUntilDateTime |
String | Not null. The datetime until when the verification is valid. This is calculated by the API based on the validity field. |
The status
and statusCode
fields can have the following values:
Code | Status | Description |
---|---|---|
0 | no status |
The token is generated and sent to the phone. |
1 | success |
The token is successfully verified. The entered token matches with the token sent to the phone. |
2 | rejected |
The verification is rejected by the system and no token is sent to the phone. The reasonCode field indicates the reason why it is rejected. See further down below for an overview of possible reasonCodes. |
3 | expired |
The verification is expired as the token was not verified within the specified validity time. |
4 | failed |
The verification is failed as the entered token didn’t match with the token sent to the phone. The reasonCode field indicates the reason why it is rejected. See further down below for an overview of possible reasonCodes. |
Submit verification
Example submit verification:
curl -X POST /v1/verification/submit \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>" \
-d '{
"recipient" : ""
}'
The response looks like this:
{
"applicationTag": "Default application",
"tokenLength": null,
"tokenType": null,
"createdDateTime": "",
"dcs": null,
"issuer": "Silver",
"language": null,
"messageId": "eu-01-1.17172.ver583d6255ae66f2.27354409",
"reasonCode": null,
"recipient": "",
"salesPrice": null,
"salesPriceCurrencyCode": null,
"sender": null,
"senderNpi": null,
"senderTon": null,
"sessionId": "3f2d893f-a663-4919-9472-e8b7f4b61fa7",
"status": "no status",
"statusCode": 0,
"tag": null,
"bodyTemplate": null,
"type": "sms",
"validity": null,
"validUntilDateTime": null,
"_links": {
"self": {
"href": "https:\/\/\/v1\/verification\/submit\/eu-01-1.17172.ver583d6255ae66f2.27354409"
}
}
}
HTTP Endpoint
POST /v1/verification/submit
Arguments
Key | Type | Description |
---|---|---|
recipient |
String | Required. The recipient phone number in international format. It can be a mobile number or a fixed phone number. |
type |
String | Optional. The type of token to be send to the phone. Possible values are:
sms , call , push ,
telegram , line or facebook_messenger . The
default
value is sms . |
issuer |
String | Required for types push , telegram , line ,
facebook_messenger . The name to be displayed for the received
verification
message. See our FAQ about issuer for
more
information. |
tokenLength |
String | Optional. The tokenLength defines the length of the token. The minimum value is 4 and the maximum value 10. The default value is 6. When you set the tokenLength, you have to set the tokenType as well. |
tokenType |
String | Optional. Possible values are numeric and alphanumeric .
Numeric token will only contain the digits 0-9. For alphanumeric the
token contains the digits 0-9 and characters a-z (lowercase). The
default value of the tokenType is numeric . When you set the tokenType,
you have
to set the tokenLength as well. |
tag |
String | Optional. The tag is a free text parameter you can use for your own reference. The maximum length of the tag is 30 characters. The tag parameter is returned in the result and you can use it for reporting purposes on your side. |
sessionId |
String | Optional. If it is not set the API will automatically generate the value. See 'Verification session' for more information. The maximum length of the sessionId is 54 characters. |
validity |
String | Optional. The validity specifies how long the token is valid. The validity is in seconds. If the token is not verified within this time, the token is expired. The minimum value of the validity is 5 seconds and the maximum value is 3600 seconds (= 1 hour). The default value is 60 seconds. |
bodyTemplate |
String | Optional. Only for SMS verification. The body template in case an SMS needs to be send. The body template must contain the tag '%token%' which will be used by the system to replace it with the actual token to be send to the end user. The maximum length on the body template is for GSM-7 alphabet 160 characters and for Unicode maximum 70 characters. This is including the token which will be inserted by the system. So if you set a tokenLength of 8, the max length of the bodyTemplate is 160-8=152 characters excluding the text '%token%'. If you do not set the tokenLength, the API will need to consider the maximum length of the token (10) for the maximum bodyTemplate length, so in that case the bodyTemplate can have a maximum length of 150 characters for GSM-7 and 60 for Unicode. Concatenated messages are not possible for these SMS messages. See our tutorial 'Unicode' for more information on the maximum length of the body. Default value for the bodyTemplate is: Your verification token is: %token% |
sender |
String | Optional. Only for SMS verification. The sender is what the receiver
of the SMS see as the submitter of the SMS. See our tutorial 'Sender' for more
information.
The default value for the sender is Silver . |
senderTon |
Integer | Optional. Only for SMS verification. If it is not set the API will automatically detect the value. See our tutorial 'Sender' for more information. |
senderNpi |
Integer | Optional. Only for SMS verification. If it is not set the API will automatically detect the value. See our tutorial 'Sender' for more information. |
dcs |
Integer | Optional. Only for SMS verification. With the DCS parameter you can specify the character set of the bodyTemplate. For GSM-7 the value should be 0 and for Unicode the value should be 8. The default value is 0. See our tutorial 'Unicode' for more information. |
Verify token
Example verify a token:
curl /v1/verification/submit/eu-01-1.25569.ver583ed178a52521.24988267?token=123456 \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>"
The response looks like this:
{
"applicationTag": "Default application",
"tokenLength": 6,
"tokenType": "numeric",
"createdDateTime": "",
"dcs": 0,
"issuer": null,
"language": null,
"messageId": "eu-01-1.25569.ver583ed178a52521.24988267",
"reasonCode": null,
"recipient": "",
"salesPrice": 0,
"salesPriceCurrencyCode": "eur",
"sender": "Silver",
"senderNpi": 0,
"senderTon": 5,
"sessionId": "3f2d893f-a663-4919-9472-e8b7f4b61fa7",
"status": "success",
"statusCode": 1,
"tag": null,
"bodyTemplate": "Your verification token is: %token%",
"type": "sms",
"validity": 30,
"validUntilDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/verification\/submit\/eu-01-1.25569.ver583ed178a52521.24988267"
}
}
}
HTTP Endpoint
GET /v1/verification/submit/<MESSAGE_ID>?token=<TOKEN>
Arguments
Key | Type | Description |
---|---|---|
messageId |
String | Required. The messageId returned with the verification submit. |
token |
String | Required. The token entered by the user and you want to verify with the token we sent to the user. |
Get status
Example get verification status:
curl /v1/verification/submit/<MESSAGE_ID> \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>"
The response looks like this:
{
"applicationTag": "Default application",
"tokenLength": 6,
"tokenType": "numeric",
"createdDateTime": "",
"dcs": 0,
"issuer": null,
"language": null,
"messageId": "eu-01-1.18667.ver583d637356cd58.88711156",
"reasonCode": null,
"recipient": "",
"salesPrice": 0.024,
"salesPriceCurrencyCode": "eur",
"sender": "Silver",
"senderNpi": 0,
"senderTon": 5,
"sessionId": "3f2d893f-a663-4919-9472-e8b7f4b61fa7",
"status": "success",
"statusCode": 1,
"tag": null,
"bodyTemplate": "Your verification token is: %token%",
"type": "sms",
"validity": 30,
"validUntilDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/verification\/submit\/eu-01-1.18667.ver583d637356cd58.88711156"
}
}
}
HTTP Endpoint
GET /v1/verification/submit/<MESSAGE_ID>
Arguments
Key | Type | Description |
---|---|---|
messageId |
String | Required. The messageId returned with the verification submit. |
Verification reason codes
Reason code | Description |
---|---|
201 | Insufficient credit. |
202 | Recipient temporary not available (phone switched off, roaming, handset memory full, etc.). |
203 | Recipient permanent not available (invalid number, handset doesn't support SMS, blacklisted, etc.). |
204 | Permanent network error. |
205 | Temporary network error. |
206 | Incorrect message parameter. |
207 | Rejected due to account issue. |
208 | Rejected due to spam or illegal content. |
209 | Validity expired. |
299 | An unknown error occurred. |
Verification Widget Session
For more information how to integrate the verification widget, checkout our widget guide.
Properties
The verification sessions are represented as follows:
{
"sessionToken": "eu-01_1161130_wid59003566562fe8.59122114e17b",
"applicationTag": "Default application",
"bodyTemplate": "Your verification token is %token%",
"createdDateTime": "",
"dcs": null,
"issuer": null,
"language": null,
"recipient": "",
"sender": "Silver",
"senderNpi": null,
"senderTon": null,
"tag": null,
"tokenLength": 6,
"tokenType": "numeric",
"requestedTypes": [
"sms",
"call"
],
"allowedTypes": {
"1": "sms",
"2": "call"
},
"validity": null,
"status": "success",
"statusCode": 1,
"backupCodeIdentifier": null,
"verificationIds": [
"eu-01-1.17172.ver583d6255ae66f2.27354409",
"eu-01-1.18352.ver529c5e45ae72a2.83645283"
],
"verification": {
"applicationTag": "Default application",
"bodyTemplate": null,
"createdDateTime": "",
"dcs": null,
"issuer": null,
"language": null,
"messageId": "eu-01-1.18352.ver529c5e45ae72a2.83645283",
"reasonCode": null,
"recipient": "",
"salesPrice": 0.07,
"salesPriceCurrencyCode": "eur",
"sender": null,
"senderNpi": null,
"senderTon": null,
"sessionId": "eu-01_1161130_wid59003566562fe8.59122114e17b",
"status": "success",
"statusCode": 1,
"tag": null,
"tokenLength": null,
"tokenType": null,
"type": "sms",
"validity": null,
"validUntilDateTime": null,
"webHook": null,
"_links": {
"self": {
"href": "https:\/\/\/v1\/verification\/submit\/eu-01-1.18352.ver529c5e45ae72a2.83645283"
}
},
"_links": {
"self": {
"href": "https:\/\/\/v1\/widget\/verification\/session\/eu-01_1161130_wid59003566562fe8.59122114e17b"
}
}
}
Property | Type | Description |
---|---|---|
sessionToken |
String | Not null. The unique id identifying this widget verification session. |
applicationTag |
String | Not null. The application used for sending the verification. |
tokenLength |
Integer | Can be null. The length of the token as specified when sending the verification or the default value (6). |
tokenType |
String | Can be null. The type of the token as specified when sending the verification or the default value (numeric). |
createdDateTime |
String | Not null. The datetime the verification was received by the API. The datetime is in ISO-8601 format. |
dcs |
Integer | Can be null. The DCS value as specified when sending the verification. |
issuer |
String | Can be null. The issuer name as specified when sending the verification. |
language |
String | Can be null. Currently not used yet. |
recipient |
String | Not null. The phone number as specified when sending the verification, the token must be send to. |
sender |
String | Can be null. The sender of the token in case of an SMS as specified
when sending the verification or the default value. The default value
for the sender is Silver . |
senderNpi |
Integer | Can be null. The senderNpi of the token in case of an SMS as specified when sending the verification or the automatically detected value by the API. See our tutorial 'Sender' for more information. |
senderTon |
Integer | Can be null. The senderTon of the token in case of an SMS as specified when sending the verification or the automatically detected value by the API. See our tutorial 'Sender' for more information. |
status |
String | Not null. The status of the widget verification session. The status and
statusCode fields are bound together and can have the values as can be
found in
the table below. |
statusCode |
Integer | Not null. See status field for more information. |
tag |
String | Can be null. The tag as specified when sending the verification. |
bodyTemplate |
String | Can be null. The tag value as specified when sending the verification or the default value (Your verification token is: %token%) |
requestedTypes |
Array | Not null. The allowed types as specified when creating the widget verification session. |
allowedTypes |
Array | Not null. The allowed types as specified when creating the widget
verification session minus types not available for the user. For example
when you set backupcode but for the backupCodeIdentifier you specified
the API
cannot find backup codes, the type will be removed. |
validity |
Integer | Not null. The validity in seconds as specified when sending the verification or the default value (60). |
backupCodeIdentifier |
String | Can be null. The backupCodeIdentifier if set when creating the session. |
totpIdentifier |
String | Can be null. The totpIdentifier if set when creating the session. |
verificationIds |
Array | Not null. An array with verification ID's performed during the session. |
verification |
Verification object | Can be null. When the session is successfull, this parameter contains the successful verification object. |
The status
and statusCode
fields can have the following values:
Code | Status | Description |
---|---|---|
0 | no status | The widget verification session is created and waiting for the widget to get started and performing verifications. |
1 | success | The widget verification session is successfully verified. The entered token matches with the token sent to the phone. |
2 | expired | The widget verification session is expired as the token was not verified within the specified validity time of the widget verification session. |
3 | max_attempts | The verification has failed the maximum number of attempts of sending verification has reached. |
Create verification session
Create a verification session:
curl -X POST /v1/widget/session \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>" \
-d '{
"recipient" : ""
}'
The response will look like this:
{
"sessionToken": "eu-01_1161130_wid59003566562fe8.59122114e17b",
"applicationTag": "Default application",
"bodyTemplate": "Your verification token is %token%",
"createdDateTime": "",
"dcs": null,
"issuer": null,
"language": null,
"recipient": "",
"sender": "Silver",
"senderNpi": null,
"senderTon": null,
"tag": null,
"tokenLength": 6,
"tokenType": "numeric",
"requestedTypes": [
"sms",
"call"
],
"allowedTypes": [
"sms",
"call"
],
"validity": null,
"status": "no status",
"statusCode": 0,
"backupCodeIdentifier": null,
"verificationIds": [],
"verification": null,
"_links": {
"self": {
"href": "https:\/\/\/v1\/widget\/verification\/session\/eu-01_1161130_wid59003566562fe8.59122114e17b"
}
}
}
HTTP Endpoint
POST /v1/widget/session
Arguments
Key | Type | Description |
---|---|---|
allowedTypes |
Array | Optional. The allowedTypes defines which verification types can be used with the
widget.
Possible values are: sms , call ,
push , totp , facebook_messenger ,
telegram , line or
backupcode .
When you do not set the parameter, the widget will use as default the
types you have set for your account (Open the settings of the account
and on the Verification tab select the types you want to allow your
users to use). The first type you set as allowed type will be the first
verification the widget will perform. The API will filter out certain
types when that option is not available for the user. For example when
you set 'backupcode' but for the backupCodeIdentifier you specified the
API cannot find backup codes, the type will be removed. See
'requestedTypes' and 'allowedTypes' in the status result for more
information. |
recipient |
String | Required when for the allowedTypes sms or call
is included. The recipient is a single phone number in international
format. The phone number can be a mobile number or a fixed phone number. |
backupCodeIdentifier |
String | Required when for the allowedTypes backupcode is included. The
backupCodeIdentifier is the identifier you used for creating the backup codes for
the user.
|
totpIdentifier |
String | Required when for the allowedTypes totp is included. The totpIdentifier
is the
identifier you used for creating the TOTP for the user. |
tokenLength |
Integer | Optional. The tokenLength defines the length of the token. The minimum value is 4 and the maximum value 10. The default value is 6. When you set the tokenLength, you have to set the tokenType as well. |
tokenType |
String | Optional. Possible values are numeric and alphanumeric .
Numeric token will only contain the digits 0-9. For alphanumeric the
token contains the digits 0-9 and characters a-z (lowercase). The
default value of the tokenType is numeric . When you set the tokenType,
you have
to set the tokenLength as well. |
tag |
String | Optional. The tag is a free text parameter you can use for your own reference. The maximum length of the tag is 30 characters. The tag parameter is returned in the result and you can use it for reporting purposes on your side. |
issuer |
String | Required for verifications of type push ,facebook_messenger ,
telegram or
line .
The issuer is the name of the site the user wants to login to. When the
user receives the request to confirm he wants to login, the user will
get a message like "Please confirm to verify your login of '%issuer%'". |
bodyTemplate |
String | Optional. The body template in case an SMS needs to be send. The body template must contain the tag '%token%' which will be used by the system to replace it with the actual token to be send to the end user. The maximum length on the body template is for GSM-7 alphabet 160 characters and for Unicode maximum 70 characters. This is including the token which will be inserted by the system. So if you set a tokenLength of 8, the max length of the bodyTemplate is 160-8=152 characters excluding the text '%token%'. Concatenated messages are not possible for these SMS messages. See our tutorial 'Unicode' for more information on the maximum length of the body. Default value for the bodyTemplate is: Your verification token is: %token% |
sender |
String | Optional. The sender is what the receiver of the SMS see as the submitter of the
SMS. See
our tutorial 'Sender' for
more
information. The default value for the sender is Silver . |
senderTon |
Integer | Optional. If it is not set the API will automatically detect the value. See our tutorial 'Sender' for more information. |
senderNpi |
Integer | Optional. If it is not set the API will automatically detect the value. See our tutorial 'Sender' for more information. |
dcs |
Integer | Optional. With the DCS parameter you can specify the character set of the bodyTemplate. For GSM-7 the value should be 0 and for Unicode the value should be 8. The default value is 0. See our tutorial 'Unicode' for more information. |
Get session status
Get verification session status:
curl /v1/widget/session/<SESSION_TOKEN>?recipient= \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>"
The response will look like this:
{
"sessionToken": "eu-01_1161130_wid59003566562fe8.59122114e17b",
"applicationTag": "Default application",
"bodyTemplate": "Your verification token is %token%",
"createdDateTime": "",
"dcs": null,
"issuer": null,
"language": null,
"recipient": "",
"sender": "Silver",
"senderNpi": null,
"senderTon": null,
"tag": null,
"tokenLength": 6,
"tokenType": "numeric",
"requestedTypes": [
"sms",
"call"
],
"allowedTypes": [
"sms",
"call"
],
"validity": null,
"status": "no status",
"statusCode": 0,
"backupCodeIdentifier": null,
"verificationIds": [],
"verification": null,
"_links": {
"self": {
"href": "https:\/\/\/v1\/widget\/verification\/session\/eu-01_1161130_wid59003566562fe8.59122114e17b"
}
}
}
HTTP Endpoint
GET /v1/widget/session/<SESSION_TOKEN>?recipient=<RECIPIENT>&backupCodeIdentifier=<BACKUP_CODE_IDENTIFIER>&totpIdentifier=<TOTP_IDENTIFIER>
Arguments
Key | Type | Description |
---|---|---|
sessionToken |
Array | Optional. The allowedTypes defines which verification types can be used with the
widget.
Possible values are: sms , call ,
push , totp , facebook_messenger ,
telegram , line or
backupcode .
When you do not set the parameter, the widget will use as default the
types you have set for your account (Open the settings of the account
and on the Verification tab select the types you want to allow your
users to use). The first type you set as allowed type will be the first
verification the widget will perform. The API will filter out certain
types when that option is not available for the user. For example when
you set 'backupcode' but for the backupCodeIdentifier you specified the
API cannot find backup codes, the type will be removed. See
'requestedTypes' and 'allowedTypes' in the status result for more
information. |
recipient |
String | Required when for the allowedTypes sms or call
is included. The recipient is a single phone number in international
format. The phone number can be a mobile number or a fixed phone number. |
backupCodeIdentifier |
String | Required when for the allowedTypes backupcode is included. The
backupCodeIdentifier is the identifier you used for creating the backup codes for
the user.
|
totpIdentifier |
String | Required when for the allowedTypes totp is included. The totpIdentifier
is the
identifier you used for creating the TOTP for the user. |
Registration Widget Session
For more information how to integrate the registration widget, checkout our widget guide.
Properties
The registration sessions are represented as follows:
{
"sessionToken": "eu-01_1161130_wid5aab9dec9bca47.995159356758",
"applicationTag": "Default application",
"requestedTypes": [
"sms",
"call",
],
"registeredTypes": [
"sms",
"call",
],
"allowedTypes": [
"sms",
"call",
],
"recipient": "",
"totpIdentifier": null,
"backupCodeIdentifier": null,
"issuer": null,
"language": "en",
"status": "no status",
"statusCode": 0,
"createdDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/widget-register-verification\/session\/eu-01_1161130_wid5aab9dec9bca47.995159356758"
}
}
}
Property | Type | Description |
---|---|---|
sessionToken |
String | Not null. The unique id identifying this widget verification session. |
applicationTag |
String | Not null. The application used for sending the verification. |
requestedTypes |
Array | Not null. The requested verification types. |
registeredTypes |
Array | Not null. The verification types the user is registered for. |
allowedTypes |
Array | Not null. The verification types the user is allowed for. This depends on the settings of the used account. |
recipient |
String | Not null. The phone number of the recipient. |
totpIdentifier |
String | Can be null. The totpIdentifier is the identifier you used for creating the TOTP for the user. |
backupCodeIdentifier |
String | Can be null. The backupCodeIdentifier is the identifier you used for creating the backup codes for the user. |
issuer |
String | Can be null. The issuer is the name of the site the user wants to login to. When the user receives the request to confirm he wants to login, the user will get a message like "Please confirm to verify your login of '%issuer%'". |
language |
String | Can be null. Language used for the verifications. Currently not used. |
status |
String | Not null. The status of the registration session. The status and
statusCode fields are bound together. Possible values are listed in the
table
below. |
statusCode |
String | Not null. See status for more information. |
createdDateTime |
String | Not null. The datetime the verification was received by the API. The datetime is in ISO-8601 format. |
The status
and statusCode
fields can have the following values:
Code | Status | Description |
---|---|---|
0 | no status | The widget verification session is created and waiting for the widget to get started and performing verifications. |
1 | success | The widget verification session is successfully verified. The entered token matches with the token sent to the phone. |
2 | expired | The widget verification session is expired as the token was not verified within the specified validity time of the widget verification session. |
Create registration session
Create a registration session:
curl -X POST /v1/widget-register-verification/session \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>" \
-d '{
"recipient" : ""
}'
The response will look like this:
{
"sessionToken": "eu-01_1161130_wid5aab9dec9bca47.995159356758",
"applicationTag": "Default application",
"requestedTypes": [
"sms",
"call",
],
"registeredTypes": [
"sms",
"call",
],
"allowedTypes": [
"sms",
"call",
],
"recipient": "",
"totpIdentifier": null,
"backupCodeIdentifier": null,
"issuer": null,
"language": "en",
"status": "no status",
"statusCode": 0,
"createdDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/widget-register-verification\/session\/eu-01_1161130_wid5aab9dec9bca47.995159356758"
}
}
}
HTTP Endpoint
POST /v1/widget-register-verification/session
Arguments
Key | Type | Description |
---|---|---|
allowedTypes |
Array | Optional. The allowedTypes defines which verification types the user can register
for in the
widget. Possible values are: sms , call ,
push , totp ,facebook_messenger , telegram ,
line or
backupcode .
When you do not set the parameter, the widget will use as default the
types you have set for your account (Open the settings of the account
and on the Verification tab select the types you want to allow your
users to use). |
recipient |
String | Required when for the allowedTypes sms or call
is included. The recipient is a single phone number in international
format. The phone number can be a mobile number or a fixed phone number. |
backupCodeIdentifier |
String | Required when for the allowedTypes backupcode is included. The
backupCodeIdentifier is the identifier you used for creating the backup codes for
the user.
|
totpIdentifier |
String | Required when for the allowedTypes totp is included. The totpIdentifier
is the
identifier you used for creating the TOTP for the user. |
issuer |
String | Required when you want to use a verification of type push ,
facebook_messenger ,
telegram or line .
The issuer is the name of the site the user wants to login to. When the
user receives the request to confirm he wants to login, the user will
get a message like "Please confirm to verify your login of '%issuer%'". |
Backup Codes
Backup codes are represented as follows:
{
"identifier": "",
"amountOfCodesLeft": 10,
"codes": [
"73502977",
"64553227",
"61260614",
"91387132",
"74052942",
"29371709",
"22740780",
"43369151",
"51168501",
"19402795"
],
"createdDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/backupcode\/"
}
}
}
Properties
Property | Type | Description |
---|---|---|
identifier |
String | Not null. A unique identifier of the user, e.g. an email address. |
amountOfCodesLeft |
Integer | Not null. Number of backup codes left to use. |
codes |
Array | Not null. An array of generated backup codes. |
createdDateTime |
String | Not null. Date time the backup codes are generated. |
Create backup codes
Example create backup codes:
curl -X POST /v1/backupcode \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>" \
-d '{
"identifier" : ""
}'
The response looks like this:
{
"identifier": "",
"amountOfCodesLeft": 10,
"codes": [
"73502977",
"64553227",
"61260614",
"91387132",
"74052942",
"29371709",
"22740780",
"43369151",
"51168501",
"19402795"
],
"createdDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/backupcode\/"
}
}
}
HTTP Endpoint
POST /v1/backupcode
Arguments
Key | Type | Description |
---|---|---|
identifier |
String | Required. The identifier is a unique identifier of the user, e.g. an email address. |
Verify backup codes
Example verify a backup code:
curl /v1/backupcode/?token=73502977 \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>"
The response looks like this:
{
"identifier": "1",
"amountOfCodesLeft": 9,
"codes": [],
"createdDateTime": "",
"_embedded": {
"verification": {
"applicationTag": "Default application",
"bodyTemplate": null,
"createdDateTime": "",
"dcs": null,
"language": null,
"messageId": "eu-01-1.7926.ver5955ec8f6e9640.25672922",
"reasonCode": null,
"recipient": "",
"salesPrice": null,
"salesPriceCurrencyCode": null,
"sender": null,
"senderNpi": null,
"senderTon": null,
"sessionId": "",
"status": "success",
"statusCode": 1,
"tag": null,
"tokenLength": null,
"tokenType": null,
"type": "backupcode",
"validity": null,
"validUntilDateTime": null,
"webHook": null,
"_links": {
"self": {
"href": "https:\/\/\/v1\/verification\/submit\/eu-01-1.7926.ver5955ec8f6e9640.25672922"
}
}
}
},
"_links": {
"self": {
"href": "https:\/\/\/v1\/backupcode\/"
}
}
}
HTTP Endpoint
GET /v1/backupcode/<IDENTIFIER>?token=<BACKUP_CODE>
Arguments
Key | Type | Description |
---|---|---|
identifier |
String | Required. The identifier is a unique identifier of the user, e.g. an email address. |
backupCode |
String | Required. The backup code entered by the user. |
Get remaining backup codes
Example get remaining backup codes:
curl /v1/backupcode/ \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>"
The response looks like this:
{
"identifier": "",
"amountOfCodesLeft": 9,
"codes": [],
"createdDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/backupcode\/"
}
}
}
HTTP Endpoint
GET /v1/backupcode/<IDENTIFIER>
Arguments
Key | Type | Description |
---|---|---|
identifier |
String | Required. The identifier is a unique identifier of the user, e.g. an email address. |
Update backup codes
Example update backup codes:
curl -X PUT /v1/backupcode/ \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>"
-d '{
"identifier" : ""
}'
The response looks like this:
{
"identifier": "",
"amountOfCodesLeft": 10,
"codes": [
"73502977",
"64553227",
"61260614",
"91387132",
"74052942",
"29371709",
"22740780",
"43369151",
"51168501",
"19402795"
],
"createdDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/backupcode\/"
}
}
}
Updating backup codes will delete the existing backup codes and generate 10 new backup codes.
HTTP Endpoint
PUT /v1/backupcode/<IDENTIFIER>
Arguments
Key | Type | Description |
---|---|---|
identifier |
String | Required. The identifier is a unique identifier of the user, e.g. an email address. |
Delete backup codes
Example delete backup codes:
curl -X DELETE /v1/backupcode/ \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>"
HTTP Endpoint
DELETE /v1/backupcode/<IDENTIFIER>
Arguments
Key | Type | Description |
---|---|---|
identifier |
String | Required. The identifier is a unique identifier of the user, e.g. an email address. |
TOTP
TOTP's are represented as follows:
{
"identifier": "",
"issuer": "Silver",
"uri": "otpauth:\/\/totp\/Silverstreet:?secret=QBC4NBVJO37VZJHDHLKLKM6CVZBBV7MCAWIUZQWOK3ATLIWWPGHA&issuer=Silver",
"verification": null,
"_links": {
"self": {
"href": "https:\/\/\/v1\/totp\/"
}
}
}
Properties
Property | Type | Description |
---|---|---|
identifier |
String | Not null. The identifier is a unique identifier of the user, e.g. an email address. |
issuer |
String | Not null. The issuer is the name of the site the user wants to login to. The issuer will be visible to the user when he scans the TOTP with the Silverstreet Authenticator app and shows for which website the TOTP is. |
uri |
String | Can be null. The URI to generate a QR code. |
verification |
String | Can be null. Is set when a TOTP verification is performed. |
The URI can be converted to a QR code and scanned by the Silverstreet Authenticator. Check out our help topic 'How to generate a QR code'.
Create TOTP
Example create a TOTP:
curl -X POST /v1/totp \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>" \
-d '{
"identifier" : "",
"issuer": "Silver"
}'
The response looks like this:
{
"identifier": "",
"issuer": "Silver",
"uri": "otpauth:\/\/totp\/Silverstreet:?secret=QBC4NBVJO37VZJHDHLKLKM6CVZBBV7MCAWIUZQWOK3ATLIWWPGHA&issuer=Silver",
"verification": null,
"_links": {
"self": {
"href": "https:\/\/\/v1\/totp\/"
}
}
}
HTTP Endpoint
POST /v1/totp
Arguments
Key | Type | Description |
---|---|---|
identifier |
String | Required. The identifier is a unique identifier of the user, e.g. an email address. The identifier will be visible in the Silverstreet Authenticator app as the application name. |
issuer |
String | Required. The issuer is the name of the site the user wants to login to. The issuer will be visible to the user when he scans the TOTP with the Silverstreet Authenticator app and shows for which website the TOTP is. |
Verify TOTP
Example verify a TOTP:
curl /v1/totp/?token=012345 \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>"
The response looks like this:
{
"identifier": "",
"issuer": "Silver",
"uri": null,
"_embedded": {
"verification": {
"applicationTag": "Default application",
"bodyTemplate": null,
"createdDateTime": "",
"dcs": null,
"issuer": "Silver",
"language": null,
"messageId": "eu-01-1.7926.ver5955ec8f6e9640.25672922",
"reasonCode": null,
"recipient": "",
"salesPrice": null,
"salesPriceCurrencyCode": null,
"sender": null,
"senderNpi": null,
"senderTon": null,
"sessionId": "",
"status": "success",
"statusCode": 1,
"tag": null,
"tokenLength": null,
"tokenType": null,
"type": "totp",
"validity": null,
"validUntilDateTime": null,
"webHook": null,
"_links": {
"self": {
"href": "https:\/\/\/v1\/verification\/submit\/eu-01-1.7926.ver5955ec8f6e9640.25672922"
}
}
}
},
"_links": {
"self": {
"href": "https:\/\/\/v1\/totp\/"
}
}
}
HTTP Endpoint
GET /v1/totp/<IDENTIFIER>?token=<TOKEN>
Arguments
Key | Type | Description |
---|---|---|
identifier |
String | Required. The identifier is a unique identifier of the user, e.g. an email address. The identifier will be visible in the Silverstreet Authenticator app as the application name. |
token |
String | Required. The TOTP token entered by the user and you want to verify with the generated TOTP for the user. |
Check status TOTP
Example get status of a TOTP:
curl /v1/totp/ \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>"
The response looks like this:
{
"identifier": "",
"issuer": "Silver",
"uri": null,
"verification": null,
"_links": {
"self": {
"href": "https:\/\/\/v1\/totp\/"
}
}
}
HTTP Endpoint
GET /v1/totp/<IDENTIFIER>
Arguments
Key | Type | Description |
---|---|---|
identifier |
String | Required. The identifier is a unique identifier of the user, e.g. an email address. The identifier will be visible in the Silverstreet Authenticator app as the application name. |
Delete TOTP
Example delete a TOTP:
curl -X DELETE /v1/totp/ \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>"
HTTP Endpoint
DELETE /v1/totp/<IDENTIFIER>
Arguments
Key | Type | Description |
---|---|---|
identifier |
String | Required. The identifier is a unique identifier of the user, e.g. an email address. |
SMS (MT)
Properties
SMS messages are represented as follows:
{
"applicationTag": "test",
"body": "Body of the SMS",
"callbackUrl": null,
"createdDateTime": "",
"dcs": null,
"messageId": "eu-01-1.18667.sms583d64765f6b28.36322430",
"networkCode": 12345,
"pid": null,
"reasonCode": 0,
"recipient": "",
"resultType": 0,
"salesPrice": 0.001,
"salesPriceCurrencyCode": "eur",
"scheduledDelivery": null,
"sender": "Hello world",
"senderNpi": 0,
"senderTon": 5,
"status": "delivered",
"statusCode": 1,
"tag": null,
"resultTimestamp": "",
"udh": null,
"validity": 259200,
"validUntilDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/sms\/submit\/eu-01-1.18667.sms583d64765f6b28.36322430"
}
}
}
Property | Type | Description |
---|---|---|
applicationTag |
String | Not null. The application used for sending the SMS. |
body |
String | Not null. The body as specified when sending the SMS. |
callbackUrl |
String | Can be null. The callback URL specified when sending the SMS. Our system will call this URL to return the delivery report of the SMS. |
createdDateTime |
String | Not null. The datetime the SMS was received by the API. The datetime is in ISO-8601 format. |
dcs |
Integer | Can be null. The DCS value as specified when sending the SMS. |
messageId |
String | Not null. The unique identifier, generated by the API, of the SMS. |
networkCode |
String | Can be null. The network code of the operator the mobile number is subscribed to. The network code is the MCC (Mobile Country Code) and MNC (Mobile Network Code) concatenated. |
pid |
Integer | Can be null. The PID value as specified when sending the SMS. |
reasonCode |
Integer | Can be null. When the SMS is rejected or could not be delivered a reasonCode is given explaining the cause of the rejection. See further down below for an overview of possible reasonCodes |
recipient |
String | Not null. The phone number as specified when sending the SMS. |
resultType |
Integer | Not null. The result type specified when sending the SMS. Possible values can be found in the table below. |
salesPrice |
Float | Can be null. The sales price of the SMS. |
salesPriceCurrencyCode |
String | Can be null. The currency code of the salesPrice field. The currency code is defined by the currency of your wallet. The currencyCode is in the 3-digit ISO 4217 code format. |
scheduledDelivery |
String | Can be null. The scheduled delivery time as specified when sending the SMS. |
sender |
String | Not null. The sender of the SMS as specified when sending the SMS. |
senderNpi |
Integer | Can be null. The senderNpi of the SMS as specified when sending the SMS or the automatically detected value by the API. See our tutorial 'Sender' for more information. |
senderTon |
Integer | Can be null. The senderTon of the SMS as specified when sending the SMS or the automatically detected value by the API. See our tutorial 'Sender' for more information. |
status |
String | Not null. The status of the SMS. The status and statusCode
fields
are bound together and can have the values as can be found in the table below. |
statusCode |
Integer | Not null. See status field for more information. |
tag |
String | Can be null. The tag as specified when sending the SMS. |
resultTimestamp |
String | Can be null. The timestamp when the message is delivered to the mobile phone. |
udh |
String | Can be null. The UDH as specified when sending the SMS. |
validity |
Integer | Not null. The validity in seconds as specified when sending the SMS or the default value (60). |
validUntilDateTime |
String | Can be null. The datetime until when the SMS is valid. This is calculated by the API based on the validity field. |
The resultType
field can have the following values:
Value | Description |
---|---|
0 | No results (default) |
1 | Callback (you have to specify the callbackUrl) |
2 | Polling |
3 | Callback & polling (you have to specify the callbackUrl) |
The status
and statusCode
fields can have the following values:
Code | Status | Description |
---|---|---|
0 | no status |
The SMS is received by our system. This is a temporary status, a final status will follow later. |
1 | delivered |
The SMS is successfully delivered to the mobile phone. |
2 | rejected |
The SMS is rejected by the system and is not sent to the phone. The reasonCode field indicates the reason why it is rejected. See further down below for an overview of possible reasonCodes. |
3 | expired |
The SMS is expired as it could not be delivered within the specified validity time. |
4 | enroute |
The SMS is on it's way in the mobile network and will be tried to deliver at a later moment. This is a temporary status, a final status will follow later. |
5 | buffered |
The SMS is buffered in a queue in the mobile network and will be tried to deliver at a later moment. This is a temporary status, a final status will follow later. |
6 | accepted |
The SMS is accepted by the mobile network and will be tried to deliver at a later moment. This is a temporary status, a final status will follow later. |
7 | undelivered |
The SMS could not be delivered. |
8 | deleted |
The SMS is deleted and will not be delivered. |
9 | unknown |
The SMS could not be delivered due to an unknown reason. |
Submit simple SMS
Submit a simple SMS:
curl -X POST /v1/sms/submitsimple \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>" \
-d '{
"recipients" : [""],
"body" : "Body of the sms",
"sender" : "Hello world"
}'
The response will look like this:
{
"_links": {
"self": {
"href": "https:\/\/\/v1\/sms\/submit"
}
},
"_embedded": {
"items": [
{
"applicationTag": "test",
"body": "Body of the SMS",
"callbackUrl": null,
"createdDateTime": "",
"dcs": null,
"messageId": "eu-01-1.18667.sms583d64765f6b28.36322430",
"networkCode": null,
"pid": null,
"reasonCode": null,
"recipient": "",
"resultType": 0,
"salesPrice": null,
"salesPriceCurrencyCode": null,
"scheduledDelivery": null,
"sender": "Hello world",
"senderNpi": 0,
"senderTon": 5,
"status": "no status",
"statusCode": 0,
"tag": null,
"resultTimestamp": null,
"udh": null,
"validity": 259200,
"validUntilDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/sms\/submit\/eu-01-1.18667.sms583d64765f6b28.36322430"
}
}
}
]
},
"total_items": 1
}
When submitting a simple SMS, the API will split up long SMS into multiple parts as an SMS has a maximum length. Check our tutorial 'Concatenated/long SMS' for more information on concatenated SMS.
HTTP Endpoint
POST /v1/sms/submitsimple
Arguments
Key | Type | Description |
---|---|---|
recipients |
Array | Required. It should be an array of phone numbers (in string format), in international format, for the SMS. At least 1 number must be set and maximum 1000. |
body |
String | Required. The body of the SMS. The API will automatically determine if the body is Unicode or not and when the body is too long for a single SMS the API will automatically split up the body into multiple parts. The maximum number of concatenated parts is 9. See our tutorials 'Unicode' and 'Concatenated/long SMS' for more information. |
sender |
String | Required. The sender is what the receiver of the SMS see as the submitter of the SMS. See our tutorial 'Sender' for more information. When it is numeric the maximum length is 17 digits, when it is alphanumeric the maximum length is 11. |
senderTon |
String | Optional. If it is not set the API will automatically detect the value. See our tutorial 'Sender' for more information. |
senderNpi |
String | Optional. If it is not set the API will automatically detect the value. See our tutorial 'Sender' for more information. |
pid |
String | Optional. Can be used to send hidden SMS. Allowed values: 0-255. See also GSM specification. |
scheduledDelivery |
String | Optional. Datetime of scheduled delivery. Must be in ISO-8601 format, example: . |
tag |
String | Optional. The tag is a free text parameter you can use for your own reference. The maximum length of the tag is 30 characters. The tag parameter is returned in the result and you can use it for reporting purposes on your side. |
validity |
String | Optional. The validity specifies how long the message is valid. The validity is in seconds. If the message could not be delivered within this time, the message will expire and no more attempts will be made to deliver it. The minimum value of the validity is 5 seconds and the maximum value is 259200 seconds (= 72 hours). The default value is 259200 seconds. |
resultType |
String | Optional. The result type specified when sending the SMS. Possible values can be found in the table below. |
callbackUrl |
String | Required when resultType is set to 1 or 3. When the
callbackUrl is set, this URL will be used by our system to submit status
updates to you. This parameter is only allowed when the resultType
parameter is set to 1 or 3. |
The resultType
field can have the following values:
Value | Description |
---|---|
0 | No results (default) |
1 | Callback (you have to specify the callbackUrl) |
2 | Polling |
3 | Callback & polling (you have to specify the callbackUrl) |
Submit advanced SMS
Submit an advanced SMS:
curl -X POST /v1/sms/submit \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>" \
-d '{
"recipients" : [""],
"body" : "Body of the sms",
"sender" : "Hello world"
}'
The response will look like this:
{
"_links": {
"self": {
"href": "https:\/\/\/v1\/sms\/submit"
}
},
"_embedded": {
"items": [
{
"applicationTag": "test",
"body": "Body of the SMS",
"callbackUrl": null,
"createdDateTime": "",
"dcs": null,
"messageId": "eu-01-1.18667.sms583d64765f6b28.36322430",
"networkCode": null,
"pid": null,
"reasonCode": null,
"recipient": "",
"resultType": 0,
"salesPrice": null,
"salesPriceCurrencyCode": null,
"scheduledDelivery": null,
"sender": "Hello world",
"senderNpi": 0,
"senderTon": 5,
"status": "no status",
"statusCode": 0,
"tag": null,
"resultTimestamp": null,
"udh": null,
"validity": 259200,
"validUntilDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/sms\/submit\/eu-01-1.18667.sms583d64765f6b28.36322430"
}
}
}
]
},
"total_items": 1
}
HTTP Endpoint
POST /v1/sms/submit
Arguments
Key | Type | Description |
---|---|---|
recipients |
Array | Required. It should be an array of phone numbers (in string format), in international format, for the SMS. At least 1 number must be set and maximum 1000. |
body |
String | Required. This is a mandatory string parameter. The body of the SMS. The body shall be send in GSM-7 alphabet and the maximum length is 160 characters. When you want to send characters not in the GSM-7 alphabet you have to send it as Unicode. In that case you have to set the DCS to 8. The maximum length is in that case 70 characters. When you send a concatenated message, you have to set a UDH as well and the maximum length for GSM-7 is then 153 characters and for Unicode 67 characters. See our tutorials 'Unicode' and 'Concatenated/long SMS' for more information. |
sender |
String | Required. The sender is what the receiver of the SMS see as the submitter of the SMS. See our tutorial 'Sender' for more information. When it is numeric the maximum length is 17 digits, when it is alphanumeric the maximum length is 11. |
senderTon |
Integer | Optional. If it is not set the API will automatically detect the value. See our tutorial 'Sender' for more information. |
senderNpi |
Integer | Optional. If it is not set the API will automatically detect the value. See our tutorial 'Sender' for more information. |
pid |
Integer | Optional. Can be used to send hidden SMS. Allowed values: 0-255. See also GSM specification. |
dcs |
Integer | Optional. Can be used to mark body as Unicode (8). Allowed values: 0-255. See also GSM specification. |
udh |
String | Required for long SMS. Can only consist of hexadecimal characters. Length in this parameter divided by 2 is subtracted from the maximum body length. See also GSM specification. |
scheduledDelivery |
String | Optional. Datetime of scheduled delivery. Must be in ISO-8601 format, example: . |
tag |
String | Optional. The tag is a free text parameter you can use for your own reference. The maximum length of the tag is 30 characters. The tag parameter is returned in the result and you can use it for reporting purposes on your side. |
validity |
String | Optional. The validity specifies how long the message is valid. The validity is in seconds. If the message could not be delivered within this time, the message will expire and no more attempts will be made to deliver it. The minimum value of the validity is 5 seconds and the maximum value is 259200 seconds (= 72 hours). The default value is 259200 seconds. |
resultType |
String | Optional. The result type specified when sending the SMS. Possible values can be found in the table below. |
callbackUrl |
String | Required when resultType is set to 1 or 3. When the
callbackUrl is set, this URL will be used by our system to submit status
updates to you. This parameter is only allowed when the resultType
parameter is set to 1 or 3. |
The resultType
field can have the following values:
Value | Description |
---|---|
0 | No results (default) |
1 | Callback (you have to specify the callbackUrl) |
2 | Polling |
3 | Callback & polling (you have to specify the callbackUrl) |
Get SMS status
To get the SMS status:
curl /v1/sms/submit/<MESSAGE_ID> \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>"
The response will look like this:
{
"applicationTag": "test",
"body": "Body of the SMS",
"callbackUrl": null,
"createdDateTime": "",
"dcs": null,
"messageId": "eu-01-1.18667.sms583d64765f6b28.36322430",
"networkCode": 12345,
"pid": null,
"reasonCode": 0,
"recipient": "",
"resultType": 0,
"salesPrice": 0.001,
"salesPriceCurrencyCode": "eur",
"scheduledDelivery": null,
"sender": "Hello world",
"senderNpi": 0,
"senderTon": 5,
"status": "delivered",
"statusCode": 1,
"tag": null,
"resultTimestamp": "",
"udh": null,
"validity": 259200,
"validUntilDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/sms\/submit\/eu-01-1.18667.sms583d64765f6b28.36322430"
}
}
}
HTTP Endpoint
GET /v1/sms/submit/<MESSAGE_ID>
Arguments
Key | Type | Description |
---|---|---|
messageId |
String | Required. The unique identifier of the SMS. |
Get SMS delivery reports
To get SMS delivery reports:
curl /v1/sms/poll \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>"
The response will look like this:
{
"batchId": "12467857ea2d2f8867d3.73020448",
"count": 1,
"_embedded": {
"messages": [
{
"applicationTag": "test",
"body": "Body of the SMS",
"callbackUrl": null,
"createdDateTime": "",
"dcs": null,
"messageId": "eu-01-1.18667.sms583d64765f6b28.36322430",
"networkCode": 12345,
"pid": null,
"reasonCode": 0,
"recipient": "",
"resultType": 0,
"salesPrice": 0.001,
"salesPriceCurrencyCode": "eur",
"scheduledDelivery": null,
"sender": "Hello world",
"senderNpi": 0,
"senderTon": 5,
"status": "delivered",
"statusCode": 1,
"tag": null,
"resultTimestamp": "",
"udh": null,
"validity": 259200,
"validUntilDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/sms\/submit\/eu-01-1.18667.sms583d64765f6b28.36322430"
}
}
}
]
},
"_links": {
"self": {
"href": "https:\/\/\/v1\/sms\/poll\/12467857ea2d2f8867d3.73020448"
}
}
}
Depending on the value of the resultType
field when
submitting SMS, you can poll for SMS delivery reports. Each time you
check for delivery reports you will receive up to maximum 10 delivery
reports at a time. When you received the delivery reports you will need
to confirm them so that our system knows you received them correctly.
When you are using one of our libraries or SDK's you do not have to
confirm the delivery reports, it will be done for you, so you don't have
to confirm.
HTTP Endpoint
GET /v1/sms/poll
Arguments
None.
Confirm SMS delivery reports
To confirm SMS delivery reports:
curl -X DELETE /v1/sms/poll/<BATCH_ID> \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>"
HTTP Endpoint
DELETE /v1/sms/poll/<BATCH_ID>
Arguments
Key | Description |
---|---|
batchId |
The batchId returned when retrieving the SMS delivery reports. |
SMS delivery report webhook
The SMS delivery report will look like this:
{
"applicationTag": "test",
"body": "Body of the SMS",
"callbackUrl": null,
"createdDateTime": "",
"dcs": null,
"messageId": "eu-01-1.18667.sms583d64765f6b28.36322430",
"networkCode": 12345,
"pid": null,
"reasonCode": 0,
"recipient": "",
"resultType": 0,
"salesPrice": 0.001,
"salesPriceCurrencyCode": "eur",
"scheduledDelivery": null,
"sender": "Hello world",
"senderNpi": 0,
"senderTon": 5,
"status": "delivered",
"statusCode": 1,
"tag": null,
"resultTimestamp": "",
"udh": null,
"validity": 259200,
"validUntilDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/sms\/submit\/eu-01-1.18667.sms583d64765f6b28.36322430"
}
}
}
In case you have requested to receive the SMS delivery reports via a webhook, the system will do
a HTTP
POST
to your configured URL.
SMS reason codes
Reason code | Description |
---|---|
201 | Insufficient credit. |
202 | Recipient temporary not available (phone switched off, roaming, handset memory full, etc.). |
203 | Recipient permanent not available (invalid number, handset doesn't support SMS, blacklisted, etc.). |
204 | Permanent network error. |
205 | Temporary network error. |
206 | Incorrect message parameter. |
207 | Rejected due to account issue. |
208 | Rejected due to spam or illegal content. |
209 | Validity expired. |
299 | An unknown error occurred. |
Incoming SMS (MO)
Properties
Number lookups are represented as follows:
{
"body": "Hello world",
"createdDateTime": "",
"keyword": null,
"networkCode": null,
"recipient": "",
"sender": "Silver",
"udh": null
}
Property | Type | Description |
---|---|---|
body |
String | Not null. The body of the incoming SMS. |
createdDateTime |
Integer | The datetime the incoming SMS was received by our platform. The datetime is in ISO-8601 format. |
keyword |
String | If you have configured keyword for your VMN and the message begins with the keyword, the keyword will be set in this field. |
networkCode |
String | The network code of the operator of the mobile number who sent the SMS. The network code is the MCC (Mobile Country Code) and MNC (Mobile Network Code) concatenated. |
recipient |
String | The recipient is the mobile number when the MO is sent to, so the VMN configured for you. |
sender |
String | The mobile number who sent the SMS. |
udh |
String | When the mobile number who sent the SMS sent a long SMS, it will be split up by the network into parts. Each part will have a UDH which you can use to combine it to one text again. See our tutorial on Concatenated/long SMS for more details. |
Incoming SMS webhook
The incoming message looks like this:
{
"body": "Hello world",
"createdDateTime": "",
"keyword": null,
"networkCode": null,
"recipient": "",
"sender": "Silver",
"udh": null
}
In case an incoming SMS is received by our platform, the system will do a HTTP POST
to your
configured URL.
Number Lookup
Properties
Number lookups are represented as follows:
{
"applicationTag": "Default application",
"callbackUrl": null,
"countryCode": "es",
"createdDateTime": "",
"imsi": "",
"messageId": "eu-01-1.19910.nrl583d65f60cdc75.96102916",
"msc": null,
"networkCode": ,
"number": "",
"operator": "",
"reasonCode": 0,
"resultType": 0,
"salesPrice": 0.00011,
"salesPriceCurrencyCode": "eur",
"status": "delivered",
"statusCode": 1,
"tag": null,
"resultTimestamp": "",
"validity": 60,
"validUntilDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/numberlookup\/submit\/eu-01-1.19910.nrl583d65f60cdc75.96102916"
}
}
}
Property | Type | Description |
---|---|---|
applicationTag |
String | Not null. The application used for sending the Number Lookup. |
callbackUrl |
String | Can be null. The callback URL specified when sending the Number Lookup. Our system will call this URL to return the result of the Number Lookup. |
countryCode |
String | Can be null. A two digit ISO 3166-1 alpha-2 code of the country of the operator the mobile number is subscribed to. |
createdDateTime |
String | Not null. The datetime the Number Lookup was received by the API. The datetime is in ISO-8601 format. |
imsi |
String | Can be null. The IMSI (International Mobile Subscriber Identity) of the SIM card the mobile number is linked to. |
messageId |
String | Not null. The unique identifier, generated by the API, of the Number Lookup. |
msc |
String | Can be null. The MSC (Mobile Switching Center) of the operator the mobile phone is currently registered to. This can be used to identify if a mobile phone is currently roaming or not. |
networkCode |
Integer | Can be null. The network code of the operator the mobile number is subscribed to. The network code is the MCC (Mobile Country Code) and MNC (Mobile Network Code) concatenated. |
number |
String | Not null. The phone number as specified when sending the Number Lookup. |
operator |
String | Can be null. The name of the operator the mobile number is subscribed to. |
reasonCode |
Integer | Can be null. When the Number Lookup is rejected or could not be performed a reasonCode is given explaining the cause of the rejection. See further down below for an overview of possible reasonCodes |
resultType |
Integer | Can be null. The result type specified when sending the Number Lookup. Possible values can be found in the table below. |
salesPrice |
Float | Can be null. The sales price of the Number Lookup. |
salesPriceCurrencyCode |
String | Can be null. The currency code of the salesPrice field. The currency code is defined by the currency of your wallet. The currencyCode is in the 3-digit ISO 4217 code format. |
status |
String | Not null. The status of the SMS. The status and statusCode
fields
are bound together and can have the values as can be found in the table below. |
statusCode |
Integer | Not null. See status field for more information. |
tag |
String | Can be null. The tag as specified when sending the Number Lookup. |
resultTimestamp |
String | Can be null. The timestamp when the Number Lookup was performed. |
validity |
Integer | Not null. The validity in seconds as specified when sending the Number Lookup or the default value (60). |
validUntilDateTime |
String | Can be null. The datetime until when the Number Lookup is valid. This is calculated by the API based on the validity field. |
The resultType
field can have the following values:
Value | Description |
---|---|
0 | No results (default) |
1 | Callback (you have to specify the callbackUrl) |
2 | Polling |
3 | Callback & polling (you have to specify the callbackUrl) |
The status
and statusCode
fields can have the following values:
Code | Status | Description |
---|---|---|
0 | no status |
The Number Lookup is received by our system. This is a temporary status, a final status will follow later. |
1 | delivered |
The Number Lookup is successfully performed. |
2 | rejected |
The Number Lookup is rejected by the system and is not performed. The reasonCode field indicates the reason why it is rejected. See further down below for an overview of possible reasonCodes. |
3 | expired |
The Number Lookup is expired as it could not be performed within the specified validity time. |
4 | enroute |
The Number Lookup is on it's way in the mobile network and will be tried to perform at a later moment. This is a temporary status, a final status will follow later. |
5 | buffered |
The Number Lookup is buffered in a queue in the mobile network and will be tried to perform at a later moment. This is a temporary status, a final status will follow later. |
6 | accepted |
The Number Lookup is accepted by the mobile network and will be tried to perform at a later moment. This is a temporary status, a final status will follow later. |
7 | undelivered |
The Number Lookup could not be performed. |
8 | deleted |
The Number Lookup is deleted and will not be performed. |
9 | unknown |
The Number Lookup could not be performed due to an unknown reason. |
Submit number lookup
Submit a simple SMS:
curl -X POST /v1/numberlookup/submit \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>" \
-d '{
"numbers" : [""]
}'
The response will look like this:
{
"_links": {
"self": {
"href": "https:\/\/\/v1\/numberlookup\/submit"
}
},
"_embedded": {
"items": [
{
"applicationTag": "Default application",
"callbackUrl": null,
"countryCode": null,
"createdDateTime": "",
"imsi": null,
"messageId": "eu-01-1.19910.nrl583d65f60cdc75.96102916",
"msc": null,
"networkCode": null,
"number": "",
"operator": null,
"reason": null,
"resultType": 0,
"salesPrice": null,
"salesPriceCurrencyCode": null,
"status": "no status",
"statusCode": 0,
"tag": null,
"resultTimestamp": null,
"validity": 60,
"validUntilDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/numberlookup\/submit\/eu-01-1.19910.nrl583d65f60cdc75.96102916"
}
}
}
]
},
"total_items": 1
}
HTTP Endpoint
POST /v1/numberlookup/submit
Arguments
Key | Type | Description |
---|---|---|
numbers |
Array | Required. The phone numbers in international format you want to perform a number lookup for. |
tag |
Array | Optional. The tag is a free text parameter you can use for your own reference. The maximum length of the tag is 30 characters. The tag parameter is returned in the result and you can use it for reporting purposes on your side. |
validity |
Array | Optional. The validity specifies how long the Number Lookup is valid. The validity is in seconds. If the Number Lookup could not be performed within this time, the Number Lookup is expired. The minimum value of the validity is 5 seconds and the maximum value is 259200 seconds (= 72 hours). The default value is 259200 seconds. |
resultType |
Array | Optional. The result type specified when sending the Number Lookup. Possible values can be found in the table below. |
callbackUrl |
Array | Required when resultType is set to 1 or 3. When the
callbackUrl is set, this URL will be used by our system to submit status
updates to you. This parameter is only allowed when the resultType
parameter is set to 1 or 3. |
The resultType
field can have the following values:
Value | Description |
---|---|
0 | No results (default) |
1 | Callback (you have to specify the callbackUrl) |
2 | Polling |
3 | Callback & polling (you have to specify the callbackUrl) |
Get number lookup status
To get the Number Lookup status:
curl /v1/numberlookup/submit/<MESSAGE_ID> \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>"
The response will look like this:
{
"applicationTag": "Default application",
"callbackUrl": null,
"countryCode": "es",
"createdDateTime": "",
"imsi": "",
"messageId": "eu-01-1.19910.nrl583d65f60cdc75.96102916",
"msc": null,
"networkCode": ,
"number": "",
"operator": "",
"reasonCode": 0,
"resultType": 0,
"salesPrice": 0.00011,
"salesPriceCurrencyCode": "eur",
"status": "delivered",
"statusCode": 1,
"tag": null,
"resultTimestamp": "",
"validity": 60,
"validUntilDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/numberlookup\/submit\/eu-01-1.19910.nrl583d65f60cdc75.96102916"
}
}
}
HTTP Endpoint
GET /v1/numberlookup/submit/<MESSAGE_ID>
Arguments
Key | Type | Description |
---|---|---|
messageId |
String | Required. The messageId returned with the verification submit. |
Get number lookup results
To get Number Lookup results:
curl /v1/numberlookup/poll \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>"
The response will look like this:
{
"batchId": "12467857ea2d2f8867d3.73020448",
"count": 1,
"_embedded": {
"messages": [
{
"applicationTag": "Default application",
"callbackUrl": null,
"countryCode": "es",
"createdDateTime": "",
"imsi": "",
"messageId": "eu-01-1.19910.nrl583d65f60cdc75.96102916",
"msc": null,
"networkCode": ,
"number": "",
"operator": "",
"reason": 0,
"resultType": 0,
"salesPrice": 0.00011,
"salesPriceCurrencyCode": "eur",
"status": "delivered",
"statusCode": 1,
"tag": null,
"resultTimestamp": "",
"validity": 60,
"validUntilDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/numberlookup\/submit\/eu-01-1.19910.nrl583d65f60cdc75.96102916"
}
}
}
]
},
"_links": {
"self": {
"href": "https:\/\/\/v1\/numberlookup\/poll\/12467857ea2d2f8867d3.73020448"
}
}
}
Depending on the value of the resultType
field when
submitting the Number Lookup, you can poll for Number Lookup results.
Each time you check for delivery reports you will receive up to maximum
10 results at a time. When you received the results you will need to
confirm them so that our system knows you received them correctly. When
you are using one of our libraries or SDK's you do not have to confirm
the results, it will be done for you, so you don't have to confirm.
HTTP Endpoint
GET /v1/numberlookup/poll
Arguments
None.
Confirm Number Lookup results
To confirm Number Lookup results:
curl -X DELETE /v1/numberlookup/poll/<BATCH_ID> \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>"
HTTP Endpoint
DELETE /v1/numberlookup/poll/<BATCH_ID>
Arguments
Key | Description |
---|---|
batchId |
The batchId returned when retrieving the Number lookup results. |
Number lookup result webhook
The number lookup result will look like this:
{
"applicationTag": "Default application",
"callbackUrl": null,
"countryCode": "es",
"createdDateTime": "",
"imsi": "",
"messageId": "eu-01-1.19910.nrl583d65f60cdc75.96102916",
"msc": null,
"networkCode": ,
"number": "",
"operator": "",
"reasonCode": 0,
"resultType": 0,
"salesPrice": 0.00011,
"salesPriceCurrencyCode": "eur",
"status": "delivered",
"statusCode": 1,
"tag": null,
"resultTimestamp": "",
"validity": 60,
"validUntilDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/numberlookup\/submit\/eu-01-1.19910.nrl583d65f60cdc75.96102916"
}
}
}
In case you have requested to receive the number lookup results via a webhook, the system will do
a HTTP
POST
to your configured URL.
Number Lookup Reason codes
Reason code | Description |
---|---|
1 | Absent subscriber (phone is switched off, phone out of coverage, roaming, etc.). |
9 | Unknown subscriber (number not known in network). |
13 | Operator barred the number. |
30 | Operator cannot be determined based on the number therefore no number lookup can be performed. |
53 | Rejected as you are not allowed to perform number lookups for this operator/country. |
61 | An unknown error occurred. |
75 | Number lookup aborted due to network issues. |
Testing
Introduction
We offer an easy way to test your integration of our API into your system. Free of charge.
To use our sandbox environment you have to use a test application. Go to the applications list in our portal and get the API key of a test application. If you do not have a test application yet, you can easily create one. Click on 'Add application', enter a name you want to call the application, select the 'Test application' checkbox and press the Create button. When the application is created, open it and there you see the API key of the test application and you can start sending test messages.
How it works:
Each Silverstrete API call you do with the test API key is validated as normal,
so when
you send incorrect parameters the call will be rejected (see Errors for more details on the possible errors). When the call is valid,
the
Silverstreet API checks the last 5 digits of the phone number you set. Based on those last
digits the
testing environment will influence the behaviour of the message. How it behaves depends on the
type of
message you want to send and the last 5 digits you set.
Notes:
- You will not be charged for these test calls and they will not be sent to the phone.
- Regardless of the currency of your wallet, the sandbox will always return the currency code 'usd'.
- You will not see the messages in the statistics or be able to find them in the message details.
If you are missing an option to cover a test case, please contact us and we will add that option.
Verification
With the testing environment you can fully test your verification flow. By filling in the phone number you can control the test verification. In the table below you can find an overview of the possible last 5 digits of the phone number. Anything not described in the table will have undefined behaviour but can be used in the future to cover other test scenarios.
Key | Type | Description | |
---|---|---|---|
00XXX |
0 | no status | |
01XXX |
1 | success | |
02XXX |
2 | rejected | Last 3 digits number (Reason codes) |
03XXX |
3 | expired | |
04XXX |
4 | failed |
In all these cases the verification is accepted by the API, so you will get a HTTP status code in the range of 2xx. After the call is accepted the verification will have the status as defined in the table.
When you request a test verification, a token will be generated as well. The generated token will have a defined value based on the token type (default value: numeric) and length (default value: 6) you set as you can see in this table:
Token length | Numeric | Alphanumeric |
---|---|---|
4 |
0123 | A123 |
5 |
01234 | A1234 |
6 |
012345 | A12345 |
7 |
0123456 | A123456 |
8 |
01234567 | A1234567 |
9 |
012345678 | A12345678 |
10 |
0123456789 | A123456789 |
Example 1 - Test normal verification flow
To test the normal verification flow, submit a verification with a recipient number ending with '00xxx'. If you do not specify the tokenType and tokenLength, the token of this verification will be '012345'. So if you want to test the response when the token is valid enter the token 012345 or if you want to test the response for an invalid token enter any token other then '012345'. If you want to test the response for an expired token wait till the validity is expired, by default 60 seconds, and then verify the token or use a phone number ending with '03xxx'.
Example 2 - Test verify a successful token again
In this case the verification your submitted verification will directly go the status 'success'. So when you perform a verifyToken on it, you will a HTTP status '423 - Locked' with errorCode 101.
Example 3 - Test verify an expired verification
In this example we submit a verification where the verification will directly be set to expired. When you verify the token you will get the response that it is expired. Submit a verification with a recipient number ending with '03xxx'. When you verify the token you will get the HTTP status code '423 - Locked' with errorCode 102.
Verification widget
With the testing environment you can fully test your verification widget flow. By filling in the phone number you can control the test verification for sms and call. When you set a recipient ending with '00000', you can use the token '012345' as a valid token. When you set another recipient, the token will be a random number (and therefor hard to enter the correct token ;-)).
For testing backup codes in the widget, you first need to create backup codes using a test API key, see Testing backup codes for more details.
To submit the verification:
curl -X POST /v1/verification/submit \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>" \
-d '{
"recipient" : "6112340x000",
}'
curl -X POST /v1/verification/submit \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>" \
-d '{
"recipient" : "6112340x000",
}'
To verify the verification with the correct token:
curl -X POST /v1/verification/submit/<MESSAGE_ID>?token=012345 \
-u "silverstreet:<API_KEY>" \
curl -X POST /v1/verification/submit/<MESSAGE_ID>?token=012345 \
-u "silverstreet:<API_KEY>" \
Example 1 result in:
{
"errorCode": 101,
"type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
"title": "Locked",
"status": 423,
"detail": "You are only allowed to check a certain token once."
}
Example 2 result in:
{
"errorCode": 102,
"type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
"title": "Locked",
"status": 423,
"detail": "Verification expired, validity expired on: "
}
Example 3 result in:
{
"errorCode": 102,
"type": "http:\/\/www.w3.org\/Protocols\/rfc2616\/rfc2616-sec10.html",
"title": "Locked",
"status": 423,
"detail": "Verification expired, validity expired on: "
}
Backup codes
With the testing environment you can easily test your backup code flow. When you create backup codes for the identifier you have set, a predefined set of backup codes will be returned. These backup codes can be used to test, however in test modes they are only available for 7 days. After that the backup codes are removed.
The predefined test backup codes are:
{
"00000000",
"11111111",
"22222222",
"33333333",
"44444444",
"55555555",
"66666666",
"77777777",
"88888888",
"99999999"
}
SMS
With the testing environment you can fully test your SMS flow. By filling in the phone number you can control the test SMS, including delivery reports. In the table below you can find an overview of the possible last 5 digits of the phone number. Anything not described in the table will have undefined behaviour but can be used in the future to cover other test scenarios.
Last 5 digits number | Status code | Status text | Reason code |
---|---|---|---|
00XXX |
0 | no status | |
01XXX |
1 | delivered | |
02XXX |
2 | rejected | Last 3 digits number (Reason codes) |
03XXX |
3 | expired | Last 3 digits number (Reason codes) |
04XXX |
4 | enroute | |
05XXX |
5 | buffered | |
06XXX |
6 | accepted | |
07XXX |
7 | undelivered | Last 3 digits number (Reason codes) |
08XXX |
8 | deleted | Last 3 digits number (Reason codes) |
09XXX |
9 | unknown | Last 3 digits number (Reason codes) |
In all these cases the SMS is accepted by the API, so you will get a HTTP status code in the range of 2xx. After the call is accepted the SMS will have the status as defined in the table.
Example - Test SMS when out of credit
In this example we submit an SMS where it will be rejected due to insufficient credit (reason code 201). Submit an SMS with a recipient number ending with '03201'.
To submit the SMS:
curl -X POST /v1/sms/submitsimple \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>" \
-d '{
"recipient": ["61123403201" ],
"body": "This is a rejected message",
"sender": "SMS"
}'
curl -X POST /v1/sms/submitsimple \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>" \
-d '{
"recipient": ["61123403201" ],
"body": "This is a rejected message",
"sender": "SMS"
}'
To retrieve the message status after the submit:
curl /v1/sms/submitsimple/<MESSAGE_ID> \
-u "silverstreet:<API_KEY>" \
curl /v1/sms/submitsimple/<MESSAGE_ID> \
-u "silverstreet:<API_KEY>" \
Will result in:
{
"applicationTag": "Test",
"body": "This is a rejected message",
"callbackUrl": null,
"createdDateTime": ,
"dcs": 102,
"messageId": "asia-01-1.6323.sms58b81d6f43fd08.15384596",
"networkCode": 12345,
"pid": null,
"reasonCode": 201,
"recipient": "61123403201",
"resultTimestamp": "",
"resultType": 0,
"salesPrice": 0,
"salesPriceCurrencyCode": "usd",
"scheduledDelivery": null,
"sender": "Test",
"senderNpi": 0,
"senderTon": 5,
"status": "expired",
"statusCode": 3,
"tag": null,
"udh": null,
"validity": 259200,
"validUntilDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/sms\/submitsimple\/asia-01-1.6323.sms58b81d6f43fd08.15384596"
}
}
}
Number Lookup
With the testing environment you can fully test your Number Lookup flow. By filling in the phone number you can control the test Number Lookup, including delivery reports. In the table below you can find an overview of the possible last 5 digits of the phone number. Anything not described in the table will have undefined behaviour but can be used in the future to cover other test scenarios.
Last 5 digits number | Status code | Status text | Reason code |
---|---|---|---|
00XXX |
0 | no status | |
01XXX |
1 | delivered | |
02XXX |
2 | rejected | Last 3 digits number (Reason codes) |
03XXX |
3 | expired | Last 3 digits number (Reason codes) |
04XXX |
4 | enroute | |
05XXX |
5 | buffered | |
06XXX |
6 | accepted | |
07XXX |
7 | undelivered | Last 3 digits number (Reason codes) |
08XXX |
8 | deleted | Last 3 digits number (Reason codes) |
09XXX |
9 | unknown | Last 3 digits number (Reason codes) |
In all these cases the Number Lookup is accepted by the API, so you will get a HTTP status code in the range of 2xx. After the call is accepted the Number Lookup will have the status as defined in the table.
Example - Test Number Lookup with valid result
In this example we will submit a Number Lookup which will be performed successful and data is returned. Submit an SMS with a recipient number ending with '01xxx'.
To submit the Number Lookup:
curl -X POST /v1/numberlookup/submit \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>" \
-d '{
"recipient": ["61123401000" ]
}'
curl -X POST /v1/numberlookup/submit \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>" \
-d '{
"recipient": ["61123401000" ]
}'
To submit the Number Lookup:
curl /v1/numberlookup/submit/<MESSAGE_ID> \
-u "silverstreet:<API_KEY>" \
curl /v1/numberlookup/submit/<MESSAGE_ID> \
-u "silverstreet:<API_KEY>" \
Will result in:
{
"_links": {
"self": {
"href": "https:\/\/\/v1\/sms\/submitsimple\/asia-01-1.6323.sms58b81d6f43fd08.15384596"
}
},
"_embedded": {
"items": [
{
"applicationTag": "Test",
"callbackUrl": null,
"countryCode": null,
"createdDateTime": "",
"imsi": null,
"isPorted": "Unknown",
"isRoaming": "Unknown",
"messageId": "asia-01-1.6325.nrl58b81f79d3c749.10703469",
"msc": null,
"networkCode": null,
"number": "61123401000",
"operator": null,
"reasonCode": null,
"resultTimestamp": null,
"resultType": 0,
"salesPrice": null,
"salesPriceCurrencyCode": null,
"status": "no status",
"statusCode": "0",
"tag": null,
"validity": 259200,
"validUntilDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/sms\/submitsimple\/asia-01-1.6323.sms58b81d6f43fd08.15384596"
}
},
}
]
},
"total_items": 1,
}
Widget Guide
Introduction
In this guide we will explain the steps on how to use the Twizo widgets. The Twizo widgets are the easiest way to add 2FA to your website and works on desktops, tablets and mobile devices. If you need help after reading this guide, contact us at support@silverstreet.com.
We have 2 widgets to make the integration of our service in your website easier:
- Verification widget: This widget is used to verify a user during the login process of your website.
- Registration widget: This widget is used to register a user for the different verification types.
Try out the Twizo verification widget now by clicking the below button. We will simulate sending a token to you. The valid token you can enter is '012345'.
The verification widget supports all verification types to send the token to you and an option to resend if you did not receive it. Also you can show the user to which number the verification will be sent and you can personalise the widget by setting your own logo.
HTTPS requirements
The Twizo widgets are running via secure HTTPS connections. If you want to set your own logo URL, you have to make sure you set a HTTPS connections. If not, the logo will not be shown. We recommend to run your website over HTTPS as well to protect yourself from certain forms of man-in-the-middle attacks.
Verification widget
Integrating the Twizo verification widget is done in 3 simple steps:
- Create a verification session.
- Open the verification widget.
- Verify if the verification session was successful.
Let's explain the steps in more detail.
Step 1: Create a verification session
You start by creating a verification session. When doing that you can set certain parameters like which verification types you want to support, the phone number of the user, token length and type, etc. When the session is created you get a sessionToken. The sessionToken is needed to open the widget.
To create session token:
curl -X POST /v1/widget/session \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>" \
-d '{
"allowedTypes": ["sms","call" ]
"recipient": ""
}'
<?php
$widgetSession = $client->createWidgetSession( array("sms","call"));
$widgetSession = $client->setRecipient("");
$widgetSession = $client->create();
?>
Check our API documentation to see all options you can set when creating a verification session.
Will result in:
{
"sessionToken": "eu-01_1161130_wid59003566562fe8.59122114e17b",
"applicationTag": "Default application",
"bodyTemplate": "Your verification token is %token%",
"createdDateTime": "2017-04-26T05:51:34+00:00",
"dcs": null,
"issuer": null,
"language": null,
"recipient": "",
"sender": "Twizo",
"senderNpi": null,
"senderTon": null,
"tag": null,
"tokenLength": 6,
"tokenType": "numeric",
"requestedTypes": {
"sms",
"call"
],
"allowedTypes": {
"1": "sms",
"2": "call",
],
"validity": null,
"status": "no status",
"statusCode": 0,
"backupCodeIdentifier": null,
"status": [],
"verificationIds": [],
"verification": null,
"_links": {
"self": {
"href": "https:\/\/\/v1\/widget\/verification\/session\/eu-01_1161130_wid59003566562fe8.59122114e17b"
}
}
}
You will need to use the sessionToken you can find in the response and pass it to the widget, see step 2.
Step 2: Open the widget
Now let's open the widget. You need to include widget.js into your html page and open the widget to show it to the user. Apart from the session token you can do some additional settings like the logo you want to show and the recipient number where the token is sent to.
If malicious people were able to capture the sessionToken, the privacy of the user is still protected. Only if they have the sessionToken and the API key, they are able to collect e.g. the phone number of the user. So always make sure you keep your API key in a safe place.
The URL of the widget.js is: https://cdn.twizo.com/widget.js
Javascript code to open the widget:
Javacript integration:
<script>
const handler = TwizoWidget.configure({
sessionToken: sessionToken
});
handler.open(function (sessionToken, isError, errorCode, returnData) {
if (isError) {
//verification failed, user should not be logged in
alert('error: ' + errorCode);
} else {
//verification success, user can continue to login
alert('success for sessionToken: ' + sessionToken);
}
});
</script>
The options you can set for the widget are:
Parameter | Description |
---|---|
sessionToken |
This is a mandatory parameter. The sessionToken of the verification session you created. |
logoUrl |
This is an optional parameter. If you want to personalise the widget, you can set a
URL to
your logo here. We will reduce the size of the logo to 200 pixels wide and 90 pixels
high. Please note, as the widget is using HTTPS, the link to the logo must be HTTPS as well. See HTTPS for more information. |
recipient |
This is an optional parameter. If you set it, the widget will show it to the user to indicate where the token will be sent to. For privacy reasons we recommend not to specify the full number but e.g. only the last 4 digits. So instead of showing '61123456789' show '***6789'. |
askTrusted |
This is an optional parameter. Possible values are true or false. When it is set to true, the widget will show a checkbox, by default selected, with the text 'Trust this device for x days'. The x will be replaced with the number you fill in for 'trustedDays'. When the widget is closed, the return data contains a property isTrusted indicating if the checkbox was selected or not. |
trustedDays |
This is a mandatory parameter when askTrusted is set to true. You can specify the number to be shown in the sentence 'Trust this device for x days'. |
For security reasons we have set a maximum number of retries for the verification and a maximum time of the session. This to prevent users will perform unlimited unsuccessful verifications. The maximum retries is 5 and the maximum session time is 10 minutes.
When the user completed the verification flow, either by entering the correct token, cancelling, reaching maximum number of retries or reaching the maximum session time, the widget will be closed and you will get the sessionToken, isError (true or false), an errorCode (when isError == true) and returnData returned. The returnData will contain the isTrusted property when askTrusted is set to true.
The errorCodes property can be one of the following error codes:
errorCode | Description |
---|---|
|
When isError is true and the errorCode is empty ('') the user aborted the widget. |
101 |
Verification already verified. |
104 |
Verification failed, please contact your administrator |
200 |
Verification already used |
201 |
Verification timeout |
202 |
Max attempts reached |
301 |
Invalid request |
310 |
Verification failed, unable to start new verification |
311 |
Verification failed, unable to start new verification as the session is already verified or failed |
312 |
Verification failed, unable to start new verification as the session has been expired |
313 |
Verification failed, unable to start new verification as the max attempts has been reached |
Step 3: Verify if the verification session was successful
When the widget returned the isError == false the user entered the correct token. However to make sure the verification was indeed successful, you can get the status of the verification session. It is not mandatory to get the status of the session after the widget is closed, but we highly recommend this. Even though we have implemented the widget is a secure way, there are always ways for malicious people to, for example, influence the DOM.
To create session token:
curl -X POST /v1/widget/session/<SESSION_TOKEN>?recipient=<RECIPIENT> \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>"
<?php
$widgetSession = $client->getWidgetSession($widgetSession->getSessionToken(), $widgetSession->getRecipient());
?>
Note: to get the status of a session, you need to specify the sessionToken and the recipient number. You need to specify both as the API will check the combination so that malicious people cannot return a successful sessionToken of a different user.
Will result in:
{
"sessionToken": "eu-01_1161130_wid59003566562fe8.59122114e17b",
"applicationTag": "Default application",
"bodyTemplate": "Your verification token is %token%",
"createdDateTime": "2017-04-26T05:51:34+00:00",
"dcs": null,
"issuer": null,
"language": null,
"recipient": "",
"sender": "Twizo",
"senderNpi": null,
"senderTon": null,
"tag": null,
"tokenLength": 6,
"tokenType": "numeric",
"requestedTypes": {
"sms",
"call"
],
"allowedTypes": [
"1": "sms",
"2": "call"
],
"validity": null,
"status": "success",
"statusCode": 0,
"backupCodeIdentifier": null,
"status": [],
"verificationIds": [
"eu-01-1.17172.ver583d6255ae66f2.27354409",
"eu-01-1.18352.ver529c5e45ae72a2.83645283",
],
"verification": {
"applicationTag": "Default application",
"bodyTemplate": null,
"createdDateTime": "2017-04-26T05:51:34+00:00",
"dcs": null,
"issuer": null,
"language": null,
"messageId": "eu-01-1.18352.ver529c5e45ae72a2.83645283",
"reasonCode": null,
"recipient": "",
"salesPrice": 0.07,
"salesPriceCurrencyCode": "eur",
"sender": null,
"senderNpi": null,
"senderTon": null,
"sessionId": "eu-01_1161130_wid59003566562fe8.59122114e17b",
"status": "success",
"statusCode": 1,
"tag": null,
"tokenLength": null,
"tokenType": null,
"type": "sms",
"validity": null,
"validUntilDateTime": null,
"webHook": null,
"_links": {
"self": {
"href": "https:\/\/\/v1\/verification\/submit\/eu-01-1.18352.ver529c5e45ae72a2.83645283"
}
}
},
"_links": {
"self": {
"href": "https:\/\/\/v1\/widget\/verification\/session\/eu-01_1161130_wid59003566562fe8.59122114e17b"
}
}
}
The status field will show the status, in this case 'success'. When it is success you can continue to login the user, otherwise you can logout the user so he needs to login and do the verification again. For more information on the possible status codes, please check the API documentation.
That's it! These are all the steps you need to do to integrate our verification service into your application to enable 2FA.
Registration widget
Integrating the Twizo registration widget is done in 2 simple steps:
- Create a registration session.
- Open the registration widget.
Let's explain the steps in more detail.
Step 1: Create a registration session
You start by creating a registration session. When doing that you can set certain parameters like which verification types you want to support, the phone number of the user, etc. When the session is created you get a sessionToken. The sessionToken is needed to open the registration widget.
To create session token:
curl -X POST /v1/widget-register-verification/session \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf8" \
-u "silverstreet:<API_KEY>" \
-d '{
"recipient": "",
"backupCodeIdentifier": "me@silverstreet.com",
"totpIdentifier": "me@silverstreet.com",
"issuer": "Twizo",
}'
<?php
$widgetSession = $client->createWidgetRegisterSession( array("sms","call"));
$widgetSession = $client->setRecipient("");
$widgetSession = $client->create();
?>
Check our API documentation to see all options you can set when creating a registration session.
Will result in:
{
"sessionToken": "eu-01_1161130_wid5aab9dec9bca47.995159356758",
"applicationTag": "Default application",
"requestedTypes": [
"sms",
"call",
"totp",
"push",
"backupcode",
"facebook_messenger",
"telegram",
"line"
],
"registeredTypes": [
"sms",
"call",
"facebook_messenger",
"telegram"
],
"allowedTypes": [
"sms",
"call",
"totp",
"push",
"backupcode",
"facebook_messenger",
"telegram",
"line"
],
"recipient": "",
"totpIdentifier": "me@silverstreet.com",
"backupCodeIdentifier": "me@silverstreet.com",
"issuer": "Twizo",
"language": "en",
"status": "no status",
"statusCode": 0,
"createdDateTime": "",
"_links": {
"self": {
"href": "https:\/\/\/v1\/widget-register-verification\/session\/eu-01_1161130_wid5aab9dec9bca47.995159356758"
}
}
}
You will need to use the sessionToken you can find in the response and pass it to the registration widget, see step 2.
Step 2: Open the registration widget
Now let's open the registration widget. You need to include widget.js into your html page and open the widget to show it to the user. Apart from the session token you can do some additional settings like the logo you want to show and the recipient number where the token is sent to.
If malicious people were able to capture the sessionToken, the privacy of the user is still protected. Only if they have the sessionToken and the API key, they are able to collect e.g. the phone number of the user. So always make sure you keep your API key in a safe place.
The URL of the widget.js is: https://cdn.twizo.com/widget.js
Javacript integration:
<script>
const handler = TwizoRegisterWidget.configure({
sessionToken: sessionToken
});
handler.open(function (sessionToken, isError, errorCode, registeredTypes) {
if (isError) {
return console.log('Got an error: ' + errorCode);
}
//Success...
});
</script>
The options you can set for the registration widget are:
Parameter | Description |
---|---|
sessionToken |
This is a mandatory parameter. The sessionToken of the registration session you created. |
logoUrl |
This is an optional parameter. If you want to personalise the widget, you can set a
URL to
your logo here. We will reduce the size of the logo to 200 pixels wide and 90 pixels
high. Please note, as the widget is using HTTPS, the link to the logo must be HTTPS as well. See HTTPS for more information. |
recipient |
This is an optional parameter. If you set it, the widget will show it to the user to indicate where the token will be sent to. For privacy reasons we recommend not to specify the full number but e.g. only the last 4 digits. So instead of showing '61123456789' show '***6789'. |
For security reasons we have set a maximum time of the session. The maximum session time is 15
minutes.
When the widget is closed you will get the sessionToken, isError (true or false), an errorCode
(when
isError == true) and registeredTypes returned. The registeredTypes will contain an array with
the
verification types the user has now registered for.
The errorCodes property can be one of the following error codes:
errorCode | Description |
---|---|
|
When isError is true and the errorCode is empty ('') the user aborted the widget. |
101 |
The sessionToken was already used before and cannot be used again to open the registration widget. |
102 |
The session time expired. The maximum session time is 15 minutes. |
105 |
The user is trying to register for a verification type which is not allowed. This can happen when the registration widget is open and you disable a verification type for your users. |
201 |
The account used for the registration session was disabled after the registration widget was opened. |
202 |
The verification service for the account used for the registration session was disabled after the registration widget was opened. |
301 |
The bio voice registration failed. There can be numerous reasons why it failed, e.g. the country of the user is not supported for bio voice. Please contact support for more information. |
That's it! These are all the steps you need to do to integrate our verification service into your application to enable 2FA.
Browser support
All recent versions of the major browsers on both desktops and mobiles are supported. If you have an issue with the Twizo widgets on a specific browser, please contact us so we can improve its support.