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.

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

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.

Authentication

To authorize, use this code:

<?php
//For SMS, Number Lookup and Verification:
$client = Silverstreet\Api\Silverstreet::getInstance('<API_KEY>', 'api-eu-01.silverstreet.com');

//For E-mail, Push and Address book:
$config = new \Silverstreet\EmailClient\Configuration();
$config->setUsername('silverstreet');
$config->setPassword('<API_KEY>');
$config->setHost('https://api-eu-01.silverstreet.com');

$client = new Silverstreet\EmailClient\Api\EmailApi(
    new GuzzleHttp\Client(),
    $config
);

//Note: Replace EmailClient and EmailApi in the above samples with the respective type, e.g. PushClient/PushApi.

curl -X POST https://api-eu-01.silverstreet.com/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": 13.37,
    "currencyCode": "usd",
    "freeVerifications": 42,
    "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 https://api-eu-01.silverstreet.com/v1/wallet/getbalance \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$balance = $client->getBalance();
?>

The response looks like this:

{
    "credit": 13.37,
    "currencyCode": "usd",
    "freeVerifications": 42,
    "wallet": "Default wallet"
}

Retrieve the credit balance of your wallet.

HTTP Endpoint

GET /wallet/v1/getbalance

Arguments

None.

Balance alarm webhook

The data we will send to you looks like this:

{
    "credit": 13.37,
    "currencyCode": "usd",
    "freeVerifications": 42,
    "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": "2016-11-30T13:17:44+00:00",
    "dcs": 0,
    "issuer": null,
    "language": null,
    "messageId": "eu-01-1.25569.ver583ed178a52521.24988267",
    "reasonCode": null,
    "recipient": "1234567890",
    "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": "2016-11-30T13:18:14+00:00",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/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 https://api-eu-01.silverstreet.com/v1/verification/submit \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>" \
    -d '{
        "recipient" : "1234567890"
    }'

<?php
$verification = $client->createVerification('1234567890');
$verification->send();
?>

The response looks like this:

{
    "applicationTag": "Default application",
    "tokenLength": null,
    "tokenType": null,
    "createdDateTime": "2016-11-29T11:11:17+00:00",
    "dcs": null,
    "issuer": "Silver",
    "language": null,
    "messageId": "eu-01-1.17172.ver583d6255ae66f2.27354409",
    "reasonCode": null,
    "recipient": "1234567890",
    "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:\/\/api-eu-01.silverstreet.com\/v1\/verification\/submit\/eu-01-1.17172.ver583d6255ae66f2.27354409"
        }
    }
}

HTTP Endpoint

POST /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: biovoice, 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 https://api-eu-01.silverstreet.com/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>"

<?php
$result = $client->getTokenResult($verification->getMessageId(), '123456');
?>

The response looks like this:

{
    "applicationTag": "Default application",
    "tokenLength": 6,
    "tokenType": "numeric",
    "createdDateTime": "2016-11-30T13:17:44+00:00",
    "dcs": 0,
    "issuer": null,
    "language": null,
    "messageId": "eu-01-1.25569.ver583ed178a52521.24988267",
    "reasonCode": null,
    "recipient": "1234567890",
    "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": "2016-11-30T13:18:14+00:00",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/verification\/submit\/eu-01-1.25569.ver583ed178a52521.24988267"
        }
    }
}

HTTP Endpoint

GET /verification/submit/:messageId?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 https://api-eu-01.silverstreet.com/v1/verification/submit/<MESSAGE_ID> \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$result = $client->getVerification($verification->getMessageId());
?>

The response looks like this:

{
    "applicationTag": "Default application",
    "tokenLength": 6,
    "tokenType": "numeric",
    "createdDateTime": "2016-11-29T11:16:03+00:00",
    "dcs": 0,
    "issuer": null,
    "language": null,
    "messageId": "eu-01-1.18667.ver583d637356cd58.88711156",
    "reasonCode": null,
    "recipient": "1234567890",
    "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": "2016-11-29T11:16:33+00:00",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/verification\/submit\/eu-01-1.18667.ver583d637356cd58.88711156"
        }
    }
}

HTTP Endpoint

GET /v1/verification/submit/:messageId

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": "2017-04-26T05:51:34+00:00",
    "dcs": null,
    "issuer": null,
    "language": null,
    "recipient": "601234500000",
    "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": "2017-04-26T05:51:34+00:00",
            "dcs": null,
            "issuer": null,
            "language": null,
            "messageId": "eu-01-1.18352.ver529c5e45ae72a2.83645283",
            "reasonCode": null,
            "recipient": "601234500000",
            "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:\/\/api-eu-01.silverstreet.com\/v1\/verification\/submit\/eu-01-1.18352.ver529c5e45ae72a2.83645283"
                }
            },
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/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 https://api-eu-01.silverstreet.com/v1/widget/session \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>" \
    -d '{
        "recipient" : "601234500000"
    }'

<?php
$widgetSession = $client->createWidgetSession(array('sms','call'));
$widgetSession->setRecipient('601234500000');
$widgetSession->create();
?>

The response will look like this:

{
    "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": "601234500000",
    "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:\/\/api-eu-01.silverstreet.com\/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, biovoice, push, totp, 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, 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 https://api-eu-01.silverstreet.com/v1/widget/session/:sessionToken?recipient=601234500000 \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$result = $client->getWidgetSession($widgetSession->getSessionToken(), $widgetSession->getRecipient());
?>

The response will look like this:

{
    "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": "601234500000",
    "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:\/\/api-eu-01.silverstreet.com\/v1\/widget\/verification\/session\/eu-01_1161130_wid59003566562fe8.59122114e17b"
        }
    }
}

HTTP Endpoint

GET /v1/widget/session/:sessionToken?recipient=:recipient&backupCodeIdentifier=:backupCodeIdentifier&totpIdentifier=:totpIdentifier

Arguments

Key	Type	Description
sessionToken	Array	Optional. The allowedTypes defines which verification types can be used with the widget. Possible values are: sms, call, biovoice, push, totp, 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": "601234500000",
    "totpIdentifier": null,
    "backupCodeIdentifier": null,
    "issuer": null,
    "language": "en",
    "status": "no status",
    "statusCode": 0,
    "createdDateTime": "2018-03-16T10:35:24+00:00",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/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 https://api-eu-01.silverstreet.com/v1/widget-register-verification/session \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>" \
    -d '{
        "recipient" : "601234500000"
    }'

<?php
$widgetSession = $client->createWidgetRegisterSession(array('sms','call'));
$widgetSession->setRecipient('601234500000');
$widgetSession->create();
?>

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": "601234500000",
    "totpIdentifier": null,
    "backupCodeIdentifier": null,
    "issuer": null,
    "language": "en",
    "status": "no status",
    "statusCode": 0,
    "createdDateTime": "2018-03-16T10:35:24+00:00",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/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, biovoice, push, totp, 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, 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": "1234567890",
    "amountOfCodesLeft": 10,
    "codes": [
        "73502977",
        "64553227",
        "61260614",
        "91387132",
        "74052942",
        "29371709",
        "22740780",
        "43369151",
        "51168501",
        "19402795"
    ],
    "createdDateTime": "2017-05-19T08:51:01+00:00",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/backupcode\/1234567890"
        }
    }
}

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 https://api-eu-01.silverstreet.com/v1/backupcode \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>" \
    -d '{
        "identifier" : "1234567890"
    }'

<?php
$backupCode = $client->createBackupCode('1234567890');
$backupCode->create();
?>

The response looks like this:

{
    "identifier": "1234567890",
    "amountOfCodesLeft": 10,
    "codes": [
        "73502977",
        "64553227",
        "61260614",
        "91387132",
        "74052942",
        "29371709",
        "22740780",
        "43369151",
        "51168501",
        "19402795"
    ],
    "createdDateTime": "2017-05-19T08:51:01+00:00",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/backupcode\/1234567890"
        }
    }
}

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 https://api-eu-01.silverstreet.com/v1/backupcode/1234567890?token=73502977 \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$backupCode = $client->getBackupCode('1234567890');
$backupCode->verify('73502977');
?>

The response looks like this:

{
    "identifier": "1",
    "amountOfCodesLeft": 9,
    "codes": [],
    "createdDateTime": "2017-05-19T13:06:40+00:00",
    "_embedded": {
        "verification": {
            "applicationTag": "Default application",
            "bodyTemplate": null,
            "createdDateTime": "2017-05-19T13:06:40+00:00",
            "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:\/\/api-eu-01.silverstreet.com\/v1\/verification\/submit\/eu-01-1.7926.ver5955ec8f6e9640.25672922"
                }
            }
        }
    },
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/backupcode\/1234567890"
        }
    }
}

HTTP Endpoint

GET /v1/backupcode/:identifier?token=:backupCode

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 https://api-eu-01.silverstreet.com/v1/backupcode/1234567890 \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$backupCode = $client->getBackupCode('1234567890');
?>

The response looks like this:

{
    "identifier": "1234567890",
    "amountOfCodesLeft": 9,
    "codes": [],
    "createdDateTime": "2017-05-19T13:06:40+00:00",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/backupcode\/1234567890"
        }
    }
}

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 https://api-eu-01.silverstreet.com/v1/backupcode/1234567890 \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"
    -d '{
        "identifier" : "1234567890"
    }'

<?php
$backupCode = $client->getBackupCode('1234567890');
$backupCode->update();
?>

The response looks like this:

{
    "identifier": "1234567890",
    "amountOfCodesLeft": 10,
    "codes": [
        "73502977",
        "64553227",
        "61260614",
        "91387132",
        "74052942",
        "29371709",
        "22740780",
        "43369151",
        "51168501",
        "19402795"
    ],
    "createdDateTime": "2017-05-19T08:51:01+00:00",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/backupcode\/1234567890"
        }
    }
}

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 https://api-eu-01.silverstreet.com/v1/backupcode/1234567890 \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$backupCode = $client->getBackupCode('1234567890');
$backupCode->delete();
?>

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": "1234567890",
    "issuer": "Silver",
    "uri": "otpauth:\/\/totp\/Silverstreet:1234567890?secret=QBC4NBVJO37VZJHDHLKLKM6CVZBBV7MCAWIUZQWOK3ATLIWWPGHA&issuer=Silver",
    "verification": null,
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/totp\/1234567890"
        }
    }
}

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 https://api-eu-01.silverstreet.com/v1/totp \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>" \
    -d '{
        "identifier" : "1234567890",
        "issuer": "Silver"
    }'

<?php
$totp = $client->createTotp('1234567890');
$totp->create();
?>

The response looks like this:

{
    "identifier": "1234567890",
    "issuer": "Silver",
    "uri": "otpauth:\/\/totp\/Silverstreet:1234567890?secret=QBC4NBVJO37VZJHDHLKLKM6CVZBBV7MCAWIUZQWOK3ATLIWWPGHA&issuer=Silver",
    "verification": null,
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/totp\/1234567890"
        }
    }
}

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 https://api-eu-01.silverstreet.com/v1/totp/1234567890?token=012345 \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$totp = $client->createTotp('1234567890');
$totp->verify('012345');
?>

The response looks like this:

{
    "identifier": "1234567890",
    "issuer": "Silver",
    "uri": null,
    "_embedded": {
        "verification": {
            "applicationTag": "Default application",
            "bodyTemplate": null,
            "createdDateTime": "2017-05-19T13:06:40+00:00",
            "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:\/\/api-eu-01.silverstreet.com\/v1\/verification\/submit\/eu-01-1.7926.ver5955ec8f6e9640.25672922"
                }
            }
        }
    },
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/totp\/1234567890"
        }
    }
}

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 https://api-eu-01.silverstreet.com/v1/totp/1234567890 \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$totp = $client->getTotp('1234567890');
?>

The response looks like this:

{
    "identifier": "1234567890",
    "issuer": "Silver",
    "uri": null,
    "verification": null,
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/totp\/1234567890"
        }
    }
}

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 https://api-eu-01.silverstreet.com/v1/totp/1234567890 \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$totp = $client->createTotp('1234567890');
$totp->delete();
?>

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.

Bio Voice

In order to use bio voice, a user first needs to register for it. Once the registration is completed, a subscription is created and a user can be verified via bio voice.

See tutorial 'Bio voice verification' for more information.

Create registration

Example create a bio voice registration:

curl -X POST https://api-eu-01.silverstreet.com/v1/biovoice/registration \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>" \
    -d '{
        "recipient" : "1234567890"
    }'

<?php
$bioVoice = $client->createBioVoiceRegistration('1234567890');
$bioVoice->create();
?>

The response looks like this:

{
    "createdDateTime": "2017-12-21T14:27:50+00:00",
    "language": null,
    "reasonCode": 0,
    "recipient": "1234567890",
    "registrationId": "7695.B015a3bc4e6a2b338.39633794",
    "salesPrice": 0.157675,
    "salesPriceCurrencyCode": "sgd",
    "status": "success",
    "statusCode": 1,
    "voiceSentence": "Verify me with my voicepin",
    "webHook": null,
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/biovoice\/registration\/7695.B015a3bc4e6a2b338.39633794"
        }
    }
}

HTTP Endpoint

POST /v1/biovoice/registration

Arguments

Key	Type	Description
recipient	String	Required. The phone number of the user.

Check status registration

Example get status of a bio voice registration:

curl https://api-eu-01.silverstreet.com/v1/biovoice/registration/1234567890 \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$bioVoice = $client->getBioVoiceRegistration('1234567890');
?>

The response looks like this:

{
    "createdDateTime": "2017-12-21T14:27:50+00:00",
    "language": null,
    "reasonCode": 0,
    "recipient": "1234567890",
    "registrationId": "7695.B015a3bc4e6a2b338.39633794",
    "salesPrice": null,
    "salesPriceCurrencyCode": null,
    "status": "no status",
    "statusCode": 0,
    "voiceSentence": "Verify me with my voicepin",
    "webHook": null,
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/biovoice\/registration\/7695.B015a3bc4e6a2b338.39633794"
        }
    }
}

HTTP Endpoint

GET /v1/biovoice/registration/:recipient

Arguments

Key	Type	Description
recipient	String	Required. The phone number of the user.

Check status subscription

Example get status of a bio voice subscription:

curl https://api-eu-01.silverstreet.com/v1/biovoice/subscription/1234567890 \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$bioVoice = $client->getBioVoiceSubscription('1234567890');?>

The response looks like this:

{
    "createdDateTime": "2017-12-21T14:53:49+00:00",
    "recipient": "1234567890",
    "voiceSentence": "Verify me with my voicepin",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/biovoice\/subscription\/1234567890"
        }
    }
}

HTTP Endpoint

GET /v1/biovoice/subscription/:recipient

Arguments

Key	Type	Description
recipient	String	Required. The phone number of the user.

Delete subscription

Example delete a bio voice subscription:

curl -X DELETE https://api-eu-01.silverstreet.com/v1/biovoice/subscription/<RECIPIENT> \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$bioVoice = $client->getBioVoiceSubscription('1234567890');
$bioVoice->delete();
?>

HTTP Endpoint

DELETE /v1/biovoice/subscription/:recipient

Arguments

Key	Type	Description
recipient	String	Required. The phone number of the user.

SMS (MT)

Properties

SMS messages are represented as follows:

{
    "applicationTag": "test",
    "body": "Body of the SMS",
    "callbackUrl": null,
    "createdDateTime": "2016-11-29T11:20:22+00:00",
    "dcs": null,
    "messageId": "eu-01-1.18667.sms583d64765f6b28.36322430",
    "networkCode": 12345,
    "pid": null,
    "reasonCode": 0,
    "recipient": "1234567890",
    "resultType": 0,
    "salesPrice": 0.001,
    "salesPriceCurrencyCode": "eur",
    "scheduledDelivery": null,
    "sender": "Hello world",
    "senderNpi": 0,
    "senderTon": 5,
    "status": "delivered",
    "statusCode": 1,
    "tag": null,
    "resultTimestamp": "2016-11-29T11:20:24+00:00",
    "udh": null,
    "validity": 259200,
    "validUntilDateTime": "2016-12-02T11:20:22+00:00",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/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 https://api-eu-01.silverstreet.com/v1/sms/submitsimple \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>" \
    -d '{
        "recipients" : ["1234567890"],
        "body" : "Body of the sms",
        "sender" : "Hello world"
    }'

<?php
$sms = $client->createSms('Body of the sms', '1234567890', 'Hello world');
$sms->sendSimple();
?>

The response will look like this:

{
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/sms\/submit"
        }
    },
    "_embedded": {
        "items": [
            {
                "applicationTag": "test",
                "body": "Body of the SMS",
                "callbackUrl": null,
                "createdDateTime": "2016-11-29T11:20:22+00:00",
                "dcs": null,
                "messageId": "eu-01-1.18667.sms583d64765f6b28.36322430",
                "networkCode": null,
                "pid": null,
                "reasonCode": null,
                "recipient": "1234567890",
                "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": "2016-12-02T11:20:22+00:00",
                "_links": {
                    "self": {
                        "href": "https:\/\/api-eu-01.silverstreet.com\/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/biovoice/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: 2016-10-31T12:34:56Z.
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 https://api-eu-01.silverstreet.com/v1/sms/submit \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>" \
    -d '{
        "recipients" : ["1234567890"],
        "body" : "Body of the sms",
        "sender" : "Hello world"
    }'

<?php
$sms = $client->createSms('Body of the sms', '1234567890', 'Hello world');
$sms->send();
?>

The response will look like this:

{
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/sms\/submit"
        }
    },
    "_embedded": {
        "items": [
            {
                "applicationTag": "test",
                "body": "Body of the SMS",
                "callbackUrl": null,
                "createdDateTime": "2016-11-29T11:20:22+00:00",
                "dcs": null,
                "messageId": "eu-01-1.18667.sms583d64765f6b28.36322430",
                "networkCode": null,
                "pid": null,
                "reasonCode": null,
                "recipient": "1234567890",
                "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": "2016-12-02T11:20:22+00:00",
                "_links": {
                    "self": {
                        "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/sms\/submit\/eu-01-1.18667.sms583d64765f6b28.36322430"
                    }
                }
            }
        ]
    },
    "total_items": 1
}

HTTP Endpoint

POST /v1/biovoice/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: 2016-10-31T12:34:56Z.
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 https://api-eu-01.silverstreet.com/v1/sms/submit/<MESSAGE_ID> \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$result = $client->getSms($sms->getMessageId());
?>

The response will look like this:

{
    "applicationTag": "test",
    "body": "Body of the SMS",
    "callbackUrl": null,
    "createdDateTime": "2016-11-29T11:20:22+00:00",
    "dcs": null,
    "messageId": "eu-01-1.18667.sms583d64765f6b28.36322430",
    "networkCode": 12345,
    "pid": null,
    "reasonCode": 0,
    "recipient": "1234567890",
    "resultType": 0,
    "salesPrice": 0.001,
    "salesPriceCurrencyCode": "eur",
    "scheduledDelivery": null,
    "sender": "Hello world",
    "senderNpi": 0,
    "senderTon": 5,
    "status": "delivered",
    "statusCode": 1,
    "tag": null,
    "resultTimestamp": "2016-11-29T11:20:24+00:00",
    "udh": null,
    "validity": 259200,
    "validUntilDateTime": "2016-12-02T11:20:22+00:00",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/sms\/submit\/eu-01-1.18667.sms583d64765f6b28.36322430"
        }
    }
}

HTTP Endpoint

GET /v1/biovoice/sms/submit/:messageId

Arguments

Key	Type	Description
messageId	String	Required. The unique identifier of the SMS.

Get SMS delivery reports

To get SMS delivery reports:

curl https://api-eu-01.silverstreet.com/v1/sms/poll \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$results = $client->getSmsResults();
?>

The response will look like this:

{
    "batchId": "12467857ea2d2f8867d3.73020448",
    "count": 1,
    "_embedded": {
        "messages": [
            {
                "applicationTag": "test",
                "body": "Body of the SMS",
                "callbackUrl": null,
                "createdDateTime": "2016-11-29T11:20:22+00:00",
                "dcs": null,
                "messageId": "eu-01-1.18667.sms583d64765f6b28.36322430",
                "networkCode": 12345,
                "pid": null,
                "reasonCode": 0,
                "recipient": "1234567890",
                "resultType": 0,
                "salesPrice": 0.001,
                "salesPriceCurrencyCode": "eur",
                "scheduledDelivery": null,
                "sender": "Hello world",
                "senderNpi": 0,
                "senderTon": 5,
                "status": "delivered",
                "statusCode": 1,
                "tag": null,
                "resultTimestamp": "2016-11-29T11:20:24+00:00",
                "udh": null,
                "validity": 259200,
                "validUntilDateTime": "2016-12-02T11:20:22+00:00",
                "_links": {
                    "self": {
                        "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/sms\/submit\/eu-01-1.18667.sms583d64765f6b28.36322430"
                    }
                }
            }
        ]
    },
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/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 https://api-eu-01.silverstreet.com/v1/sms/poll/:batchId \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

HTTP Endpoint

DELETE /v1/sms/poll/:batchId

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": "2016-11-29T11:20:22+00:00",
    "dcs": null,
    "messageId": "eu-01-1.18667.sms583d64765f6b28.36322430",
    "networkCode": 12345,
    "pid": null,
    "reasonCode": 0,
    "recipient": "1234567890",
    "resultType": 0,
    "salesPrice": 0.001,
    "salesPriceCurrencyCode": "eur",
    "scheduledDelivery": null,
    "sender": "Hello world",
    "senderNpi": 0,
    "senderTon": 5,
    "status": "delivered",
    "statusCode": 1,
    "tag": null,
    "resultTimestamp": "2016-11-29T11:20:24+00:00",
    "udh": null,
    "validity": 259200,
    "validUntilDateTime": "2016-12-02T11:20:22+00:00",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/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": "2017-07-21T13:54:28+00:00",
    "keyword": null,
    "networkCode": null,
    "recipient": "1234567890",
    "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": "2017-07-21T13:54:28+00:00",
    "keyword": null,
    "networkCode": null,
    "recipient": "1234567890",
    "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": "2016-11-29T11:26:46+00:00",
    "imsi": "214031500000000",
    "messageId": "eu-01-1.19910.nrl583d65f60cdc75.96102916",
    "msc": null,
    "networkCode": 12345,
    "number": "1234567890",
    "operator": "(SPAIN)ORANGE",
    "reasonCode": 0,
    "resultType": 0,
    "salesPrice": 0.00011,
    "salesPriceCurrencyCode": "eur",
    "status": "delivered",
    "statusCode": 1,
    "tag": null,
    "resultTimestamp": "2016-11-29T11:26:48+00:00",
    "validity": 60,
    "validUntilDateTime": "2016-11-29T11:27:46+00:00",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/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 https://api-eu-01.silverstreet.com/v1/numberlookup/submit \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>" \
    -d '{
        "numbers" : ["1234567890"]
    }'

<?php
$numberLookup = $client->createNumberLookup('1234567890');
$numberLookup->send();
?>

The response will look like this:

{
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/numberlookup\/submit"
        }
    },
    "_embedded": {
        "items": [
            {
                "applicationTag": "Default application",
                "callbackUrl": null,
                "countryCode": null,
                "createdDateTime": "2016-11-29T11:26:46+00:00",
                "imsi": null,
                "messageId": "eu-01-1.19910.nrl583d65f60cdc75.96102916",
                "msc": null,
                "networkCode": null,
                "number": "1234567890",
                "operator": null,
                "reason": null,
                "resultType": 0,
                "salesPrice": null,
                "salesPriceCurrencyCode": null,
                "status": "no status",
                "statusCode": 0,
                "tag": null,
                "resultTimestamp": null,
                "validity": 60,
                "validUntilDateTime": "2016-11-29T11:27:46+00:00",
                "_links": {
                    "self": {
                        "href": "https:\/\/api-eu-01.silverstreet.com\/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 https://api-eu-01.silverstreet.com/v1/numberlookup/submit/<MESSAGE_ID> \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$result = $client->getNumberLookup($numberLookup->getMessageId());
?>

The response will look like this:

{
    "applicationTag": "Default application",
    "callbackUrl": null,
    "countryCode": "es",
    "createdDateTime": "2016-11-29T11:26:46+00:00",
    "imsi": "214031500000000",
    "messageId": "eu-01-1.19910.nrl583d65f60cdc75.96102916",
    "msc": null,
    "networkCode": 12345,
    "number": "1234567890",
    "operator": "(SPAIN)ORANGE",
    "reasonCode": 0,
    "resultType": 0,
    "salesPrice": 0.00011,
    "salesPriceCurrencyCode": "eur",
    "status": "delivered",
    "statusCode": 1,
    "tag": null,
    "resultTimestamp": "2016-11-29T11:26:48+00:00",
    "validity": 60,
    "validUntilDateTime": "2016-11-29T11:27:46+00:00",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/numberlookup\/submit\/eu-01-1.19910.nrl583d65f60cdc75.96102916"
        }
    }
}

HTTP Endpoint

GET /v1/numberlookup/submit/:messageId

Arguments

Key	Type	Description
messageId	String	Required. The messageId returned with the verification submit.

Get number lookup results

To get Number Lookup results:

curl https://api-eu-01.silverstreet.com/v1/numberlookup/poll \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$results = $client->getNumberLookupResults();
?>

The response will look like this:

{
    "batchId": "12467857ea2d2f8867d3.73020448",
    "count": 1,
    "_embedded": {
        "messages": [
            {
                "applicationTag": "Default application",
                "callbackUrl": null,
                "countryCode": "es",
                "createdDateTime": "2016-11-29T11:26:46+00:00",
                "imsi": "214031500000000",
                "messageId": "eu-01-1.19910.nrl583d65f60cdc75.96102916",
                "msc": null,
                "networkCode": 12345,
                "number": "1234567890",
                "operator": "(SPAIN)ORANGE",
                "reason": 0,
                "resultType": 0,
                "salesPrice": 0.00011,
                "salesPriceCurrencyCode": "eur",
                "status": "delivered",
                "statusCode": 1,
                "tag": null,
                "resultTimestamp": "2016-11-29T11:26:48+00:00",
                "validity": 60,
                "validUntilDateTime": "2016-11-29T11:27:46+00:00",
                "_links": {
                    "self": {
                        "href": "https:\/\/api-eu-01.silverstreet.com\/v1\/numberlookup\/submit\/eu-01-1.19910.nrl583d65f60cdc75.96102916"
                    }
                }
            }
        ]
    },
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/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 https://api-eu-01.silverstreet.com/v1/numberlookup/poll/:batchId \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

HTTP Endpoint

DELETE /v1/numberlookup/poll/:batchId

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": "2016-11-29T11:26:46+00:00",
    "imsi": "214031500000000",
    "messageId": "eu-01-1.19910.nrl583d65f60cdc75.96102916",
    "msc": null,
    "networkCode": 12345,
    "number": "1234567890",
    "operator": "(SPAIN)ORANGE",
    "reasonCode": 0,
    "resultType": 0,
    "salesPrice": 0.00011,
    "salesPriceCurrencyCode": "eur",
    "status": "delivered",
    "statusCode": 1,
    "tag": null,
    "resultTimestamp": "2016-11-29T11:26:48+00:00",
    "validity": 60,
    "validUntilDateTime": "2016-11-29T11:27:46+00:00",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/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.

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.

Address book fields

With the address book API you can manage the fields of the address book.

Properties

Fields are represented as follows:

{
    "displayName": "First name",
    "key": "firstName",
    "type": "string",
    "_links" : {
        "self" : {
           "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/firstName"
        }
     },
}

Property	Type	Description
displayName	String	Not null. The name of the field as shown in the portal.
key	String	Not null. The unique identifier of the field. Allowed characters of the key are a-z, A-Z and _.
type	String	Not null. The field type. See below for the possible types.

type can be one of the following values:

Type	Description
string	A string with a maximum length of 32 characters.
int	An integer value.
mobile	A mobile number in international format, with leading + or 00. The minimum length is 8 digits and the maximum length is 16 digits.
push	A Push ID. See also Push API specification.
email	An email address.
date	A date value in the format of YYYY-MM-DD.
dateTime	A datetime is in ISO-8601 format.

Get fields

To get all fields:

<?php
$fields = $client->listFields();

curl https://api-eu-01.silverstreet.com/addressbook/v1/field \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

The response looks like this:

{
    "fields": [
        {
            "displayName": "First name",
            "key": "firstName",
            "type": "string",
            "_links" : {
                "self" : {
                   "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/firstName"
                }
             }
        },
        {
            "displayName": "Last name",
            "key": "lastName",
            "type": "string",
            "_links" : {
                "self" : {
                   "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/lastName"
                }
             }
        },
        {
            "displayName": "Address",
            "key": "address",
            "type": "string",
            "_links" : {
                "self" : {
                   "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/address"
                }
             }
        },
        {
            "displayName": "City",
            "key": "city",
            "type": "string",
            "_links" : {
                "self" : {
                   "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/city"
                }
             }
        },
        {
            "displayName": "Country",
            "key": "country",
            "type": "string",
            "_links" : {
                "self" : {
                   "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/country"
                }
             }
        },
        {
            "displayName": "Zip code",
            "key": "zipCode",
            "type": "string",
            "_links" : {
                "self" : {
                   "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/zipCode"
                }
             }
        },
        {
            "displayName": "Company",
            "key": "company",
            "type": "string",
            "_links" : {
                "self" : {
                   "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/company"
                }
             }
        },
        {
            "displayName": "Birthday",
            "key": "birthday",
            "type": "date",
            "_links" : {
                "self" : {
                   "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/birthday"
                }
             }
        },
        {
            "displayName": "Website",
            "key": "website",
            "type": "string",
            "_links" : {
                "self" : {
                   "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/website"
                }
             }
        },
        {
            "displayName": "Mobile number",
            "key": "mobileNumber",
            "type": "mobile",
            "_links" : {
                "self" : {
                   "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/mobileNumber"
                }
             }
        },
        {
            "displayName": "Email address",
            "key": "email",
            "type": "email",
            "_links" : {
                "self" : {
                   "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/email"
                }
             }
        }
    ]
}

Get all configured fields for the address book.

HTTP Endpoint

GET /addressbook/v1/field

Arguments

None.

Get field

To get a field:

curl https://api-eu-01.silverstreet.com/addressbook/v1/field/<KEY> \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$contact = $client->getField('firstName');

The response looks like this:

{
    "displayName": "First name",
    "key": "firstName",
    "type": "string",
    "_links" : {
        "self" : {
           "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/firstName"
        }
     }
}

Get the address book field.

HTTP Endpoint

GET /addressbook/v1/field/:key

Arguments

Key	Type	Description
key	string	Required. The unique key of the field.

Add fields

To add fields:

curl -X POST https://api-eu-01.silverstreet.com/addressbook/v1/field \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>" \
    -d '{
        "fields" : [
            {
                "key": "fieldOne",
                "type": "string",
                "displayName": "Field 1"
            }
        ]
    }'

<?php
$fieldsCollection = new \Silverstreet\AddressBookClient\Model\FieldCollection();
$fields = array();
$fields[] = new \Silverstreet\AddressBookClient\Model\Field(array(
    'key' => 'fieldOne',
    'type' => 'string',
    'displayName' => 'Field 1',
));
$fieldsCollection->setFields($fields);
$client->addFields($fieldsCollection);

HTTP Endpoint

POST /addressbook/v1/field

Arguments

Key	Type	Description
fields	Array	Required. An array with fields and per field the items key, type and displayName.

Update field

To update a field:

curl -X PUT https://api-eu-01.silverstreet.com/addressbook/v1/field/<KEY> \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>" \
    -d '{
        "key": "fieldOne",
        "type": "string",
        "displayName": "Field One"
    }'

<?php
$key = 'fieldOne';
$field = $client->getField($key);
$field->setDisplayName('Field One');
$client->updateField($key, $field);

The response looks like this:

{
    "displayName": "Field One",
    "key": "fieldOne",
    "type": "string",
    "_links" : {
        "self" : {
           "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/firstName"
        }
     }
}

HTTP Endpoint

PUT /addressbook/v1/field/:key

Arguments

Key	Type	Description
key	String	Required. The key of the field to be updated.
properties	Array	Required. An array with the items key, type and displayName. Only the item fieldName can be updated.

Delete field

To delete a field:

curl -X DELETE https://api-eu-01.silverstreet.com/addressbook/v1/field/<KEY> \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$client->deleteField('fieldOne');

HTTP Endpoint

DELETE /addressbook/v1/field/:key

Arguments

Key	Type	Description
key	String	Required. The key of the field to be removed.

Delete all fields

To delete all fields:

curl -X DELETE https://api-eu-01.silverstreet.com/addressbook/v1/field \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$client->deleteAllFields();

HTTP Endpoint

DELETE /addressbook/v1/field

Address book contacts

Properties

Contacts are represented as follows:

{
    "attributes": {
        "birthday": null,
        "city": null,
        "company": null,
        "country": null,
        "customDate": null,
        "customDateTime": null,
        "customNumber": null,
        "customText": null,
        "firstName": "John",
        "lastName": "Doe",
        "remarks": null,
        "street": null,
        "tag": null,
        "website": null,
        "zip": null
    },
    "created": "2018-11-13T12:11:51+00:00",
    "id": "37d1c172-0b75-4786-972d-68070906f601",
    "_links" : {
        "self" : {
           "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/contact/37d1c172-0b75-4786-972d-68070906f601"
        }
     }
}

Property	Type	Description
attributes	Array	Not null. The attributes of the contact. See below for the available attributes.
created	String	Not null. The datetime the contact was created. The datetime is in ISO-8601 format.
id	String	Not null. The unique identifier of the contact. The id is a UUID.

attributes is an array of field attributes configured for the address book. You can manage the fields of you address book via the API.

Get contacts

To get contacts:

#get all contacts
curl https://api-eu-01.silverstreet.com/addressbook/v1/contact \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

#get contacts based on filters
curl 'https://api-eu-01.silverstreet.com/addressbook/v1/contact?operator=or&filter[attributes.lastName][eq]=Doe' \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
//get all contacts
$contacts = $client->listContacts();

//get contacts based on filters
$operator = 'and';
$filters = array(
    'attributes.lastName' => array('eq' => 'Doe'),
);
$contacts = $client->listContacts($operator, $filters);

The response will look like this:

{
    "contacts": [
        {
            "attributes": {
                "birthday": null,
                "city": null,
                "company": null,
                "country": null,
                "customDate": null,
                "customDateTime": null,
                "customNumber": null,
                "customText": null,
                "firstName": "John",
                "lastName": "Doe",
                "remarks": null,
                "street": null,
                "tag": null,
                "website": null,
                "zip": null
            },
            "created": "2018-11-28T06:35:32+00:00",
            "id": "3f9bc3a4-3b02-4563-8e52-0a673266afe9",
            "_links" : {
                "self" : {
                    "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/contact/3f9bc3a4-3b02-4563-8e52-0a673266afe9"
                }
             }
        }
    ],
    "fields": [
        {
            "displayName": "First name",
            "key": "firstName",
            "type": "string",
            "_links" : {
              "self" : {
                  "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/firstName"
              }
            }
        },
        {
            "displayName": "Last name",
            "key": "lastName",
            "type": "string",
            "_links" : {
                "self" : {
                    "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/lastName"
                }
             }
        },
        {
            "displayName": "Address",
            "key": "address",
            "type": "string",
            "_links" : {
                "self" : {
                    "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/address"
                }
             }
        },
        {
            "displayName": "City",
            "key": "city",
            "type": "string",
            "_links" : {
                "self" : {
                    "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/city"
                }
             }
        },
        {
            "displayName": "Country",
            "key": "country",
            "type": "string",
            "_links" : {
                "self" : {
                    "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/country"
                }
             }
        },
        {
            "displayName": "Zip code",
            "key": "zipCode",
            "type": "string",
            "_links" : {
                "self" : {
                    "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/zipCode"
                }
             }
        },
        {
            "displayName": "Company",
            "key": "company",
            "type": "string",
            "_links" : {
                "self" : {
                    "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/company"
                }
             }
        },
        {
            "displayName": "Birthday",
            "key": "birthday",
            "type": "date",
            "_links" : {
              "self" : {
                    "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/birthday"
              }
            }
        },
        {
            "displayName": "Website",
            "key": "website",
            "type": "string",
            "_links" : {
                "self" : {
                    "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/website"
                }
             }
        },
        {
            "displayName": "Mobile number",
            "key": "mobileNumber",
            "type": "mobile",
            "_links" : {
                "self" : {
                    "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/mobileNumber"
                }
             }
        },
        {
            "displayName": "Email address",
            "key": "email",
            "type": "email",
            "_links" : {
               "self" : {
                  "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/field/email"
               }
            }
        }
    ],
    "total": 1
}

Get all contacts or get contacts based on filters.

HTTP Endpoint

GET /addressbook/v1/contact?operator=:operator&filter=:filter

Arguments

Key	Type	Description
operator	String	Optional. The operator used between the filters. Possible values are and and or.
filter	Array	Optional. An array of filters. A filter has a key with an array of operators with values.

The following filtering operators are available:

Type	Description	Remark
eq	Equal	For all fields
ne	Not Equal	For all fields
in	Contains	For string fields only
nin	Does not contain	For string fields only
gte	Greater than or equal	For date, datetime and numeric fields only
lte	less then or equal	For date, datetime and numeric fields only
between	Between 2 values	For date, datetime and numeric fields only
null	Field is null	For all fields, does not need a parameter
notnull	Field is not null	For all fields, does not need a parameter
sw	Starts with	For string fields only
ew	Ends with	For string fields only
type	Channel type	Only for channel fields

Get contact

To get a contact:

curl https://api-eu-01.silverstreet.com/addressbook/v1/contact/<ID> \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$contact = $client->getContact($id);

The response will look like this:

{
    "attributes": {
        "birthday": null,
        "city": null,
        "company": null,
        "country": null,
        "customDate": null,
        "customDateTime": null,
        "customNumber": null,
        "customText": null,
        "firstName": "John",
        "lastName": "Doe",
        "remarks": null,
        "street": null,
        "tag": null,
        "website": null,
        "zip": null
    },
    "created": "2018-11-13T12:11:51+00:00",
    "id": "37d1c172-0b75-4786-972d-68070906f601",
    "_links" : {
        "self" : {
           "href" : "https://api-eu-01.silverstreet.com/addressbook/v1/contact/37d1c172-0b75-4786-972d-68070906f601"
        }
     }
}

HTTP Endpoint

GET /addressbook/v1/contact/:id

Arguments

Key	Type	Description
id	String	Required. The unique identifier of the contact.

Update contact

To update a contact:

curl -X PUT https://api-eu-01.silverstreet.com/addressbook/v1/contact/<ID> \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$id = 'c1ec143f-a3bc-4158-9d63-20444dd25280';
$contact = $client->getContact($id);
$attributes = $contact->getAttributes();
$attributes['website'] = 'https://www.silverstreet.com';
$contact->setAttributes($attributes);
$client->updateContact($id, $contact);

HTTP Endpoint

DELETE /addressbook/v1/contact/:id

Arguments

Key	Type	Description
id	String	Required. The unique identifier of the contact.

Delete contact

To delete a contact:

curl -X DELETE https://api-eu-01.silverstreet.com/addressbook/v1/contact/<ID> \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$client->deleteContact($id);

HTTP Endpoint

DELETE /addressbook/v1/contact/:id

Arguments

Key	Type	Description
id	String	Required. The unique identifier of the contact.

Delete contacts

To delete contacts:

#delete all contacts
curl -X DELETE https://api-eu-01.silverstreet.com/addressbook/v1/contact \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

#delete contacts based on filters
curl -X DELETE 'https://api-eu-01.silverstreet.com/addressbook/v1/contact?operator=or&filter[attributes.lastName][eq]=Doe' \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
//delete all contacts
$client->deleteContacts();

//delete contacts based on filters
$operator = 'and';
$filters = array(
    'attributes.lastName' => array('eq' => 'Doe'),
);
$client->deleteContacts($operator, $filters);

Delete all contacts or delete contacts based on filters.

HTTP Endpoint

DELETE /addressbook/v1/contact?operator=:operator&filter=:filter

Arguments

Key	Type	Description
operator	String	Optional. The operator used between the filters. Possible values are and and or.
filter	Array	Optional. An array of filters. A filter has a key with an array of operators with values. For more information and examples of filters, please check our tutorial How to filter contacts with Address Book API.

The following filtering operators are available:

Type	Description	Remark
eq	Equal	For all fields
ne	Not Equal	For all fields
in	Contains	For string fields only
nin	Does not contain	For string fields only
gte	Greater than or equal	For date, datetime and numeric fields only
lte	less then or equal	For date, datetime and numeric fields only
between	Between 2 values	For date, datetime and numeric fields only
null	Field is null	For all fields, does not need a parameter
notnull	Field is not null	For all fields, does not need a parameter
sw	Starts with	For string fields only
ew	Ends with	For string fields only
type	Channel type	Only for channel fields

E-mail

Properties

E-mail messages are represented as follows:

{
   "subject" : "Hello world",
   "supplierMessageId" : "<20190226131239.1.EDE18535B9C95827@m.silverstreet.com>",
   "cc" : [],
   "callbackUrl" : null,
   "to" : [
      "john@doe.com"
   ],
   "_links" : {
      "self" : {
         "href" : "https://api-eu-01.silverstreet.com/email/v1/email/80fef11f386a75f8f3b29433aaf54a4e00020002"
      }
   },
   "html" : "<p>Hello world</p>",
   "text" : "Hello world",
   "id" : "80fef11f386a75f8f3b29433aaf54a4e00020002",
   "status" : "delivered",
   "bcc" : [],
   "events" : [
      {
         "deliveryStatusCode" : 250,
         "event" : "delivered",
         "severity" : null,
         "received" : "2019-02-26T13:12:40+00:00",
         "url" : null,
         "deliveryStatusMessage" : "OK"
      },
      {
         "severity" : null,
         "event" : "opened",
         "deliveryStatusCode" : null,
         "url" : null,
         "deliveryStatusMessage" : null,
         "received" : "2019-02-26T13:18:58+00:00"
      }
   ],
   "supplierType" : "mailgun",
   "from" : "\"John Doe\" <john.doe@silverstreet.com>",
   "received" : "2019-02-26T13:12:38+00:00"
}

Property	Type	Description
subject	String	Not null. The subject of the e-mail
supplierMessageId	String	Can be null. The id returned by the supplier on submitting the e-mail to the supplier.
cc	Array	Not null. An array of email addresses added as cc (copy) of the e-mail.
callbackUrl	String	Can be null. The callback URL set by your system upon submitting the e-mail. The callback URL will be used to send events for the e-mail. When no callback URL is set, no events will be submitted.
to	Array	Not null. An array of email addresses added as to of the e-mail.
html	String	Not null. The HTML body of the e-mail.
text	String	Not null. The plain-text body of the e-mail. By most e-mail clients this is shown when the user has disabled HTML content or the client doesn't support HTML.
id	String	Not null. Unique identifier of the e-mail returned by the API when submitting the e-mail.
status	String	Not null. The status of the e-mail. See below for possible values.
bcc	Array	Not null. An array of email addresses added as bcc (blind-copy) of the e-mail.
events	Array	Not null. An array with events returned by the supplier. The information in an event depends on the used supplier.
supplierType	String	Not null. The supplier used for sending e-mail.
from	String	Not null. The email address, and optionally the name of the author(s). Possible format: "John Doe" <john.doe@silverstreet.com>.
received	String	Not null. The datetime the e-mail was received by the API. The datetime is in ISO-8601 format.
variables	Array	Can be null. An array with per to e-mail address an array with variables which will be replaced in the subject, HTML and text fields with the corresponding values. See Create e-mail message for more information.

Possible status values of an e-mail are:

Status	Description
new	The e-mail message is accepted by the API..
sent	The e-mail message is sent successfully.
delivered	The e-mail message is delivered successfully.
undelivered	The e-mail message could not be delivered.
error	The e-mail message is rejected by the supplier.

Get e-mail messages

To get e-mail messages:

curl https://api-eu-01.silverstreet.com/email/v1/email \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$emailMessages = $client->getEmailMessages();

The response will look like this:

{
   "email" : [
       {
          "subject" : "Hello world",
          "supplierMessageId" : "<20190226131239.1.EDE18535B9C95827@m.silverstreet.com>",
          "cc" : [],
          "callbackUrl" : "https://api-eu-01.silverstreet.com/v0/callback/email-api/email/15d62888-79cd-41f2-9706-e47b1f7096a9?token=031f4b95ec77cf73e6773a180ac012ca596354e3e505dc7556fb8bc8c99a2abb",
          "to" : [
             "john@doe.com"
          ],
          "_links" : {
             "self" : {
                "href" : "https://api-eu-01.silverstreet.com/email/v1/email/80fef11f386a75f8f3b29433aaf54a4e00020002"
             }
          },
          "html" : "<p>Hello world</p>",
          "text" : "Hello world",
          "id" : "80fef11f386a75f8f3b29433aaf54a4e00020002",
          "status" : "delivered",
          "bcc" : [],
          "events" : [
             {
                "deliveryStatusCode" : 250,
                "event" : "delivered",
                "severity" : null,
                "received" : "2019-02-26T13:12:40+00:00",
                "url" : null,
                "deliveryStatusMessage" : "OK"
             },
             {
                "severity" : null,
                "event" : "opened",
                "deliveryStatusCode" : null,
                "url" : null,
                "deliveryStatusMessage" : null,
                "received" : "2019-02-26T13:18:58+00:00"
             }
          ],
          "supplierType" : "mailgun",
          "from" : "\"John Doe\" <john.doe@silverstreet.com>",
          "received" : "2019-02-26T13:12:38+00:00"
       }
   ],
    "limit" : 10,
    "_links" : {
       "last" : {
          "href" : "https://api-eu-01.silverstreet.com/email/v1/email?page=1&limit=10"
       },
       "self" : {
          "href" : "https://api-eu-01.silverstreet.com/email/v1/email?page=1&limit=10"
       },
       "first" : {
          "href" : "https://api-eu-01.silverstreet.com/email/v1/email?page=1&limit=10"
       }
    },
    "page" : 1,
    "total" : 1
}

HTTP Endpoint

GET /email/v1/email?page=:page&limit=:limit

Arguments

Key	Type	Description
page	Integer	Optional. The page number you want to retrieve. The number of pages depends on the total e-mail messages and the limit value. Default value of page is 1.
limit	Integer	Optional. The number of e-mail messages per page. The default value is 10.

Get e-mail message

To get a e-mail message:

curl https://api-eu-01.silverstreet.com/email/v1/email/<ID> \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$email = $client->getEmailById($id);

The response will look like this:

{
   "subject" : "Hello world",
   "supplierMessageId" : "<20190226131239.1.EDE18535B9C95827@m.silverstreet.com>",
   "cc" : [],
   "callbackUrl" : "https://api-eu-01.silverstreet.com/v0/callback/email-api/email/15d62888-79cd-41f2-9706-e47b1f7096a9?token=031f4b95ec77cf73e6773a180ac012ca596354e3e505dc7556fb8bc8c99a2abb",
   "to" : [
      "john@doe.com"
   ],
   "_links" : {
      "self" : {
         "href" : "https://api-eu-01.silverstreet.com/email/v1/email/80fef11f386a75f8f3b29433aaf54a4e00020002"
      }
   },
   "html" : "<p>Hello world</p>",
   "text" : "Hello world",
   "id" : "80fef11f386a75f8f3b29433aaf54a4e00020002",
   "status" : "delivered",
   "bcc" : [],
   "events" : [
      {
         "deliveryStatusCode" : 250,
         "event" : "delivered",
         "severity" : null,
         "received" : "2019-02-26T13:12:40+00:00",
         "url" : null,
         "deliveryStatusMessage" : "OK"
      },
      {
         "severity" : null,
         "event" : "opened",
         "deliveryStatusCode" : null,
         "url" : null,
         "deliveryStatusMessage" : null,
         "received" : "2019-02-26T13:18:58+00:00"
      }
   ],
   "supplierType" : "mailgun",
   "from" : "\"John Doe\" <john.doe@silverstreet.com>",
   "received" : "2019-02-26T13:12:38+00:00"
}

HTTP Endpoint

GET /email/v1/email/:id

Arguments

Key	Type	Description
id	String	Required. The unique id of the e-mail message and returned when submitting the e-mail message.

Create e-mail message

To create a e-mail message:

curl -X POST https://api-eu-01.silverstreet.com/email/v1/email \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>" \
    -d '{
        "to" : ["john@doe.com"],
        "subject" : "Hello world",
        "html" : "<p>Hello world</p>",
        "text" : "Hello world",
        "from" : "\"John Doe\" <john.doe@silverstreet.com>"
    }'

#Example with variables:
    -d '{
        "to" : ["john@doe.com"],
        "subject" : "Hello %var1%",
        "html" : "<p>Hello world</p>",
        "text" : "Hello world",
        "from" : "\"John Doe\" <john.doe@silverstreet.com>",
        "variables" : {
            "john@doe.com" : {
                "var1" : "world"
            }
        }
    }'

<?php
$email = new \Silverstreet\EmailClient\Model\Email();
$email->setTo(array('john@doe.com'));
$email->setSubject("Hello world");
$email->setHtml("<p>Hello world</p>");
$email->setText("Hello world");
$email->setFrom("\"John Doe\" <john.doe@silverstreet.com>");

$client->createEmail($email);

//Example with variables:
$email->setVariables(
        array(
            'john@doe.com' => array(
                'var1' => 'world',
            ),
        )
    );
$email->setText("Hello %var1%");

The response will look like this:

{
   "count" : 1,
   "batchId" : "aec97e2f469623db98ba67f381e451050001"
}

Variables

When submitting e-mail messages you can use variables to customize your e-mails. Per to e-mail address you can set the variables. Variables in the subject, HTML and text fields will be replaced with the corresponding value. Variables need to be placed between %, for example %var1%. You can also set a default value in case the variable is not set or is empty. You can do that like this: %var1|Default%. See also tutorial How to use personalise your campaigns for more information.

Response

Property	Type	Description
count	Integer	Not null. The number of e-mail created on submit.
batchId	Integer	Not null. A unique identifier of the e-mail batch created. The id's of the e-mails created for the batch will be the batch ID plus the counter. So if the batch id is aec97e2f469623db98ba67f381e451050001 and you want to retrieve the first e-mail of the batch, you have a append 0001 to the batch id. So the id of the e-mail will be aec97e2f469623db98ba67f381e4510500010001.

HTTP Endpoint

POST /email/v1/email

Arguments

Property	Type	Description
subject	String	Required. The subject of the e-mail
cc	Array	Optional An array of email addresses added as cc (copy) of the e-mail.
callbackUrl	String	Optional. The callback URL set by your system upon submitting the e-mail. The callback URL will be used to send events for the e-mail. When no callback URL is set, no events will be submitted.
to	Array	Required. An array of email addresses added as to of the e-mail.
html	String	Required. The HTML body of the e-mail.
text	String	Required. The plain-text body of the e-mail. By most e-mail clients this is shown when the user has disabled HTML content or the client doesn't support HTML.
bcc	Array	Optional. An array of email addresses added as bcc (blind-copy) of the e-mail.
from	String	Required. The email address, and optionally the name of the author(s). Possible format: "John Doe" <john.doe@silverstreet.com>.
variables	Array	Optional. An array with per to e-mail address an array with variables which will be replaced in the subject, HTML and text fields with the corresponding values. See Create e-mail message for more information.

Push

Properties

Push messages are represented as follows:

{
    "callbackId": "488fe3e4-00bc-4227-a384-f0e0be689e8c",
    "data": "{\"to\":\"f4XzKr1VSmI:APA28baA6_1ClL53qNcEfAxR2Ci8Va8vISSoTVDArMduD1VBkO8iXSU4Gygux-lqxUQgi49bMY8mkyrSgcNMx6vURf1Rnd7moHGWScOzNoF9bvkgSnM4pAd2SZHxHGnZ1a4mQQ5iRdil\",\"priority\":\"high\",\"time_to_live\":60,\"data\":{\"type\":\"verify\",\"token\":\"883103\",\"datetime\":\"2018-11-05T14:43:45.000Z\"}}",
    "id": "f39a87015dc1d76204798f211f701f0b",
    "received": "2018-11-05T14:43:46+00:00",
    "status": "sent",
    "supplierMessageId": "0:1541429027866250%7170e3c6f9fd7ecd",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/push\/v1\/push\/f39a87015dc1d76204798f211f701f0b"
        }
    }
}

Property	Type	Description
callbackId	String	Not null. For future use.
data	String	Not null. The JSON data sent as push message.
id	String	Not null. The unique identifier of the push message.
received	String	Not null. The datetime the push message was sent. The datetime is in ISO-8601 format.
status	String	Not null. The status of the push message. See below table for possible status values.
supplierMessageId	String	Not null. The id returned by the supplier when sending the message.

Status	Description
new	The push message is accepted by the API..
sent	The push message is sent successfully.
error	The push message is rejected by the supplier.

Get push messages

To get push messages:

curl https://api-eu-01.silverstreet.com/push/v1/push \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$pushMessages = $client->getPushMessages();

The response will look like this:

{
    "limit": 1,
    "page": 1,
    "push": [
        {
            "callbackId": "488fe3e4-00bc-4227-a384-f0e0be689e8c",
            "data": "{\"to\":\"f4XzKr1VSmI:APA28baA6_1ClL53qNcEfAxR2Ci8Va8vISSoTVDArMduD1VBkO8iXSU4Gygux-lqxUQgi49bMY8mkyrSgcNMx6vURf1Rnd7moHGWScOzNoF9bvkgSnM4pAd2SZHxHGnZ1a4mQQ5iRdil\",\"priority\":\"high\",\"time_to_live\":60,\"data\":{\"type\":\"verify\",\"token\":\"883103\",\"datetime\":\"2018-11-05T14:43:45.000Z\"}}",
            "id": "f39a87015dc1d76204798f211f701f0b",
            "received": "2018-11-05T14:43:46+00:00",
            "status": "sent",
            "supplierMessageId": "0:1541429027866250%7170e3c6f9fd7ecd",
            "_links": {
                "self": {
                    "href": "https:\/\/api-eu-01.silverstreet.com\/push\/v1\/push\/f39a87015dc1d76204798f211f701f0b"
                }
            }
        }
    ],
    "total": 1,
    "_links": {
        "first": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/push\/v1\/push?page=1&limit=10"
        },
        "last": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/push\/v1\/push?page=1&limit=10"
        },
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/push\/v1\/push?page=1&limit=10"
        }
    }
}

HTTP Endpoint

GET /push/v1/push?page=:page&limit=:limit

Arguments

Key	Type	Description
page	Integer	Optional. The page number you want to retrieve. The number of pages depends on the total push messages and the limit value. Default value of page is 1.
limit	Integer	Optional. The number of push messages per page. The default value is 10.

Get push message

To get a push message:

curl https://api-eu-01.silverstreet.com/push/v1/push/<ID> \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>"

<?php
$push = $client->getPushById($id);

The response will look like this:

{
    "callbackId": "488fe3e4-00bc-4227-a384-f0e0be689e8c",
    "data": "{\"to\":\"f4XzKr1VSmI:APA28baA6_1ClL53qNcEfAxR2Ci8Va8vISSoTVDArMduD1VBkO8iXSU4Gygux-lqxUQgi49bMY8mkyrSgcNMx6vURf1Rnd7moHGWScOzNoF9bvkgSnM4pAd2SZHxHGnZ1a4mQQ5iRdil\",\"priority\":\"high\",\"time_to_live\":60,\"data\":{\"type\":\"verify\",\"token\":\"883103\",\"datetime\":\"2018-11-05T14:43:45.000Z\"}}",
    "id": "f39a87015dc1d76204798f211f701f0b",
    "received": "2018-11-05T14:43:46+00:00",
    "status": "sent",
    "supplierMessageId": "0:1541429027866250%7170e3c6f9fd7ecd",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/push\/v1\/push\/f39a87015dc1d76204798f211f701f0b"
        }
    }
}

HTTP Endpoint

GET /push/v1/push/:id

Arguments

Key	Type	Description
id	String	Required. The unique id of the push message and returned when submitting the push message.

Create push message

To create a push message:

curl -X POST https://api-eu-01.silverstreet.com/push/v1/push \
    -H "Accept: application/json" \
    -H "Content-Type: application/json; charset=utf8" \
    -u "silverstreet:<API_KEY>" \
    -d '{
        "push":[
            {
            "data":"\"to\":\"<PUSH_ID>\",\"priority\":\"high\",\"time_to_live\":60,\"data\":{\"field1\":\"value1\",\"field2\":\"value2\"}}"
            }
        ]
    }'

<?php
$body = array;
$body[] = array(
    'data' => json_encode(
        array(
            'to' => $pushId,
            'priority' => 'high',
            'time_to_live' => 60,
            'data' => $jsonString,
        )
    ),
);
$pushCollection = new \Silverstreet\PushClient\Model\PushCollection(['push' => $body]);

$client->createPush($pushCollection);

The response will look like this:

{
    "callbackId": "488fe3e4-00bc-4227-a384-f0e0be689e8c",
    "data": "{\"to\":\"f4XzKr1VSmI:APA28baA6_1ClL53qNcEfAxR2Ci8Va8vISSoTVDArMduD1VBkO8iXSU4Gygux-lqxUQgi49bMY8mkyrSgcNMx6vURf1Rnd7moHGWScOzNoF9bvkgSnM4pAd2SZHxHGnZ1a4mQQ5iRdil\",\"priority\":\"high\",\"time_to_live\":60,\"data\":{\"field1\":\"value1\",\"field2\":\"value2\"}}",
    "id": "f39a87015dc1d76204798f211f701f0b",
    "received": "2018-11-05T14:43:46+00:00",
    "status": "sent",
    "supplierMessageId": "0:1541429027866250%7170e3c6f9fd7ecd",
    "_links": {
        "self": {
            "href": "https:\/\/api-eu-01.silverstreet.com\/push\/v1\/push\/f39a87015dc1d76204798f211f701f0b"
        }
    }
}

HTTP Endpoint

POST /push/v1/push

Arguments

Key	Type	Description
callbackId	Integer	Optional. For future use. When not set, the system will generate one.
push	Array	Required. An array with push messages you want to send. Per push message you can to set the data field, see below.
data	String	Required. The JSON data to be send as push message. See our tutorial (link) for more information what data to send.