Welcome

Get started easily with Beepsend API. Here is a complete list of our public end points. Feel free to give us feedback on @beepsend or on IRC #beepsend@freenode

Introduction

Item Value
Host api.beepsend.com
Port 80 or 443
Protocol HTTP or HTTPS
Authentication User Token OR Connection Token
Administrator Page https://connect.beepsend.com

Users and Connections

Before you begin using Beepsends API you need to know the difference between a User and a Connection.

You are a user. At your disposal you have one or more connections to send SMS or do HLR lookups. Connections are in other services sometimes referred to as "Application-token".

As a user you can perform administrative tasks like transferring funds between your connections or get accumulated statistics. Using a connection you can send SMS and HLR requests.

Questions

I've just signed up. I have a username and password. What now?

Log in to the Beepsend Customer Portal and grap your API tokens used to authenticate against the API. Please note that Connection-token is limited in functionality and works best for production. The customer portal also showcases everything you can do using the RESTful API as it is 100% built using only these public API endpoints.

So do I send messages with a connection or a user?

Technically a connection is always what is used for sending a message. A connection means a price lists and you can have several connections with different quality and price. When you send a message as a user your user-account is linked to a connection.

Can I send SMS/HLR with a user API Token?

Yes, one of your connections will always be the default connection. When doing tasks that require a connection your default connection will be chosen automatically.

Escaped data

If you intend to use the data you receive in a web application, it's a good idea to sanitize the data before. This is to prevent XSS attacks.

If you do not wish to do sanitize the data on your own, all of our endpoints that return data have the option to sanitize it for you before sending.

In your query string, set _escape to true.

GET /2/users/me?_escape=true

Example data from the Users endpoint.

{
    "id": 123,
    "name": "Åke Ärlig Östen",
    "email": "thejanitor@beepsend.com",
    "phone": "46406007500",
    "customer": "Beepsend AB",
    "api_token": "abc123",
    "default_connection": {
        "id": 142,
        "label": "<script type=\"text/javascript\">XSS här</script>",
        "system_id": "beepbeep",
        "type": 1
    },
    "user_types": [
        {
            "id": 1,
            "name": "Technical Contact"
        }
    ],
    "max_level": 2,
    "verified": {
        "email": true,
        "phone": false,
        "terms": true
    }
}
{
    "id": 123,
    "name": "&Aring;ke &Auml;rlig &Ouml;sten",
    "email": "thejanitor@beepsend.com",
    "phone": "46406007500",
    "customer": "Beepsend AB",
    "api_token": "abc123",
    "default_connection": {
        "id": 142,
        "label": "&lt;script type=&quot;text/javascript&quot;&gt;XSS h&auml;r&lt;/script&gt;",
        "system_id": "beepbeep",
        "type": 1
    },
    "user_types": [
        {
            "id": 1,
            "name": "Technical Contact"
        }
    ],
    "max_level": 2,
    "verified": {
        "email": true,
        "phone": false,
        "terms": true
    }
}

Installation with Composer

This library is available via Composer. This is the recommended installation method.

To install with Composer, create composer.json in your project root and add the following.

{
    "require": {
        "beepsend/php-sdk": "dev-master"
    }
}

To install, run:

php composer.phar install

Once you have installed the library, you will need to load Composer's autoloader (which registers all the required namespaces):

require_once __DIR__ . '/vendor/autoload.php';

Manual Installation

Please note that the examples all expect you to have used the Composer method. If not you need to substitute the autoload.php with your own import in the php-code.

Use git to clone the repository:

git clone https://github.com/beepsend/beepsend-php.git

Or download the repository as a zip file.

Installation

Installation of this library is available trough Bower package manager.

bower install beepsend-javascript --save

Or you can clone it with git from our repository

git clone https://github.com/beepsend/beepsend-javascript.git

Or download the repository as a zip file.

After that you need to include the Beepsend Javascript library to your project:

<script type="text/javascript" src="src/beepsend.js"></script>

And you're ready to go!

Installation

Clone BeepSendSDK iOS library with git from our repository

git clone https://github.com/beepsend/beepsend-ios.git

Or download the repository as a zip file.

You can either import entire BeepSendSDK project or you can generate libBeepSendSDK.a and use it instead.

Have fun!

API access is granted by the use of Tokens.

Each request must be accompanied by a Token. The Token grants you privileges to end points on Connection- or User level.

To find your API token, visit the Beepsend Customer Portal or contact your account manager.

There are two ways to authenticate yourself using the Beepsend API.

Using Query String

Add your API token as a parameter in the query string and append to the URL you are trying to reach.

Parameter: api_token

Example

/2/connections/me?api_token=abc123

With an HTTP header

If you prefer keeping the URL untouched, you can use an HTTP header in your request instead.

In your request, add the Authorization HTTP header with your API token as value.

Authorization: Token abc123

CURL EXAMPLE

curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/connections/me"
curl "https://api.beepsend.com/2/connections/me?api_token=abc123"

DEFINITION

$client = new Client({API_TOKEN});

CODE EXAMPLE

For authentication you need to provide valid API token in library constructor.

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

CODE EXAMPLE

var client = new beepsend(
    {
        "api_token" : "abc123"
    }
);

DEFINITION

For authentication you need to set valid API token. In your main project .plist file you must add API token value for key "BeepSendToken".

This endpoint requres a valid User API-Token. Read more about Users and Connections.

As a user you belong to a customer. A customer is where your address, pay and pricelist information is stored.

GET /2/customer/

Response

{
    "id": 1,
    "phone": "46406007500",
    "name": "Beepsend AB",
    "address": "Gustav Adolfs Torg 12",
    "city": "Malmö",
    "post_box": "21139",
    "country": "Sweden",
    "vat": "",
    "email": "beepsend@beepsend.se",
    "invoice_type": "pre-pay",
    "account_manager": {
        "name": "Account Manager",
        "email": "account.manager@beepsend.se"
    },
    "pricelist_type": 1,
    "pricelist_delimiter": null,
    "pricelist_schedule": {
        "id": 1,
        "name": "Immediately"
    },
    "pricelist_fields": [],
    "trial": false
}
Key Type Description
id int ID.
phone string Phone number.
name string name.
address string Street address.
city string City.
post_box string Post code.
country string Country.
vat string VAT number.
email string Email.
invoice_type string pre-pay or post-pay.
account_manager.name string Name of customer account manager.
account_manager.email string Email of customer account manager.
pricelist_type int 1 for json, 2 for csv.
pricelist_delimiter string \ null Delimiter that is being used if pricelist_type is csv. If pricelist_type is json this will be null.
pricelist_schedule.id int Pricelist sendout schedule ID.
pricelist_schedule.name string Pricelist sendout schedule name. How often new pricelist updates should be mailed out.
pricelist_fields array Pricelist fields to be included.
trial boolean Indicates whether customer is in trial mode

CURL EXAMPLE

curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/customer/"

DEFINITION

$client->customer->get();

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');
$customer = $client->customer->get();

DEFINITION

var client = new beepsend(
    {
        "api_token" : "abc123"
    }
);

client.customer().get().then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});

CODE EXAMPLE

client.customer().get().then(
    function(customer) {
        // Write your success handler function here
    },
    function(error) {
        // Write your error handler function here
    }
);

DEFINITION

@interface BSUser

    - (void)getCustomerDetailsOnCompletion:(void(^)(BSCustomer *customer, NSArray *errors))block;

@end

CODE EXAMPLE

[[BSUser currentUser] getCustomerDetailsOnCompletion:^(BSCustomer *customer, NSArray *errors) {

    if (!errors || errors.count == 0) {

        //Handle response (BSCustomer object)

    }
    else {

        //Handle error (array of BSError objects)

    }

}];

If authenticated using a Connection token only one connect object is accessible. If authenticated using a User token there can be one or several connections accessible. Each User normally has a default connection specified unless no connection ID is specified.

To fetch a list of all available connections and their corresponding information.

GET /2/connections/

For both Connection and User tokens a short-hand tag is available which serves as alias for the connection ID. The label is called "me".

Receive the connection object for given API-token.

GET /2/connections/me

Response

[
    {
        "id": 1,
        "system_id": "beepsend",
        "label": "beepsend-connection",
        "api_token": "abc123",
        "callbacks": {
            "dlr": "http://beepsend.com/dlr",
            "mo": "https://beepsend.com/mocallback",
            "method": "PUT"
        },
        "users": [
            {
                "username": "beepsend-user",
                "name": "Beep Beepson",
                "id": 1
            }
        ],
        "wallet": {
            "balance": 5028.14758,
            "name": "Beepsend wallet",
            "id": 1
        },
        "customer": "Beepsend AB",
        "description": "",
        "type": 1,
        "whitelist": [
            "127.0.0.1",
            "10.11.12.13",
            "172.16.0.36",
            "192.168.1.170"
        ],
        "tlv_for_mcc_mnc": 0
    }
]
Key Type Description
id int Unique connection ID.
system_id string Login name.
label string Connection label.
api_token string API Token belonging to this connection.
callbacks.dlr string Connection DLR Callback URL.
callbacks.mo string Connection Mo Callback URL.
callbacks.method string HTTP method used for connection callbacks.
users array List of users with read-write access to this connection.
users.username string Username.
users.name string Name of user.
users.id int Unique user ID.
wallet.balance float Current credit balance in Euro (€).
wallet.name string The name of this wallet.
wallet.id int Unique wallet ID.
customer string Customer name.
description string (Optional) Description of this connection.
type int Type of connection, 1 for SMS connection or 2 for HLR connection.
whitelist list   List of ip addresses that have been whitelisted to use this connection.
tlv_for_mcc_mnc int Tag-Length-Value field for returning mcc and mnc in DLR.

CURL EXAMPLE

curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/connections/"
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/connections/me"

DEFINITION

$client->connection->get({CONNECTION});

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

/* Get all connections */
$connections = $client->connection->all();

/* Get connection for given API-token */
$connection = $client->connection->get();

/* Get specific connection by id */
$connectionId = 1;
$connection = $client->connection->get($connectionId);

DEFINITION

var client = new beepsend(
    {
        "api_token" : "abc123"
    }
);

client.connection().all().then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});

client.connection().get({CONNECTION}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});

CODE EXAMPLE

/* In case that you want to get all connection connected to this account, you can use this library method. */

client.connection().all().then(
    function(allConnections) {
        // Write your success handler function here 
    },
    function(error) {
        // Write your error handler function here
    }
);

/* This method returns collection of all connection connected to this account. */


/* Or if you want to fetch data about specific connection you can use this library method. In get method we can provide connection id or we can call it without connection id, in case that you havent provide connection id, we will return data of default connection */

/* connectionId - is id of connection that we want to get or you can pass null if you want to get default connection object */

var connection = 1;

client.connection().get(connection).then(
    function(connection) {
        // Write your success handler function here 
    },
    function(error) {
        // Write your error handler function here
    }
);

DEFINITION

//If you are using user API token
@interface BSUser

    @property (nonatomic, strong) BSConnection *defaultConnection;

    - (void)getAvailableConnectionsOnCompletion:(void(^)(NSArray *connections, NSArray *errors))block;

@end

//If you are using connection API token you can access connection directly
@interface BSConnection

    + (BSConnection *)currentConnection;

@end

CODE EXAMPLE

Get users default connection:

BSConnection *connection = [[BSUser currentUser] defaultConnection];

Get all connections associated with account:

[[BSUser currentUser] getAvailableConnectionsOnCompletion:^(NSArray *connections, NSArray *errors) {

    if (!errors || errors.count == 0) {

        //Handle response (array of BSConnection objects)

    }
    else {

        //Handle error (array of BSError objects)

    }

}];

If using connection API token you can access only default connection

BSConnection *connection = [BSConnection currentConnection];

Any property of the connection object can be manipulated once authenticated either as that Connection using a Connection token or by authenticating using a User token with read/write access to the Connection.

By issuing a PUT request and one or many properties as key/values in payload the information is updated. A successful save is indicated by a 200 OK. The "me" alias can be used to reference the default Connection if authenticated as a User or the Connection in question if authenticated using a Connection token.

PUT /2/connections/<ID>
PUT /2/connections/me
Parameter Type Description
callbacks.dlr
Optional
string The callback URL that will be used for your Delivery reports.
callbacks.mo
Optional
string The callback URL that will be used for your Mobile Originated SMS.
callbacks.method
Optional
string What HTTP method that will be used for your callbacks. GET, POST or PUT.
system_id
Optional
string Your login name. Used for SMPP and HTTP v1 api.
label
Optional
string Custom label to recognize your connection.
description
Optional
string Connection description.
default_connection
Optional
bool If authenticating with a user API Token, set to true to make specified connection your default.

This endpoint supports partial updates. Any omitted field in a model will read in the current value.

Request body

Initialise a request with the fields you would like to update.

{
    "callbacks": {
        "dlr": "https://beepsend.com/securedlr"
    },
    "system_id": "crossover",
    "label": "Pawnee-connection",
    "description": "Cool. Cool, cool, cool"
}

If authenticating with a user API Token you can even set specified connection to be your default.

{
    "default_connection": true
}

Response

{
    "id": 15748,
    "system_id": "crossover",
    "label": "Pawnee-connection",
    "api_token": "abc123",
    "callbacks": {
        "dlr": "https://beepsend.com/securedlr",
        "mo": "https://beepsend.com/mocallback",
        "method": "PUT"
    },
    "users": [
        {
            "id": 1,
            "name": "Beep Beepson",
            "username": "beepsend-user"
        }
    ],
    "wallet": {
        "id": 1,
        "name": "Beepsend wallet",
        "balance": 5.78838
    },
    "customer": "Beepsend AB",
    "description": "Cool. Cool, cool, cool",
    "type": 1,
    "whitelist": [],
    "tlv_for_mcc_mnc": 0
}

CURL EXAMPLE

curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X PUT -d '{"callbacks": {"dlr": "https://yourdomain.com/securedlr"}, "system_id": "crossover", "label": "Pawnee-connection", "description": "Cool. Cool, cool, cool"}' \
"https://api.beepsend.com/2/connections/1"

DEFINITION

$client->connection->update({CONNECTION}, {OPTIONS});

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

$data = array(
    'callbacks' => array(
        'dlr' => 'https://beepsend.com/securedlr'
    ),
    'system_id' => 'crossover',
    'label' => 'Pawnee-connection',
    'description' => 'This is the main production connection'
);

$connectionId = 1;
$connections = $client->connection->update($connectionId, $data);

You can also omit connection id and then we will use the "me" alias to reference the default connection

DEFINITION

var client = new beepsend(
    {
        "api_token" : "abc123"
    }
);

client.connection().update({CONNECTION}, {DATA}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});

CODE EXAMPLE

//In this example we will show how you can update your default connection

var connectionId = "me";

var connectionData = {
    "callbacks": {
        "dlr": "https://beepsend.com/securedlr"
    },
    "system_id": "crossover",
    "label": "Pawnee-connection",
    "description": "Cool. Cool, cool, cool"
};

client.connection().update(connectionId, connectionData).then(
    function(success) {
        //Here you can handle success result
    },
    function(error) {
        //Here you can handle error result
    }
);

DEFINITION

@interface BSConnection    

    @property (nonatomic, strong) NSString *label;
    @property (nonatomic, strong) NSString *description;
    @property (nonatomic, strong) NSString *systemID;
    @property (nonatomic, strong) BSCallbacks *callbackURLs;

    - (void)updateConnectionOnCompletion:(void(^)(NSArray *errors))block;

@end

CODE EXAMPLE

//Connection that you want to update
BSConnection *connection = [BSConnection currentConnection];

connection.label = @"New label";
connection.description = @"New description";
connection.systemID = @"New system ID";

connection.callbackURLs.DLR = @"www.newdlrcallback.com";
connection.callbackURLs.MO = @"www.newmocallback.com";
connection.callbackURLs.method = @"POST";

[connection updateConnectionOnCompletion:^(NSArray *errors) {

    if (!errors || errors.count == 0) {

        //Connection successfully updated

    }
    else {

        //Handle error (array of BSError objects)

    }

}];

This endpoint requres a valid User API-Token. Read more about Users and Connections.

If you think that the connection token used for authenticating with the Beepsend API has been compromised you can use this method (with a user token) to reset the connection token.

GET /2/connections/<id>/tokenreset

Response

{
    "api_token": "abc123",
}
Key Type Description
api_token string New API Token for this connection.

CURL EXAMPLE

curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/connections/1/tokenreset"

DEFINITION

$client->connection->resetToken({CONNECTION});

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

$connectionId = 1;
$newToken = $client->connection->resetToken($connectionId);

You can also omit connection id and then we will use the "me" alias to reference the default connection

DEFINITION

var client = new beepsend(
    {
        "api_token" : "abc123"
    }
);

client.connection().resetToken({CONNECTION}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});

CODE EXAMPLE

var connection = 1;

client.connection().resetToken(connection).then(
    function(success) {
        // Write your success handler function here
    },
    function(error) {
        // Write your error handler function here
    }
);

DEFINITION

@interface BSConnection

    - (void)resetConnectionTokenOnCompletion:(void(^)(NSArray *errors))block;

@end

CODE EXAMPLE

[[BSConnection currentConnection] resetConnectionTokenOnCompletion:^(NSArray *errors) {

    if (!errors || errors.count == 0) {

        //Token successfully updated

    }
    else {

        //Handle error (array of BSError objects)

    }

}];

This endpoint requres a valid User API-Token. Read more about Users and Connections.

If you wish to use our legacy HTTP API, you need to supply your connection username as well as password for each request. If you don't have your connection password, you can request a new one with this endpoint.

NOTE: A connection token and password are two separate things. A connection password is only used for HTTP API and SMPP.

GET /2/connections/<id>/passwordreset

Response

{
    "password": "abc12345",
}
Key Type Description
password string New 8 character password to use with HTTP API and SMPP.

CURL EXAMPLE

curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/connections/1/passwordreset"

DEFINITION

$client->connection->resetPassword({CONNECTION});

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

$connectionId = 1;
$newToken = $client->connection->resetPassword($connectionId);

You can also omit connection id and then we will use the "me" alias to reference the default connection

DEFINITION

var client = new beepsend(
    {
        "api_token" : "abc123"
    }
);

client.connection().resetPassword({CONNECTION}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});

CODE EXAMPLE

var connection = 1;

client.connection().resetPassword(connection).then(
    function(success) {
        // Write your success handler function here
    },
    function(error) {
        // Write your error handler function here
    }   
);

DEFINITION

@interface BSConnection

    - (void)resetConnectionPasswordOnCompletion:(void(^)(NSString *password, NSArray *errors))block;

@end

CODE EXAMPLE

[[BSConnection currentConnection] resetConnectionPasswordOnCompletion:^(NSString *password, NSArray *errors) {

    if (!errors || errors.count == 0) {

        //Handle response (updated password)

    }
    else {

        //Handle error (array of BSError objects)



}];

Please contact your account manager if you wish to setup a 2-way number. Find out how to recieve a mobile orignated SMS under our callback documentation.

As a user you will have associated connections. These connections (may) have access to 2-way numbers, which can receive mobile originated messages. The 2-way numbers are registered in specific countries, which this endpoint will also list.

GET /2/numbers/
GET /2/numbers/<ID>
GET /2/numbers/?ids=<ID1,ID2>&connection=<connection ID>
GET /2/numbers/?number=<number>&connection=<connection ID>
Parameter Type  Description
number
Optional
int Registered number
connection_id
Optional
int Get numbers linked to a specific connection
ids
Optional
string List of ids separated by a comma (,)

Response

[
    {
        "id": 350,
        "number": "1272",
        "country": "Denmark",
        "keywords": [
            {
                "connection": {
                    "id": 1,
                    "name": "your-account"
                },
                "keyword": null,
                "price": 0
            }
        ]
    },
    {
        "id": 8779,
        "number": "46736007500",
        "country": "Sweden",
        "keywords": [
            {
                "connection": {
                    "id": 1,
                    "name": "your-account"
                },
                "keyword": null,
                "price": 0
            }
        ]
    }
]
Key Type Description
id int Recipient number id
number int Recipient number
country string Country name
keywords array List of keywords
keywords.keyword null|string The keyword that will be matched on for incoming MO traffic. null will match everything.
keywords.price float The cost for each incoming MO.
keywords.connection int Connection object
keywords.connection.id int ID of connection
keywords.connection.name string Name of connection

CURL EXAMPLE

curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/numbers/"

DEFINITION

$client->contact->recipientNumbers();

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

$numbers = $client->contact->recipientNumbers();

DEFINITION

var client = new beepsend(
    {
        "api_token" : "abc123"
    }
);

client.connection().recipientNumbers().then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});

CODE EXAMPLE

client.connection().recipientNumbers().then(
    function(success) {
        // Write your success handler function here
    },
    function(error) {
        // Write your error handler function here
    }
);

DEFINITION

@interface BSUser

    - (void)getRecipientNumbersOnCompletion:(void(^)(NSArray *numbers, NSArray *errors))block;

@end

CODE EXAMPLE

[[BSUser currentUser] getRecipientNumbersOnCompletion:^(NSArray *numbers, NSArray *errors) {

    if (!errors || errors.count == 0) {

        //Handle response (array of BSNumber objects)

    }
    else {

        //Handle error (array of BSError objects)

    }

}];

The following endpoints give access to a connections associated pricelist. If accessing using a user token, connection id which the user is accociated with is required.

The API offers the ability to see every revision made of price lists for each connection. When specifying a revision ID one can fetch the detailed price list at that point in time. If authenticated using a User token, a connection ID needs to be provided too. For simplicity the tag "me" can be used to select the default assigned connection for the User.

This end point is subject to rate limits. The API is restricted to allow five requests per five minute interval and token.

(To download price lists in the CSV-format specified on the individual connection you need to use the information here ).

Instead of fetching all revisions and then using the latest revision id to get the current price list the following can be used for both User and Connection authentications:

GET /2/connections/<ID>/pricelists/current
GET /2/connections/me/pricelists/current
GET /2/pricelists/<ID>
GET /2/pricelists/<label>

Response

{
    "networks": [
        {
            "mccmnc": [
                {
                    "mnc": "03",
                    "mcc": "648"
                }
            ],
            "comment": "",
            "price": 0.006,
            "country": {
                "name": "Zimbabwe",
                "prefix": 263,
                "code": "ZW"
            },
            "operator": "Telecel Zimbabwe (PVT) Ltd (TELECEL)",
        }
    ],
    "id": 280290,
    "timestamp": 1386085755,
    "active": true,
    "first_viewed": 1386228799,
    "parent_revision_id": 280195
}
Key Type Description
networks array An array of networks covered by this pricelist.
networks.mccmnc.mnc string MNC of the network.
networks.mccmnc.mcc string MCC of the network.
networks.comment string (Optional) Specific details about this network.
networks.price float Price of sending to this network in Euro (€).
networks.country.name string Name of the country this network resides in.
networks.country.prefix int Country calling code.
networks.country.code string Country code (ISO-3166-1).
networks.operator string Operator name.
id int Pricelist ID.
timestamp int Date of save for this pricelist.
active bool Whether this pricelist is active or not.
first_viewed int, Unix time|null First time this pricelist was accessed by customer.
parent_revision_id int Parent revision ID

CURL EXAMPLE

curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/connections/1/pricelists/current"
curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/connections/me/pricelists/current"

DEFINITION

$client->pricelist->get({CONNECTION});

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

$connectionId = 1;
$pricelist = $client->pricelist->get($connectionId);

You can also omit connection id and then we will use the "me" alias to reference the default connection

DEFINITION

var client = new beepsend(
    {
        "api_token" : "abc123"
    }
);

client.pricelist().get({CONNECTION_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});

CODE EXAMPLE

var connectionId = "me";

client.pricelist().get(connectionId).then(
    function(success) {
        // Write your success handler function here
    },
    function(error) {
        // Write your error handler function here
    }
);

DEFINITION

@interface BSConnection

    - (void)getCurrentPricelistOnCompletion:(void(^)(BSPricelist *pricelist, NSArray *errors))block;

@end

CODE EXAMPLE

[[BSConnection currentConnection] getCurrentPricelistOnCompletion:^(BSPricelist *pricelist, NSArray *errors) {

    if (!errors || errors.count == 0) {

        //Handle response (BSPricelist object)

    }
    else {

        //Handle error (array of BSError objects)

    }

}];

Receive the 200 latest price lists revisions* for a specific connection related to the authenticated user. A connection ID or alias tag "me" must be provided as reference.

GET /2/connections/<ID>/pricelists/
GET /2/connections/me/pricelists/

Response

[{
    "networks_count": 980,
    "id": 280290,
    "timestamp": 1386085000,
    "active": true,
    "first_viewed": 1386228799
}]
Key Type Description
networks_count int Number of networks covered by this pricelist.
id int Pricelist revision ID.
timestamp int Date of save for this pricelist.
active bool Whether this pricelist is active or not.
first_viewed int, Unix time First time this pricelist was accessed by customer.
* Please contact your account manager if you need more than the 200 latest price lists.

CURL EXAMPLE

curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/connections/12/pricelists/"

curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/connections/me/pricelists/"

DEFINITION

$client->pricelist->revisions({CONNECTION});

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

$revisions = $client->pricelist->revisions();

DEFINITION

var client = new beepsend(
    {
        "api_token" : "abc123"
    }
);

client.pricelist().getRevisions({CONNECTION_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});

CODE EXAMPLE

var connectionId = "me";

client.pricelist().getRevisions(connectionId).then(
    function(success) {
        // Write your success handler function here
    },
    function(error) {
        // Write your error handler function here
    }
);

You can also omit connection id and then the "me" alias is used to reference the default connection

DEFINITION

@interface

    - (void)getPricelistsOnCompletion:(void(^)(NSArray *pricelists, NSArray *errors))block;

@end

CODE EXAMPLE

[[BSConnection currentConnection] getPricelistsOnCompletion:^(NSArray *pricelists, NSArray *errors) {

    if (!errors || errors.count == 0) {

        //Handle response (array of BSPricelist objects)

    }
    else {

        //Handle error (array of BSError objects)

    }

}];

Receive pricelist for a specific connection as a csv file. A connection ID or alias tag "me" must be provided as reference.

GET /2/pricelists/<ID>.csv
GET /2/pricelists/<label>.csv
Parameter Type Description
id
Required
int Id of the connection which price list to received.
label
Required
string Label of the connection.
delimiter
Optional
string What delimiter to use for the csv output. (Default: , <comma>)
fields
Optional
string Comma separated list of fields to use in the output (will be ordered in the same way as the input).
Available fields: mcc, mnc, mccmnc, country, operator, price.
Default: mcc, mnc, country, operator, price.

Example

GET /2/pricelists/1.csv?delimiter=;&fields=mcc,mnc,operator,price

Response

mcc;mnc;operator;price
240;;Default;0.08
240;01;"TeliaSonera Mobile Networks AB Sweden (TeliaSonera Mobile Networks)";0.068

CURL EXAMPLE

curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/pricelists/1234.csv"

DEFINITION

$client->pricelist->download({CONNECTION});

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';
use Beepsend\Client;

$connectionId = 1;    
$client = new Client('abc123');

$pricelist = $client->pricelist->download($connectionId);

You can also omit connection id and then the "me" alias is used to reference the default connection

DEFINITION

var client = new beepsend(
    {
        "api_token" : "abc123"
    }
);

client.pricelist().download({CONNECTION_ID}, {DELIMITER}, {FIELDS});

CODE EXAMPLE

var connectionId = 1;

client.pricelist().download(connectionId);

DEFINITION

@interface BSConnection

    - (void)getPricelistsAsCsvOnCompletion:(void(^)(NSString *pricelist, NSArray *errors))block;

@end

CODE EXAMPLE

[[BSConnection currentConnection] getPricelistsAsCsvOnCompletion:^(NSString *pricelist, NSArray *errors) {

    if (!errors || errors.count == 0) {

        //Handle response (NSString containing data from csv file)

    }
    else {

        //Handle error (array of BSError objects)

    }

}];

Beepsend can give you price changes. To get it you have to find pricelist revisions that you want to compare.

Compare pricelist revisions from given connection and return their diff.

GET /2/pricelists/<ID>/<rev1>..<rev2>/diff
GET /2/pricelists/<label>/<rev1>..<rev2>/diff
Parameter Type Description
id
Required
int Id of the connection which pricelist are compared.
label
Required
string Label of the connection.
rev1
Required
int Id of first pricelist to compare
rev2
Required
int Id of second pricelist to compare

Example

GET /2/pricelists/1/4321..4371/diff

Response

[
    {
        "country": {
            "name": "Zimbabwe",
            "prefix": 263,
            "code": "ZW"
        },
        "operator": "Telecel Zimbabwe (PVT) Ltd (TELECEL)",
        "mccmnc": [
            {
                "mnc": "03",
                "mcc": "648"
            }
        ],
        "comment": "",
        "price": 0.006,
        "old_price":0.022,
        "diff":"price"
    }
]
Key Type Description
country.name string Name of the country this network resides in.
country.prefix int Country calling code.
country.code string Country code (ISO-3166-1).
operator string Operator name.
mccmnc array An array of mcc mnc that belong to this operator
mccmnc.mnc string MNC of the network.
mccmnc.mcc string MCC of the network.
comment string Specific details about this network.
price float Price of sending to this network in Euro (�). Price belong to pricelist given as rev2
old_price float Old price of sending to this network in Euro (�). Price belong to pricelist given as rev1
diff string Type of differece between revisions, possible values price, new or removed

CURL EXAMPLE

curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/pricelists/1/4321..4371/diff"

DEFINITION

$client->pricelist->diff({REV_1}, {REV_2}, {CONNECTION});

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

$diff = $client->pricelist->diff(4321, 4371, 1);

DEFINITION

var client = new beepsend(
    {
        "api_token" : "abc123"
    }
);

client.pricelist().diff({CONNECTION_ID}, {REV1}, {REV2}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});

CODE EXAMPLE

var connectionId = 1;
var rev1 = 1234;
var rev2 = 2134;

client.pricelist().diff(connectionId, rev1, rev2).then(
    function(success) {
        // Write your success handler function here
    },
    function(error) {
        // Write your error handler function here
    }
);

DEFINITION

@interface BSConnection

    - (void)getPricelistsDiffForPricelist:(BSPricelist *)pl1 andPricelist:(BSPricelist *)pl2 onCompletion:(void(^)(BSNetwork *pricelistDiff, NSArray *errors))block;

@end

CODE EXAMPLE

BSPricelist *pl1 = firstPricelistToCompare;
BSPricelist *pl2 = secondPricelistToCompare;

[[BSConnection currentConnection] getPricelistsDiffForPricelist:pl1 andPricelist:pl2 onCompletion:^(BSNetwork *pricelistDiff, NSArray *errors) {

    if (!errors || errors.count == 0) {

        //Handle response (BSNetwork object)

    }
    else {

        //Handle error (array of BSError objects)

    }

}];

Compare pricelist revisions from given connection and return their diff as csv file.

GET /2/pricelists/<ID>/<rev1>..<rev2>/diff.csv
GET /2/pricelists/<label>/<rev1>..<rev2>/diff.csv
Parameter Type Description
id
Required
int Id of the connection which pricelist are compared.
label
Required
string Label of the connection.
rev1
Required
int Id of first pricelist to compare
rev2
Required
int Id of second pricelist to compare
delimiter
Optional
string What delimiter to use for the csv output. (Default: , <comma>)
fields
Optional
string Comma separated list of fields to use in the output (will be ordered in the same way as the input).
Available fields: mcc, mnc, mccmnc, country, operator, old_price, price, price_diff, diff, comment.
Default: mcc, mnc, mccmnc, country, operator,o ld_price, price, price_diff, diff, comment

Example

GET /2/pricelists/1/4321..4371/diff.csv?delimiter=;&fields=mcc,mnc,operator,price,price_diff,diff

Response

mcc;mnc;operator;price;price_diff;diff
240;;Default;0.08;0.011;price
240;01;"TeliaSonera Mobile Networks AB Sweden (TeliaSonera Mobile Networks)";;0;removed

CURL EXAMPLE

curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/pricelists/1/4321..4371/diff.csv"

DEFINITION

$client->pricelist->downloadDiff({REV_1}, {REV_2}, {CONNECTION});

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

$diff = $client->pricelist->downloadDiff(4321, 4371, 1);

DEFINITION

var client = new beepsend(
    {
        "api_token" : "abc123"
    }
);

client.pricelist().diffDownload({CONNECTION_ID}, {REV1}, {REV2}, {DELIMITER}, {FIELDS});

CODE EXAMPLE

var connectionId = 1;
var rev1 = 1234;
var rev2 = 2134;

client.pricelist().diffDownload(connectionId, rev1, rev2);

DEFINITION

@interface BSConnection

    - (void)getPricelistsDiffAsCsvForPricelist:(BSPricelist *)pl1 andPricelist:(BSPricelist *)pl2 onCompletion:(void(^)(NSString *pricelist, NSArray *errors))block;

@end

CODE EXAMPLE

BSPricelist *pl1 = firstPricelistToCompare;
BSPricelist *pl2 = secondPricelistToCompare;

[[BSConnection currentConnection] getPricelistsDiffAsCsvForPricelist:pl1 andPricelist:pl2 onCompletion:^(NSString *pricelist, NSArray *errors) {

    if (!errors || errors.count == 0) {

        //Handle response (NSString containing data from csv file)

    }
    else {

        //Handle error (array of BSError objects)

    }

}];

This endpoint requres a valid User API-Token. Read more about Users and Connections.

Get details regarding your user.

GET /2/users/me

Response

{
    "id": 4,
    "name": "Beep",
    "email": "beep@beepsend.com",
    "trial": false,
    "disabled": false,
    "phone": [
        {
            "number": "46736007518",
            "verified": true,
            "primary_number": true
        }
    ],
    "customer": [
        {
            "id": 1,
            "name": "Beepsend AB",
            "disabled": false,
            "trial": false
        }
    ],
    "api_token": "abc123",
    "default_connection": {
        "id": 27,
        "label": "The Beep Connection",
        "system_id": "beep-connect",
        "type": 1
    },
    "user_types": [
        {
            "id": 1,
            "name": "Technical Contact"
        }
    ],
    "max_level": 2,
    "verified": {
        "email": true,
        "terms": true
    }
}
Key Type Description
id int Unique user ID.
name string Name to recognise your User by.
email string User email.
trial bool Indicates whether user is in trial mode
disabled bool Indicates whether user is disabled
phones array Array of user phone numbers.
phone.number string Phone number
phone.verified bool Indicates if the phone is verified.
phone.primary_number bool Indicates if the phone is user's primary number.
customer.id int Unique customer ID.
customer.name string Name of customer the user is associated with.
customer.disabled bool Indicates if customer and all users are disabled.
customer.trial bool Indicates if customers all users are in trial mode.
api_token string API Token belonging to this User.
default_connection array Object with information regarding the default connection for this user.
default_connection.id int Unique connection ID.
default_connection.label string Name of connection.
default_connection.system_id string Connection login name. Used for API v.1 as well as SMPP.
user_types array List of types that applies to this user.
user_types.id int Type ID.
user_types.name string Type name to describe its function
max_level int Simple permission model. Allows access to all version 2 endpoints.
verified.email bool If the users email address is verified or not.
verified.terms bool True if the user has agreed to the terms & conditions.

CURL EXAMPLE

curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/users/me"

DEFINITION

$client->user->get();

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');
$user = $client->user->get();

DEFINITION

var client = new beepsend(
    {
        "api_token" : "abc123"
    }
);

client.user().get().then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});

CODE EXAMPLE

client.user().get().then(
    function(success) {
        // Write your success handler function here
    },
    function(error) {
        // Write your error handler function here
    }
);

DEFINITION

@interface BSUser

 + (BSUser *)currentUser;

@end

CODE EXAMPLE

//It is necessary to call this method at application start so there would be enough time for user to initialize
//Because it is singleton it will be initialized only first time
BSUser *user = [BSUser currentUser];

This endpoint requres a valid User API-Token. Read more about Users and Connections.

Update properties for your user.

PUT /2/users/me
Parameter Type Description
name
Optional
string Name to recognise your user by.
phones
Optional
array Update users phones, update must contain primary number. Expects object in array containing number. Note that this will not be immediately changed. An SMS will be sent out to your new number asking you to verify the change. Until verified your current number will be used. The verification SMS will be valid for 24 hours.
default_connection
Optional
array Object with default connection.
default_connection.id
Optional
int Connection ID that should be the default for this user.
user_types
Optional
array List of objects with user types that applies for this user.
user_types.id
Optional
int User type ID.
verified.terms
Optional
bool True if you accept the terms & conditions.

This endpoint supports partial updates. Any omitted field in a model will read in the current value.

Available user types.

ID Type
1 Technical Contact
2 Account Contact
3 Support Contact
4 Pricelist Contact
5 Finance Contact.

Request body

Initialise a request with the fields you would like to update.

{
    "name": "My user",
    "default_connection": {
        "id": 27
    },
    "user_types": [
        {
            "id": 1
        },
        {
            "id": 5
        }
    ],
    "verified": {
        "terms": true
    }
}

Response

A user object.

CURL EXAMPLE

curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X PUT -d '{"name": "Christian Nilsson", "default_connection": {"id": 27}, "user_types": [{"id": 1}, {"id": 5}], "verified": {"terms": true}' \
"https://api.beepsend.com/2/users/me"

DEFINITION

$client->user->update({OPTIONS});

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

$data = array(
    'name' => 'My user',
    'default_connection' => array(
        'id' => 27
    ),
    'user_types' => array(
        array('id' => 1),
        array('id' => 5)
    ),
    'verified' => array(
        'terms' => true
    )
);

$user = $client->user->update($data);

DEFINITION

var client = new beepsend(
    {
        "api_token" : "abc123"
    }
);

client.user().update({OPTIONS}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});

CODE EXAMPLE

var options = {
    "name": "My user",
    "default_connection": {
        "id": 27
    },
    "user_types": [
        {
            "id": 1
        },
        {
            "id": 5
        }
    ],
    "verified": {
        "terms": true
    }
};

client.user().update(options).then(
    function(success) {
        // Write your success handler function here
    },
    function(error) {
        // Write your error handler function here
    }
);

DEFINITION

@interface BSUser

    @property (nonatomic, strong) NSString *name;
    @property (nonatomic, strong) NSString *phone;
    @property (nonatomic, strong) BSConnection *defaultConnection;
    @property (nonatomic, strong) NSArray *userTypes;
    @property (nonatomic, strong, readonly) BSVerified *verified;

    - (void)updateUserOnCompletion:(void(^)(NSArray *errors))block;

@end

CODE EXAMPLE

[BSUser currentUser].name = @"New name";
[BSUser currentUser].phone = @"012345678911";
[BSUser currentUser].defaultConnection = newConnection;
[BSUser currentUser].userTypes = @[userType1, userType2];
[BSUser currentUser].verified.termsVerified = @YES

[[BSUser currentUser] updateUserOnCompletion:^(NSArray *errors) {

    if (!errors || errors.count == 0) {

        //User updated

    }
    else {

        //Handle error (array of BSError objects)

    }

}];

This endpoint requres a valid User API-Token. Read more about Users and Connections.

Update email for your user.

PUT /2/users/me/email
Parameter Type Description
email
Required
string The email address you would like to change to.
password
Required
string Your current password. This is needed for extra security.

Request body

{
    "email": "newemail@beepsend.se",
    "password": "supersecret"
}

Response

204 no content header.

After having changed user email, an email will be sent out to the new email address. In this email is a verification link that must be visited within 24 hours for the email change to go through. Until then, the old email is used.

CURL EXAMPLE

curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X PUT -d '{"email": "newemail@beepsend.se", "password": "supersecret"}' \
"https://api.beepsend.com/2/users/me/email"

DEFINITION

$client->user->updateEmail({EMAIL}, {CURRENT_PASSWORD});

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

$user = $client->user->updateEmail('newemail@beepsend.se', 'supersecret');

DEFINITION

var client = new beepsend(
    {
        "api_token" : "abc123"
    }
);

client.user().updateEmail({EMAIL}, {PASSWORD}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});

CODE EXAMPLE

var newEmail = "newemail@beepsend.se";
var password = "yourpassword";

client.user().updateEmail(newEmail, password).then(
    function(success) {
        // Write your success handler function here
    },
    function(error) {
        // Write your error handler function here
    }
);

DEFINITION

@interface BSUser

    @property (nonatomic, strong) NSString *email;

    - (void)updateUserEmailWithPassword:(NSString *)password onCompletion:(void(^)(NSArray *errors))block;

@end

CODE EXAMPLE

[BSUser currentUser].email = @"newemail@mail.com";

[[BSUser currentUser] updateUserEmailWithPassword:@"password" onCompletion:^(NSArray *errors) {

    if (!errors || errors.count == 0) {

        //Email updated

    }
    else {

        //Handle error (array of BSError objects)

    }

}];

This endpoint requres a valid User API-Token. Read more about Users and Connections.

Update user password.

PUT /2/users/me/password
Parameter Type Description
password
Required
string Your current password. This is needed for extra security.
new_password
Required
string The new password to be set for your user.

Request body

{
    "password": "supersecret",
    "new_password": "donotlookplease"
}

Response

204 no content header.

CURL EXAMPLE

curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X PUT -d '{"password": "supersecret", "new_password": "donotlookplease"}' \
"https://api.beepsend.com/2/users/me/password"

DEFINITION

$client->user->updatePassword({NEW_PASSWORD}, {OLD_PASSWORD});

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

$user = $client->user->updatePassword('donotlookplease', 'supersecret');

DEFINITION

var client = new beepsend(
    {
        "api_token" : "abc123"
    }
);

client.user().updatePassword({OLD_PASSWORD}, {NEW_PASSWORD}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});

CODE EXAMPLE

var oldPassword = "oldPassword";
var newPassword = "newPassword";

client.user().updatePassword(oldPassword, newPassword).then(
    function(success) {
        // Write your success handler function here
    },
    function(error) {
        // Write your error handler function here
    }
);

DEFINITION

@interface BSUser

    - (void)changePassword:(NSString *)currentPassword withNewPassword:(NSString *)newPassword onCompletion:(void(^)(NSArray *errors))block;

@end

CODE EXAMPLE

[[BSUser currentUser] changePassword:@"currentPassword" withNewPassword:@"newPassword" onCompletion:^(NSArray *errors) {

    if (!errors || errors.count == 0) {

        //Password changed

    }
    else {

        //Handle error (array of BSError objects)

    }

}];

If you have forgotten or in other ways lost control over your password, you can issue a reset. When doing so, Beepsend will send an email with a link to where you can get your new password.

GET /2/users/passwordreset?email=myemail@beepsend.com
Parameter Type Description
email string Your login email.

Response

204 no content header.

Set new password

In the reset email sent out by Beepsend you will find a link to restore your password. At the end of that link is a hash that can be used to set a new password.

PUT /2/users/password/<hash>
Parameter  Type  Description
password string Your new password

Request body

{
    "password": "mynewpassword"
}

Response

A user object. See Users.

CURL EXAMPLE

curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/users/passwordreset?email=myemail@beepsend.com"

/* Set new password with given hash */
curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X PUT -d '{"password": "mynewpassword"}' \
"https://api.beepsend.com/2/users/password/<hash>"

DEFINITION

$client->user->resetUserPassword({EMAIL});
$client->user->setNewPassword({HASH}, {EMAIL});

CODE EXAMPLE RESET

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

$client->user->resetUserPassword('myemail@beepsend.com');

CODE EXAMPLE VERIFY

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

$user = $client->user->setNewPassword('<hash in email>', 'mynewpassword');

DEFINITION

var client = new beepsend(
    {
        "api_token" : "abc123"
    }
);

client.user().resetUserPassword({EMAIL}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});

client.user().setNewPassword({HASH}, {EMAIL}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});

CODE EXAMPLE

var email = "myemail@beepsend.com";

client.user().resetUserPassword(email).then(
    function(success) {
        // Write your success handler function here
    },
    function(error) {
        // Write your error handler function here
    }
);

/* After receiving reset password email you need to call next endpoint and provide hash, that you received in password reset email, and new password as well */

var hash = "b123ais123";
var newPassword = "yournewpassword";

client.user().setNewPassword(hash, newPassword).then(
    function(success) {
        // Write your success handler function here
    },
    function(error) {
        // Write your error handler function here
    }
);

DEFINITION

@interface BSUser

    - (void)resetUserPasswordOnCompletion:(void(^)(BOOL success, NSArray *errors))block;

@end

CODE EXAMPLE

[[BSUser currentUser] resetUserPasswordOnCompletion:^(BOOL success, NSArray *errors) {

    if (!errors || errors.count == 0) {

        //Password successfully reseted

    }
    else {

        //Handle error (array of BSError objects)

    }

}];

This endpoint requres a valid User API-Token. Read more about Users and Connections.

If you think that the user token used for authenticating with the Beepsend API has been compromised you can use this method (with your current user token and password) to reset the user token.

GET /2/users/me/tokenreset
GET /2/users/<id>/tokenreset
Parameter Type Description
password string Your current password. Needed to not allow unauthorized people to reset the token.

Response

{
    "api_token": "abc123",
}
Key Type Description
api_token string New API Token for this connection.

CURL EXAMPLE

curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/users/<id>/tokenreset"

DEFINITION

$client->user->resetUserToken({PASSWORD});

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

$token = $client->user->resetUserToken('mysecretpassword');

DEFINITION

var client = new beepsend(
    {
        "api_token" : "abc123"
    }
);

client.user().resetUserToken({PASSWORD}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});

CODE EXAMPLE

var password = "yourpassword";

client.user().resetUserToken(password).then(
    function(success) {
        // Write your success handler function here
    },
    function(error) {
        // Write your error handler function here
    }
);

DEFINITION

@interface BSUser

    - (void)resetUserTokenWithPassword:(NSString *)password onCompletion:(void(^)(NSArray *errors))block;

@end

CODE EXAMPLE

[[BSUser currentUser] resetUserTokenWithPassword:@"password" onCompletion:^(NSArray *errors) {

    if (!errors || errors.count == 0) {

        //Token reseted

    }
    else {

        //Handle error (array of BSError objects)

    }

}];
For sending multiple messages or send to a group you need to use our /2/sendouts endpoint
We have depricated our old endpoints /2/sms and /2/batches. Please note that we will still be supporting the old endpoints but that we strongly urge our users to start using our new endpoints /2/send and /2/sendouts.

Each sent message require a token either assigned to a Connection or a User that has a default connection set up. By specifying a label of a different Connection belonging to your Company this will instead be used, granted the User has access-rights to this Connection. If authenticated by User token and no Connection is specified, the default assigned Connection will be used.

A message can carry 160 characters if in the Latin alphabet and 70 if content is Unicode. The Beepsend Gateway will automatically split up the message if the content exceeds the maximum character limit based on the content encoding. When sending UTF-8 encoding the Beepsend Gateway will try and convert to GSM7 if possible to avoid splitting at 70 characters.

The endpoint for sending messages is:

POST /2/send/

Specify which connection to use for sending this message. This can be useful if you are authenticating with a User token and do not want to send with your default connection.

POST /2/send/<connection id>
POST /2/send/<connection label>
Parameter Type Description
to
Required
string The mobile phone number starting with country code and no + sign. Also referred to sometimes as MSISDN.
body
Required
string Message body.
from
Required
string Sender id. Check below for a list of allowed formats.
encoding
Optional
string UTF-8, ISO-8859-15 or Unicode. If omitted, the default charset is UTF-8. The unicode uses the UCS2 standard UTF16-BE.
message_type
Optional
string flash or binary. If omitted, a normal message will be sent. Flash sms can contain only ASCII alphanumeric characters.
validity_period
Optional
int, Unix time How long a message is relevant to the end user. If this expires, the message won't continue to be routed. Default is infinite.
receive_dlr
Optional
int Specify whether delivery reports should be sent to your DLR Callback URL.
0: Disable, 1: Always, 2: Only on failure. Default is 1.
auto_gsm7_conversion
Optional
true | false Setting this flag to false will disable UTF-8 to GSM7 conversion. By default this flag is true.

Request body

{
    "to": "46736007518",
    "body": "Hello World! 你好世界!",
    "from": "Beepsend",
    "encoding": "UTF-8",
    "receive_dlr": 0
}

Response

[
    {
        "id": [
            "01108500014328897161775546736007518"
        ],
        "from": "Beepsend",
        "to": "46736007518"
    }
]
Key Type Description
id array | null Unique Beepsend generated ID. If the SMS got rejected, null.
to string Input destination for this particular SMS.
from string Input source.

The following formats are allowed for from.

  • Alphanumeric signs with upper och lower case characters (a-z, A-Z, 0-9). The maximum allowed characters are 11. We crop the from address at 11 characters.

  • MSISDN numbers, international format. Minimum 9 chars, max 17 chars.

  • Short numbers / codes, national format. Maximum length 7 chars.

Local restrictions apply. Check with your account manager for the destinations you aim to send to for details.

Long SMS

Long SMS are messages with more than 160 (70 if unicode encoding) characters. Beepsend will automatically split up your long messages before sending so you don't have to worry about it. Unless you're sending binary SMS.

Since long SMS are really just two or more messages with a special identifier that connects them, you will receive a response with separate IDs for each message you are sending. When sending with our a sendouts endpoint you will get a sendout id which you then need to do a lookup with the provided id to get all the MSISDNs.

Billing is done based on how many parts the message in total requires.

CURL EXAMPLE

curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X POST -d '{"to": "46736007518", "body": "Hello World! 你好世界!", "from": "Beepsend", "encoding": "UTF-8", "receive_dlr": 0}' \
"https://api.beepsend.com/2/send/"

DEFINITION

$client->message->send({TO}, {FROM}, {MESSAGE}, {CONNECTION}, {ENCODING}, {OPTIONS});

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

$connectionId = 1;

$options = array(
    'receive_dlr' => false
);

$message = $client->message->send(
    '46736007502',
    'Beepsend',
    'Hello World! 你好世界!',
    $connectionId,
    'UTF-8',
    $options
);

You can also set null for connection id and then the "me" alias is used to reference the default connection

POST /2/send/
POST /2/send/<connection id>
POST /2/send/<connection label>

If your system rather sends the messages using binary content we offer a service for this. The combined length of a binary message and UDH can not be longer than 140 bytes (280 hex characters), if you want to send concatenated messages you have to do this by sending a sequence of messages with the appropriate UDH.

To send a binary SMS. You need to have message_type set to binary. When sending binary SMS the following options become available.

Parameter Type Description
udh
Optional
string User Data Header. Can be used to send Concatenated or Wap Push messages.
dcs
Optional
int Data coding settings. For binary messages this is set to 4 (8-bit binary) by default. Should be 0 for gsm7 encoded messages and 8 for UCS-2 encoded messages.

CURL EXAMPLE

curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X POST -d '{"to": "46736007518", "message": "48656c6c6f20576f726c6421", "from": "Beepsend", "encoding": "UTF-8", "message_type": "binary"}' \
"https://api.beepsend.com/2/send/"

If something terrible were to happen. We'll send back a neat array of error codes and descriptions.

Invalid request example

{
    "to": [
        "12345"
    ],
    "from": "x"
}

Response

[
    {
       "errors": [
           {
               "code": 1030,
               "description": ""from" can not be shorter than 2 characters"
           },
           {
               "code": 1026,
               "description": ""message" is required and can not be null"
           }
       ]
    }
]

The API can be utilized to get details of any message sent through Beepsend no matter if you submitted it via SMPP or HTTP.

Get details regarding one message.

This end point is subject to rate limits. The API is restricted to allow 90 requests in a 15 minute interval for a specific request and token.
GET /2/send/<sms id>

Response

{
    "id": "12345",
    "body": "Hello World!",
    "hex_body": "48656c6c6f20576f726c6421",
    "connection": {
        "id": 7,
        "label": "superman-connection"
    },
    "to": {
        "address": "46406007500",
        "ton": 1,
        "npi": 1
    },
    "from": {
        "address": "Beepsend",
        "ton": 1,
        "npi": 1
    },
    "validity_period": "131102072704000-",
    "data_coding": 3,
    "timestamps": {
        "sms": {
            "in": 1383225355,
            "delivered": 1383225359
        },
        "dlr_out": 1383225359
    },
    "dlr": {
        "status": "DELIVRD",
        "error": 0
    },
    "price": 0.068,
    "mccmnc": {
        "mcc": "240",
        "mnc": "01"
    }
}
Key Type Description
id string Unique Beepsend generated ID.
body string The message body of sent SMS.
hex_body string Hex encoded string containing the raw body of sent SMS (or sms part if it's multipart message).
connection array Connection details.
connection.id int The id of the connection that was used to send the SMS.
connection.label string The name of the connection that was used to send the SMS.
to.address string Destination address.
to.ton int Type of number.
to.npi int Number Plan Index.
from.address string Source address.
from.ton int Type of number.
from.npi int Number Plan Index.
validity_period string Until what date and time the message is considered valid for routing. Formatted like YYMMDDhhmmsstnnp according to the SMPP standard.
data_coding int Data coding settings. 0 for Gsm7 encoded messages. 8 for UCS-2 encoded messages and 4 for binary messages. Can be set manually if sending Binary SMS.
timestamps.sms.in int When the message reached Beepsend in Unix time.
timestamps.sms.delivered int | null When the message was delivered to handset. In Unix time. null if not yet delivered.
timestamps.dlr_out int | null When the Delivery Report left our system to reach your DLR Callback URL. null if message has not been delivered yet.
dlr.status string | null One of the following: DELIVRD, EXPIRED, REJECTD, UNKNOWN, UNDELIV, FAILED. Or null if message has not yet been delivered.
dlr.error int | null Specific return codes regarding message delivey. 0 if OK. Beepsend Return Codes. null if message has not been delivered yet.
price float Message price.
mccmnc.mcc string Destination mcc.
mccmnc.mnc string Destination mnc.

In case of a multipart SMS. body will be concatenated to contain all the parts.

CURL EXAMPLE

curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/sms/12345"

DEFINITION

$client->message->lookup({SMS_ID});

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

$smsId = 12345;
$message = $client->message->lookup($smsId);

DEFINITION

var client = new beepsend(
    {
        "api_token" : "abc123"
    }
);

client.messages().lookup({MESSAGE_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});

CODE EXAMPLE

var messageId = 12345;

client.messages().lookup(messageId).then(
    function(success) {
        // Write your success handler function here
    },
    function(error) {
        // Write your error handler function here
    }
);

DEFINITION

@interface BSConnection

    - (void)getDetailsForSMS:(BSMessage *)message onCompletion:(void(^)(BSLookup *lookup, NSArray *errors))block;

@end

CODE EXAMPLE

BSMessage *message = messageThatWasSent;

[[BSConnection currentConnection] getDetailsForSMS:message onCompletion:^(BSLookup *lookup, NSArray *errors) {

    if (!errors || errors.count == 0) {

        //Handle response (BSLookup object)

    }
    else {

        //Handle error (array of BSError objects)

    }

}];
For general information about sending SMS with our API please read the introduction to sending SMS

Our Sendout endpoint is for doing some additional nifty things with your message. You can send to multiple adresses, send to a group and set a send time for your message. You can also delete,update and add recipients to a message before it has been sent, granted you set a send time.

The endpoint for sending multiple messages is:

POST /2/sendouts/

Specify which connection to use for sending this message. This can be useful if you are authenticating with a User token and do not want to send with your default connection.

POST /2/sendouts/<connection id>
* You need to specify a recipient either by using the to parameter or groups.
Parameter Type Description
sms.to
Required *
array (string) The mobile phone number starting with country code and no + sign. Also referred to sometimes as MSISDN. Supports multiple values.
Note Multiple destinations count as multiple messages and will be charged as such.
sms.groups
Required *
array (int) The id of contants group that have to exist in our system. Supports multiple values.
sms.body
Required
string Message body.
sms.from
Required
string Sender id. Check below for a list of allowed formats.
label Optional string The name of your sendout of messages.
send_time Optional int, Unix time Schedule message to be delivered at a certain time in the future. Note Credits will be deducted from your connection at the time of sending for the price at that time. Therefore we do not encourage delivery dates set long in the future.
receive_dlr Optional int Specify whether delivery reports should be sent to your DLR Callback URL.
0: Disable, 1: Always, 2: Only on failure. Default is 1.
sms.encoding Optional string UTF-8, ISO-8859-15 or Unicode. If omitted, the default charset is UTF-8. The unicode uses the UCS2 standard UTF16-BE.
sms.message_type Optional string flash or binary. If omitted, a normal message will be sent. Flash sms can contain only ASCII alphanumeric characters.
sms.validity_period Optional int, Unix time How long a message is relevant to the end user. If this expires, the message won't continue to be routed. Default is infinite.
sms.auto_gsm7_conversion Optional true | false Setting this flag to false will disable UTF-8 to GSM7 conversion. By default this flag is true.

The following formats are allowed for from.

  • Alphanumeric signs with small characters or capitals (a-z, A-Z, 0-9). The maximum allowed characters are 11. We crop the from address at 11 characters.

  • MSISDN numbers, international format. Minimum 9 chars, max 17 chars.

  • Short numbers / codes, national format. Maximum length 7 chars.

Local restrictions apply. Check with your account manager for the destinations you aim to send to for details.

A sendout will be stored for 30 days from the last time it was updated.

Long SMS

Long SMS are messages with more than 160 (70 if unicode encoding) characters. Beepsend will automatically split up your long messages before sending so you don't have to worry about it. Unless you're sending binary SMS.

Since long SMS are really just two or more messages with a special identifier that connects them, you will receive a response with separate IDs for each message you are sending. When sending with our a sendouts endpoint you will get a sendout id which you then need to do a lookup with the provided id to get all the MSISDNs.

Billing is done based on how many parts the message in total requires.

Request body

{
    "label": "Lottery winner",
    "send_time": 1433116800,
    "sms": {
        "groups": [
            1,
            2
        ],
        "to": [
            "123456",
            "1234567"
        ],
        "body": "You won!",
        "from": "Beepsend",
        "encoding": "UTF-8"
    }
}

Response

[
    {
        "id": 24151,
        "label": "Lottery winner",
        "connection_id": 17755,
        "send_time": 1433116800,
        "sms": {
            "groups": [
                1,
                2
            ],
            "to": [
                "123456",
                "1234567"
            ],
            "from": "Beepsend",
            "message": "You won!"
        }
    }
]
Key Type Description
id int Unique sendout id.
label string Name of the Sendout.
conneciton_id int Connection id
send_time int, Unix timestamp Schedule message to be delivered at a certain time in the future. Note Credits will be deducted from your connection at the time of sending for the price at that time. Therefore we do not encourage delivery dates set long in the future (max is 30 days).
sms object Sms object with the data about your message, groups, to, from and any optional setting.

CURL EXAMPLE

curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X POST -d '{"label": "Lottery winner", "send_time": 1433116800, "sms": { "groups": [1,2],"to": ["123456","1234567"], "body": "You won!", "from": "Beepsend", "encoding": "UTF-8"}}' \
"https://api.beepsend.com/2/sendouts/"

DEFINITION

$client->message->sendouts({GROUPS}, {TO}, {MESSAGE}, {CONNECTION}, {ENCODING}, {OPTIONS});

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

$connectionId = 1;

$options = array(
    'receive_dlr' => false
);

$message = $client->message->sendouts(
    [1,2], /* Id of groups that we want to send sms too */
    ["123456","1234567"], /* List of numbers that we want to send sms too*/
    'Beepsend',
    'You won!',
    $connectionId,
    'UTF-8',
    $options
);

You can also set null for connection id and then the "me" alias is used to reference the default connection

Send messages to groups or numbers.

POST /2/sendouts/

Use specific connections to send messages

POST /2/sendouts/<connection id>

You can send single SMS or sendout SMS but instead using 1 or more to addresses you can import contacts and send to full contacts group

To send message to contacts groups just add to standard sms parameter groups, parameter to is optional

Parameter Type Description
groups
Required
array (string) The id of contants group that have to exist in our system. Supports multiple values in an array.
to
Optional
array (string) The mobile phone number starting with country code and no + sign. Also referred to sometimes as MSISDN. Supports multiple values in an array.

Request body

{
    "label": "Lottery winner",
    "send_time": 1433116800,
    "sms": {
        "groups": [
            1,
            2
        ],
        "body": "You won!",
        "from": "Beepsend",
        "encoding": "UTF-8"
    }
}

Response

[
    {
        "id": 24154,
        "label": "Lottery winner",
        "connection_id": 17755,
        "send_time": 1433116800,
        "sms": {
            "groups": [
                1,
                2
            ],
            "to": null,
            "from": "Beepsend",
            "message": "You won!"
        }
    }
]
Key Type Description
id int Unique sendout id.
label string Name of the Sendout.
conneciton_id int Connection id
send_time int, Unix timestamp Schedule message to be delivered at a certain time in the future. Note Credits will be deducted from your connection at the time of sending for the price at that time. Therefore we do not encourage delivery dates set long in the future (max is 30 days).
sms object Sms object with the data about your message, groups, to, from and any optional setting.

CURL EXAMPLE

curl -H "Authorization: Token abc123" \
-H "Content-Type: application/json" \
-X POST -d '{"label": "Lottery winner", "send_time": 1433116800, "sms": { "groups": [1,2], "body": "You won!", "from": "Beepsend", "encoding": "UTF-8"}}' \
"https://api.beepsend.com/2/sendouts/"

DEFINITION

$client->message->sendouts({GROUPS}, {TO}, {MESSAGE}, {CONNECTION}, {ENCODING}, {OPTIONS});

CODE EXAMPLE

require_once __DIR__ . '/vendor/autoload.php';

use Beepsend\Client;
$client = new Client('abc123');

$connectionId = 1;

$options = array(
    'receive_dlr' => false
);

$message = $client->message->sendouts(
    [1,2], /* Id of groups that we want to send sms too */
    [""], /* Empty list of phone numbers*/
    'Beepsend',
    'You won!',
    $connectionId,
    'UTF-8',
    $options
);

You can also set null for connection id and then the "me" alias is used to reference the default connection

You can:

  • Change the message
  • Add/remove recipients
  • You will not be able to alter a sendout once the send time has passed

    The endpoint for updating an existing sendout is:

    PUT /2/sendouts/<sendout id>
    Parameter Type Description
    id
    Required
    int Unique sendout id for the sendout you wish to update or alter.
    sms.to
    Required *
    array (string) The mobile phone number starting with country code and no + sign. Also referred to sometimes as MSISDN. Supports multiple values.
    Note Multiple destinations count as multiple messages and will be charged as such.
    sms.groups
    Required *
    array (int) The id of group that have to exist in our system. Supports multiple values.
    sms.body
    Required
    string Message body.
    sms.from
    Required
    string Sender id. Check below for a list of allowed formats.
    label Optional string The name of your sendout of messages.
    send_time Optional int, Unix time Schedule message to be delivered at a certain time in the future. Note Credits will be deducted from your connection at the time of sending for the price at that time. Therefore we do not encourage delivery dates set long in the future.
    receive_dlr Optional int Specify whether delivery reports should be sent to your DLR Callback URL.
    0: Disable, 1: Always, 2: Only on failure. Default is 1.
    sms.encoding Optional string UTF-8, ISO-8859-15 or Unicode. If omitted, the default charset is UTF-8. The unicode uses the UCS2 standard UTF16-BE.
    sms.message_type Optional string flash or binary. If omitted, a normal message will be sent. Flash sms can contain only ASCII alphanumeric characters.
    sms.validity_period Optional int, Unix time How long a message is relevant to the end user. If this expires, the message won't continue to be routed. Default is infinite.
    sms.auto_gsm7_conversion Optional true | false Setting this flag to false will disable UTF-8 to GSM7 conversion. By default this flag is true.

    Request body

    {
        "label": "Lottery winner",
        "send_time": 1433116800,
        "sms": {
            "groups": [
                1,
                2
            ],
            "to": [
                "123456",
                "1234567"
            ],
            "body": "You won!",
            "from": "Beepsend"
        }
    }
    

    Response

    [
        {
            "id": 24151,
            "label": "Lottery winner",
            "connection_id": 17755,
            "send_time": 1433116800,
            "sms": {
                "groups": [
                    1,
                    2
                ],
                "to": [
                    "123456",
                    "1234567"
                ],
                "from": "Beepsend",
                "message": "You won!"
            }
        }
    ]
    
    Key Type Description
    id int Unique sendout id.
    label string Name of the Sendout.
    connection_id int Connection id
    send_time int, Unix timestamp Schedule message to be delivered at a certain time in the future. Note Credits will be deducted from your connection at the time of sending for the price at that time. Therefore we do not encourage delivery dates set long in the future (max is 30 days).
    sms object Sms object with the data about your message, groups, to, from and any optional setting.

    Note: Credits will be deducted from your connection at the time of sending for the price at that time. Therefore we do not encourage delivery dates set long in the future (max is 30 days).

    Error Codes Description
    1 This Sendout has already been delivered or is in the process of being delivered.
    2 Id does not exist.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" \
    -X PUT -d '{"label": "Lottery winner", "send_time": 1433116800, "sms": { "groups": [14589,14581], "body": "You won!", "from": "Beepsend", "encoding": "UTF-8"}}' \
    "https://api.beepsend.com/2/sendouts/<sendout id>"
    

    The endpoint for deleting a Sendout messages is:

    DELETE /2/Sendouts/<id>

    Please note: You can only delete a Sendout if you have specified a send time and if that send time is in the future.

    Response

    {
        "response": {
            "code": 0,
            "description": "Sendout deleted"
        }
    }
    
    Status Code Description
    0 Sendout deleted.
    1 This Sendout has already been processed or are being processed.
    2 Id does not exist.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -X DELETE "https://api.beepsend.com/2/sendouts/<id>"
    

    Get details of your created sendouts

    This end point is subject to rate limits. The API is restricted to allow 90 requests in a 15 minute interval for a specific request and token.
    GET /2/sendouts/
    GET /2/sendouts/?<parameter>=<value>
    Parameter Type Description
    count
    Optional
    int How many objects to fetch. Maximum 200, default 200.
    offset
    Optional
    int What offset in result set to fetch data from.

    Response

    [
        {
            "id": 24160,
            "connection_id": "17755",
            "label": "Lottery winner",
            "date_created": 1432890161,
            "send_time": 1433116800,
            "processed": 51512,
            "status": 2,
            "sms": {
                "groups": [
                    1,
                    2
                ],
                "to": null,
                "from": "Beepsend",
                "message": "You won!",
                "receive_dlr": 1,
                "encoding": "utf-8",
                "message_type": null,
                "validity_period": "",
                "auto_gsm7_conversion": true,
                "sendout": {
                    "label": "Lottery winner",
                    "id": "24160"
                }
            }
        },
        {
            "id": 24155,
            "connection_id": "17755",
            "label": "Lottery Loser",
            "date_created": 1432889596,
            "send_time": 1433116800,
            "processed": 2,
            "status": 2,
            "sms": {
                "groups": null,
                "to": [
                    "46123456789",
                    "46987654321"
                ],
                "from": "Beepsend",
                "message": "You lost!",
                "receive_dlr": 1,
                "encoding": "utf-8",
                "message_type": null,
                "validity_period": "",
                "auto_gsm7_conversion": true,
                "sendout": {
                    "label": "Lottery Loser",
                    "id": "24155"
                }
            }
        }
    ]
    
    Key Type Description
    id int Unique sendout id.
    label string Name of the Sendout.
    date_created int, Unix time Creation time of the Sendout.
    last_used int, Unix time Last time the batch was used to send a message.
    processed int Number of processed messages.
    status int 0 for pending, 1 for in progress and 2 for sent.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/sendouts/?<parameter>=<value>"
    

    Two Way Sendout

    This call will give a paginated overview of messages in a sendout, complete with sent and received message body, recipient number and contact details, if recipient number exists in user contacts. The mobile terminated messages are matched with their mobile originated counterpart

    GET /2/sendouts/<ID>/messages/
    Parameter Type Description
    count
    Optional
    int How many objects to fetch. Maximum 200, default 200.
    offset
    Optional
    int What offset in result set to fetch data from. Default is 0.

    Response

    [
      {
        "mt_sms_id": "889000680270500421",
        "mt_body": "What is your name?",
        "mt_timestamp": 1418030569,
        "mo_sms_id": "889000680270500422",
        "mo_body": "Sir Lancelot",
        "mo_timestamp": 1418030569,
        "dlr_stat": "DELIVRD",
        "to" : {
            "number": "46736007500",
            "contact" : {
                "firstname": "Foo",
                "lastname": "Bar"
            }
        }
      },
      {
        "mt_sms_id": "889000680141388005",
        "mt_body": "What is your quest?",
        "mt_timestamp": 1418030569,
        "mo_sms_id": "889000680141388006",
        "mo_body": "To seek the holy grail",
        "mo_timestamp": 1418030569,
        "dlr_stat": "DELIVRD",
        "to" : {
            "number": "46736007500",
            "contact" : {
                "firstname": "Foo",
                "lastname": "Bar"
            }
        }
      },
      {
        "mt_sms_id": "889000680141388005",
        "mt_body": "What is your favorite color?",
        "mt_timestamp": 1418030569,
        "mo_sms_id": "889000680141388006",
        "mo_body": "BLUE!",
        "mo_timestamp": 1418030569,
        "dlr_stat": "DELIVRD",
        "to" : {
            "number": "46736007500",
            "contact" : {
                "firstname": "Foo",
                "lastname": "Bar"
            }
        }
      }
    ]
    
    Key Type Description
    mt_sms_id string Unique Beepsend generated ID.
    mt_body string UTF-8 encoded message body of the mobile terminated message.
    mt_timestamp int|null Unix time of when the message was sent.
    mo_sms_id string Unique Beepsend generated ID.
    mo_body string UTF-8 encoded message body of the mobile originated message.
    mo_timestamp int|null Unix time of when a reply was received.
    dlr_stat string Response status.
    to object
    to.number string Recipient number
    to.contact object
    to.contact.firstname string Firstname of contact.
    to.contact.lastname string Lastname of contact.

    Two Way sendout CSV

    This call will give all messages in a sendout formatted as CSV.

    GET /2/sendouts/<ID>/messages.csv
    Parameter Type Description
    delimiter
    Optional
    string What delimiter to use for the csv output. (Default: , <comma>)

    Fields in the CSV file are

    Field Description
    number Recipient's number.
    firstname Firstname of the contact (might be empty).
    lastname Lastname of the contact (might be empty).
    sent_sms_id Outgoing SMS ID.
    sent_body Text sent to the recipient.
    sent_sms_timestamp ISO-8601 formatted time when the message was sent.
    delivery_status Status of the outgoing message.
    incoming_sms_id Incoming SMS ID.
    incoming_message Text received from the recipient.
    incoming_sms_timestamp ISO-8601 formatted time when the message was received.

    If you have an HLR connection set up with Beepsend this can be used to make HLR queries. You still need to identify which connection to use as HLR connection for submissions, either by setting the Connection ID or by using the "me" alias if your HLR connection is the default connection for the User token.

    You can choose to do a simple, immediate HLR lookup via GET. This is only valid for one number at a time.
    For bulk submissions you need to POST a request. The results will be returned to your callback URL.

    GET /2/hlr/<msisdn>?connection=<connection id>
    Parameter Type Description
    msisdn
    Required
    string Mobile number
    connection
    Optional
    int Specify your preferred connection to use for this operation.

    Response

    {
        "id": "08087780013866630151559112345",
        "timestamps": {
            "hlr": {
                "in": 1383225355,
                "delivered": 1383225359
            },
            "dlr_out": 1383225359
        },
        "dlr": {
            "status": "DELIVRD",
            "error": 0
        },
        "mccmnc": {
            "mcc": "402",
            "mnc": "02"
        },
        "to": {
            "address": "46736007600",
            "ton": 1,
            "npi": 1
        },
        "imsi": "423900000000000000000",
        "ported": true,
        "roaming": {
            "is_roaming": true,
            "mcc": "240",
            "mnc": "01"
        },
        "prefix": {
            "mcc": "402",
            "mnc": "02"
        }
    }
    
    Key Type Description
    id string The id of the transaction.
    timestamps.hlr.in int  When the HLR reached Beepsend.
    timestamps.hlr.delivered int When HLR response reached Beepsend.
    timestamps.dlr_out int When callback was sent.
    dlr.status string Response status.
    dlr.error int  Response code.
    mccmnc.mcc string Mobile Country Code for the handset.
    mccmnc.mnc string Mobile Network Code for the handset.
    to.address string The number you did the HLR on.
    to.ton int The numbers Type of Number.
    to.npi int The numbers Numbering Plan Identifier.
    imsi int The IMSI of the handset if available. First five characters and then zeroes.
    ported bool True if the number seems to be ported, false if not.
    roaming object Return roaming information
    roaming.is_roaming bool True if the number is roaming, false if not.
    roaming.mcc string Mobile Country Code of current phone location
    roaming.mnc string Mobile Network Code of current phone location
    prefix object Return Mcc Mnc assigned to msisdn prefix.
    prefix.mcc string Mobile Country Code assigned to msisdn prefix.
    prefix.mnc string Mobile Network Code assigned to msisdn prefix.

    The following fields can be included by request.

    Key Type Description
    price float HLR price.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/hlr/46736007518"
    curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/hlr/46736007518?connection=<connection id>"
    

    DEFINITION

    $client->hlr->intermediate({MSISDN}, {CONNECTION});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $connectionId = 1;
    $response = $client->hlr->intermediate(123456, $connectionId);
    

    You can also omit connection id and then we will use the "me" alias to reference the default connection

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.hlr().intermediate({MSISDN}, {CONNECTION}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    /* You can provide specific connection for intermediate hlr request or you can use default (me) connection */
    
    var connection = "me";
    var msisdn = "46406007500";
    
    client.hlr().intermediate(msisdn, connection).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface
        - (void)immediateHLRForNumber:(NSString *)phoneNumber onCompletion:(void(^)(BSHLR *hlr, NSArray *errors))block;
    @end
    

    CODE EXAMPLE

    [[BSConnection currentConnection] immediateHLRForNumber:@"012345678900" onCompletion:^(BSHLR *hlr, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (BSHLR object)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    
    The HLR batch endpoints requires that you have at least one HLR connection in your account. Please contact your account manager if you want to get one set up for you.

    Sometimes you might want to do an HLR lookup on more than one number at a time. For this case we have created an HLR Batch endpoint. You can do lookups on multiple addresses, on an pre-defined group or a mix of them both. You can also look at the reports afterwards, either as JSON objects or as a CSV file.

    Do one HLR lookup on multiple addresses

    You need to specify which HLR connection to use for doing lookups.

    POST /2/hlrbatch/<connection id>
    * You need to specify at least one recipient using either the parameter "to" or the parameter "groups". If you specify to, then groups are optional and vice versa.
    Parameter Type Description
    hlr.to
    Required *
    array (string) The mobile phone number starting with country code and no + sign. Also referred to sometimes as MSISDN. Supports multiple values.
    Note: Multiple numbers counts as multiple lookups and will be charged as such.
    hlr.groups
    Required *
    array (int) The id of contacts group that have to exist in our system. Supports multiple values.
    label Optional string The name of your hlr batch.

    Request body

    {
        "label": "Winter customer sendout HLR",
        "hlr": {
            "groups": [
                1,
                2
            ],
            "to": [
                "123456",
                "1234567"
            ]
        }
    }
    

    Response

    {
        "id": 24151,
        "label": "Winter customer sendout HLR",
        "date_created": 1453485600,
        "connection_id": 17755,
        "hlr": {
            "groups": [
                1,
                2
            ],
            "to": [
                "123456",
                "1234567"
            ]
        },
        "processed": 0,
        "status": 0
    }
    
    Key Type Description
    id int Unique batch id.
    label string Name of the Batch lookup.
    date_created int, Unix time Creation time of the HLR batch.
    conneciton_id int Connection id.
    hlr object HLR object with the data about the lookup (to and groups).
    processed int Number of processed numbers.
    status int 0 for pending, 1 for in progress and 2 for done.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" \
    -X POST -d '{"label": "Winter customer sendout HLR", "hlr": {"groups": [1,2],"to": ["123456","1234567"]}}' \
    "https://api.beepsend.com/2/hlrbatch/"
    

    You need a valid User API-Token to use the "groups" field in the batch request since they are connected to a User and not connections. Read more about Users and Connections. You can still use a Connection token, but you will be limited to using only the "to" field.

    Do a HLR lookup on groups or numbers.

    You can use HLR Batch Lookup to do lookups on your imported contact groups instead of using 1 or more to MSISDN addresses.

    To do a batch lookup on contact groups, just add the hlr parameter groups with the desired group ids.

    Request body

    {
        "label": "Winter customer sendout HLR",
        "hlr": {
            "groups": [
                1,
                2
            ]
        }
    }
    

    Response

    {
        "id": 24151,
        "label": "Winter customer sendout HLR",
        "date_created": 1453485600,
        "connection_id": 17755,
        "hlr": {
            "groups": [
                1,
                2
            ],
            "to": null
        },
        "processed": 0,
        "status": 0
    }
    
    Key Type Description
    id int Unique sendout id.
    label string Name of the Sendout.
    date_created int, Unix time Creation time of the HLR batch.
    conneciton_id int Connection id.
    hlr object HLR object with the data about your groups and to.
    processed int Number of processed numbers.
    status int 0 for pending, 1 for in progress and 2 for done.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" \
    -X POST -d '{"label": "Winter customer sendout HLR", "hlr": {"groups": [1,2]}}' \
    "https://api.beepsend.com/2/hlrbatch/123"
    
    This endpoint is subject to rate limits. The API is restricted to allow 90 requests in a 15 minute interval for a specific request and token.

    Listing all batches

    This call will give a paginated overview of the previously created HLR batches.

    GET /2/hlrbatch/
    GET /2/hlrbatch/?<parameter>=<value>
    Parameter Type Description
    count
    Optional
    int How many objects to fetch. Maximum 200, default 200.
    offset
    Optional
    int What offset in result set to fetch data from. Default is 0.

    Response

    [
        {
            "id": 24151,
            "label": "Winter customer sendout HLR",
            "date_created": 1453485600,
            "connection_id": 17755,
            "hlr": {
                "groups": [
                    1,
                    2
                ],
                "to": [
                    "123456",
                    "1234567"
                ]
            },
            "processed": 42,
            "status": 2
        },
        {
            "id": 24150,
            "label": "Summer customer sendout HLR",
            "date_created": 1467413400,
            "connection_id": 17755,
            "hlr": {
                "groups": [
                    1
                ],
                "to": [
                    "123456",
                    "1234567"
                ]
            },
            "processed": 12,
            "status": 2
        }
    ]
    
    Key Type Description
    id int Unique batch id.
    label string Name of the Batch lookup.
    date_created int, Unix time Creation time of the HLR batch.
    conneciton_id int Connection id.
    hlr object
    hlr.to array (string) MSISDNs to be HLRed.
    hlr.groups array (int) Contact group ids.
    processed int Number of processed numbers.
    status int 0 for pending, 1 for in progress and 2 for done.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/hlrbatch/?<parameter>=<value>"
    

    Fetch a specific batch

    To fetch a specific batch you only need to supply the unique batch ID to the URL.

    This endpoint requires a valid User API-Token. Read more about Users and Connections.

    GET /2/hlrbatch/<ID>
    Parameter Type Description
    ID
    Required
    int The unique batch id.

    Response

    {
       "id": 24151,
       "label": "Winter customer sendout HLR",
       "date_created": 1453485600,
       "connection_id": 17755,
       "hlr": {
           "groups": [
               1,
               2
           ],
           "to": [
               "123456",
               "1234567"
           ]
       },
       "processed": 42,
       "status": 2
    }
    
    Key Type Description
    id int Unique batch id.
    label string Name of the Batch lookup.
    date_created int, Unix time Creation time of the HLR batch.
    conneciton_id int Connection id.
    hlr object
    hlr.to array (string) MSISDNs to be HLRed.
    hlr.groups array (int) Contact group ids.
    processed int Number of processed numbers.
    status int 0 for pending, 1 for in progress and 2 for done.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/hlrbatch/123"
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    This call will give a paginated overview of the results in an HLR batch, complete with status, errorcode, mcc, mnc, number and contact details (if the number exists in user contacts).

    GET /2/hlrbatch/<ID>/results/
    GET /2/hlrbatch/<ID>/results/?<parameter>=<value>
    Parameter Type Description
    count
    Optional
    int How many objects to fetch. Maximum 200, default 200.
    offset
    Optional
    int What offset in result set to fetch data from. Default is 0.

    Response

    [
      {
        "dlr": {
            "status": "DELIVRD",
            "error": 0
        },
        "mccmnc": {
            "mcc": "240",
            "mnc": "07"
        },
        "to" : {
            "number": "46736007500",
            "contact" : {
                "firstname": "Foo",
                "lastname": "Bar"
            }
        }
      },
      {
        "dlr": {
            "status": "DELIVRD",
            "error": 0
        },
        "mccmnc": {
            "mcc": "240",
            "mnc": "07"
        },
        "to" : {
            "number": "46736007500",
            "contact" : {
                "firstname": "Foo",
                "lastname": "Bar"
            }
        }
      },
      {
        "dlr": {
            "status": "DELIVRD",
            "error": 0
        },
        "mccmnc": {
            "mcc": "240",
            "mnc": "07"
        },
        "to" : {
            "number": "46736007500",
            "contact" : {
                "firstname": "Foo",
                "lastname": "Bar"
            }
        }
      }
    ]
    
    Key Type Description
    dlr object
    dlr.status string Response status.
    dlr.error int Response code
    mccmnc object
    mccmnc.mcc string Mobile Country Code
    mccmnc.mnc string Mobile Network Code
    to object
    to.number string Recipient number
    to.contact object
    to.contact.firstname string First name of contact.
    to.contact.lastname string Last name of contact.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/hlrbatch/123/results/"
    

    This endpoint requires a valid User API-Token. Read more about Users and Connections.

    This call will give all results in an hlr batch formatted as CSV.

    GET /2/hlrbatch/<ID>/results.csv
    Parameter Type Description
    delimiter
    Optional
    string What delimiter to use for the csv output. (Default: , <comma>)

    Fields in the CSV file are

    Field Description
    number Recipient's number.
    firstname First name of the contact (might be empty).
    lastname Last name of the contact (might be empty).
    delivery_status Status of the HLR result.
    delivery_error Response code of the HLR result.
    mcc Mobile Country Code.
    mnc Mobile Network Code.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/hlrbatch/123/results.csv"
    

    Perform a dry run of SMS sending or HLR lookups.

    POST /2/sms/validate

    See Send SMS for request instructions.

    Response

    If validation is successful, the response will be sent like below. Since the SMS was never sent id will always be null.

    {
       "id": null,
       "to": "502040",
       "from": "Sir Lancelot",
       "errors": null
    }
    

    If validation is unsuccessful, errors would be an array instead of null.

    If any messages fail to validate, this endpoint will return the status code 403.

    {
        "id": null,
        "to": "5020assd40",
        "from": "Beepsend",
        "errors": [
            {
                "code": 1031,
                "description": "\"to\" must be a numeric value"
            }
        ]
    }
    

    If you want to validate multiple messages you need to use our batch endpoint

    POST /2/batch/validate

    Response

    If validation is successful, the response will be sent like below. Since the SMS was never sent id will always be null.

    {
       "id": null,
       "batch_label": "My custom name for my batch",
       "to": "502040",
       "from": "lolboll",
       "errors": null
    }
    

    If validation is unsuccessful, errors would be an array instead of null.

    If any messages fail to validate, this endpoint will return the status code 403.

    {
        "id": null,
        "batch_label": "My custom name for my batch",
        "to": "5020assd40",
        "from": "Beepsend",
        "errors": [
            {
                "code": 1031,
                "description": "\"to\" must be a numeric value"
            }
        ]
    }
    
    POST /2/hlr/validate

    See instructions for HLR.

    Response

    If validation is successful, the response will be sent like below. Since the HLR lookup was never sent id will always be null.

    {
        "id": null,
        "msisdn": "46736007518",
        "errors": null
    }
    

    If validation is unsuccesful, errors would be an array instead of null.

    If any lookups fail to validate, this endpoint will return the status code 403.

    {
        "id": null,
        "msisdn": "5020assd40",
        "errors": [
            {
                "code": 1031,
                "description": "\"msisdn\" must be a numeric value"
            }
        ]
    }
    

    CURL EXAMPLE FOR VALIDATING SMS

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" \
    -X POST -d '{"batch_label": "My custom name for batch", "to": "46736007518", "message": "Hello World! 你好世界", "from": "Beepsend", "send_time": 1383225355, "encoding": "UTF-8", "receive_dlr": false}' \
    "https://api.beepsend.com/2/sms/validate"
    

    CODE EXAMPLE FOR VALIDATING HLR

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" \
    -X POST -d '{"msisdn": "46736007518"}' \
    "https://api.beepsend.com/2/hlr/validate/"
    

    DEFINITION

    $client->message->validate(
        {TO}, 
        {FROM}, 
        {MESSAGE}, 
        {CONNECTION}, 
        {ENCODING}, 
        {OPTIONS}
    );
    $client->hlr->validate({MSISDN});
    

    CODE EXAMPLE FOR VALIDATING SMS

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $options = array(
        'batch_label' => 'My custom name for my batch',
    );
    
    $connectionId = 1;
    $message = $client->message->validate(
        46736007518, 
        'TonyMontana', 
        'Hello World! 你好世界!', 
        'UTF-8', 
        $options
    );
    

    You can also set null for connection id and the "me" alias will be used to reference your default SMS connection

    CODE EXAMPLE FOR VALIDATING HLR

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $connectionId = 1;
    $response = $client->hlr->validate(46736007518);
    

    You can also set null for connection id and the "me" alias will be used to reference your default HLR connection

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.messages().validate({FROM}, {TO}, {MESSAGE}, {ENCODING}, {OPTIONS}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    
    client.hlr().validate({MSISDN}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    /* SMS validation example */
    
    var from = "Beepsend";
    var to = "46736007518";
    var message = "Hello World!";
    var encoding = "UTF-8";
    
    /* Aditional options */
    var options = {
        "batch_label": "My custom name for my batch",
        "receive_dlr": false
    };
    
    client.messages().validate(from, to, message, encoding, options).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    
    
    /* HLR validation example */
    
    var msisdn = "46406007500";
    
    client.hlr().validate(msisdn).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSMessage

    - (void)validateMessageOnCompletion:(void(^)(BSMessage *message, NSArray *errors))block;
    

    @end

    @interface BSHLR

    - (void)validateHLRForNumberOnCompletion:(void(^)(BSHLR *hlr, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    SMS validation

    BSMessage *sms = [BSMessage messageWithBody:@"Message body" from:@"Sender name or number" to:@"012345678900"];
    
    [sms validateMessageOnCompletion:^(BSMessage *message, NSArray *errors) {
        if (!errors || errors.count == 0) {
            //Handle response (BSMessage object)
        }
        else {
            //Handle error (array of BSError objects)
        }
    }];
    

    HLR validation

    BSHLR *hlr = [[BSHLR alloc] initHLRWithNumber:@"01234567890"];
    
    [hlr validateHLRForNumberOnCompletion:^(BSHLR *hlr, NSArray *errors) {
        if (!errors || errors.count == 0) {
            //Handle response (BSHLR object)
        }
        else {
            //Handle error (array of BSError objects)
        }
    }];
    

    Callbacks

    Callbacks is our way of giving you back results for operations that typically are asynchronous or take a longer time. One common use-case for callbacks is to get delivery receipts of SMS. The Callback is a webpage located on a public URL which will listen for incoming requests with a JSON payload. Without a proper callback handling you will not be able to get delivery confirmations. This chapter describes in more detail how to configure your callback for delivery receipts, incoming SMS (MO) and HLR results.

    Setup callback url for delivery reports.

    Delivery Reports (DR)

    When a text message is received by the Beepsend SMS Gateway, you will receive a delivery report (also called DR, DN or DLR) once we have attempted delivery. The DR is sent to your specified callback URL by HTTP PUT, POST or GET. This message passing procedure is called callback and gives you statistics for if and when a message was delivered. If you don't want delivery notifications you should leave the callback URL-field empty. The first thing to do is specifying the callback URL for your connection on the admin page.

    Examples

    POST http://youraddress.com/
    PUT http://youraddress.com/<sms id>
    GET http://youraddress.com/?id=<sms id> {...}

    Please visit the Beepsend Customer Portal to set up your callback URL and method.

    The delivery-notification you will receive after each sent message contains five parameters:

    Key Type  Description
    id string Message Id.
    batch array | null Object with id and label or null.
    timestamps.sms.in int  When the SMS reached Beepsend.
    timestamps.sms.delivered int When DLR reached Beepsend.
    timestamps.dlr_out int When DLR callback was sent.
    dlr.status string Response status.
    dlr.error int  Response code.
    to.address string Destination address
    to.ton int Destination Type of Number.
    to.npi int Destination Numbering Plan Identifier.

    Request body

    Via GET these parameters will be appended to the URL in a querystring. If using POST or PUT they will be sent as a JSON request shown below.

    {
        "id": "128452",
        "batch": null,
        "timestamps": {
            "sms": {
                "in": 1383225355,
                "delivered": 1383225359
            },
            "dlr_out": 1383225359
        },
        "dlr": {
            "status": "DELIVRD",
            "error": 0
        },
        "to": {
            "address": "46736007600",
            "ton": 1,
            "npi": 1
        }
    }
    

    Delivery notification can also contain optional information per customer request:

    Key Type  Description
    mccmnc.mcc string MCC, Destination country code.
    mccmnc.mnc string MNC, Destination operator code.
    imsi int The IMSI of the handset if available. First five characters and then zeroes.
    price float Message price.

    Callback response

    After you have received the DLR, your webserver should send http response 200 OK

    This tells us that you have received the DLR and we can flag the transaction complete.

    Mobile Originated SMS is sent by end user phone to registered shortcode or longcode.

    You need to have a 2-way Number to be able to recieve a mobile originated SMS.

    The mobile operator will forward the message to the Beepsend SMS platform. Beepsend's SMS gateway will then send it to your specified callback URL by HTTP POST, PUT or GET.

    Examples

    POST http://youraddress.com/
    PUT http://youraddress.com/
    GET http://youraddress.com/?from=<Sender MSISDN> {...}

    Please visit the Beepsend Customer Portal to set up your callback URL and method.

    The Beepsend SMS Gateway will initialise an HTTP request to your URL with the following parameters.

    Key Type  Description
    id string Message Id.
    timestamps.sms.in int When MO sms reached Beepsend.
    from string Sender MSISDN.
    to string Destination short or longcode.
    message string MO SMS body. Plain text URL encoded.
    hex_body string Hex encoded string containing the raw body of MO sms (or MO sms part if it's multipart message).
    encoding string Message encoding. ‘Windows-1252’ if possible. If message contain non latin characters then ‘Unicode’ (UTF-16 BE).

    Request body

    Via GET these parameters will be appended to the URL in a querystring. If using POST or PUT they will be sent as a JSON request shown below.

    {
        "id":"07595980013893439611559146736007518",
        "timestamps": {
            "sms": {
                "in": 1383225355
            }
        },
        "from": "46406007500",
        "to": "461111111",
        "message": "Hello World!",
        "hex_body": "48656c6c6f20576f726c6421",
        "encoding": "Windows-1252"
    }
    

    MO sms can also contain optional information per customer request:

    Key Type  Description
    mccmnc.mcc string MCC, Destination country code.
    mccmnc.mnc string MNC, Destination operator code.
    imsi int The IMSI of the handset if available. First five characters and then zeroes.
    price float Message price.

    MO callback response

    After you have received the MO SMS, your webserver should send http response 200 OK

    This tells us that you have received the MO SMS and we can flag the transaction complete.

    Once all the HLR requests has been made our system will send the results to the DLR URL defined as callback for the specified HLR connection. Callbacks are made for each submitted number and returned as they are completed. The result payload is:

    Request body

    {
        "id": "08087780013866630151559112345",
        "timestamps": {
            "hlr": {
                "in": 1383225355,
                "delivered": 1383225359
            },
            "dlr_out": 1383225359
        },
        "dlr": {
            "status": "DELIVRD",
            "error": 0
        },
        "mccmnc": {
            "mcc": "402",
            "mnc": "02"
        },
        "to": {
            "address": "46736007500",
            "ton": 1,
            "npi": 1
        },
        "imsi": "423900000000000000000",
        "ported": true,
        "roaming": {
            "is_roaming": true,
            "mcc": "240",
            "mnc": "01"
        },
        "prefix": {
            "mcc": "402",
            "mnc": "02"
        }
    }    
    
    Key Type Description
    id string The id of the transaction.
    timestamps.hlr.in int  When the HLR reached Beepsend.
    timestamps.hlr.delivered int When HLR response reached Beepsend.
    timestamps.dlr_out int When callback was sent.
    dlr.status string Response status.
    dlr.error int  Response code.
    mccmnc.mcc string Mobile Country Code for the handset.
    mccmnc.mnc string Mobile Network Code for the handset.
    to.address string The number you did the HLR on.
    to.ton int The numbers Type of Number.
    to.npi int The numbers Numbering Plan Identifier.
    imsi int The IMSI of the handset if available. First five characters and then zeroes.
    ported bool True if the number seems to be ported, false if not.
    roaming object Return roaming information
    roaming.is_roaming bool True if the number is roaming, false if not.
    roaming.mcc string Mobile Country Code of current phone location
    roaming.mnc string Mobile Network Code of current phone location
    prefix object Return Mcc Mnc assigned to msisdn prefix.
    prefix.mcc string Mobile Country Code assigned to msisdn prefix.
    prefix.mnc string Mobile Network Code assigned to msisdn prefix.

    The following fields can be included by request.

    Key Type Description
    price float HLR price.

    Callback response

    After you have received the DLR, your webserver should send http response 200 OK

    This tells us that you have received the DLR and we can flag the transaction complete.

    Accumulated Statistics

    This call will give you accumulated statistics for all messages sent between two specified dates and the accumulated cost for these in Euro (€). The call counts all messages submitted via SMPP and HTTP alike.

    The call supports a summary for available connections based on a User Token, a specific connection or using the short hand alias "me" for the authenticated connection, will return you statistics for user default connection.

    This call does not consider delivery statistics and should merely be used for aggregated views on traffic. If no ID is provided the return data set is a list of connections.

    GET /2/analytics/summary/<ID>
    GET /2/analytics/summary/me
    GET /2/analytics/summary/
    Parameter Type Description
    from_date
    Optional
    int Begin Date in Unix time.
    to_date
    Optional
    int End dates in Unix time.

    Response

    {
        "connection": "customer-1",
        "count": 100,
        "price": 4.38
    }
    
    Key Type Description
    connection string The connection label
    count int Number of messages during the time interval.
    price float Total cost for traffic between given interval in Euro (€).

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X GET \
    "https://api.beepsend.com/2/analytics/summary/"
    

    DEFINITION

    $client->analytic->summary({CONNECTION}, {FROM_DATE}, {TO_DATE});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $connectionId = 1;
    $fromDate = 1388534400;
    $toDate = 1619984000;
    
    $summary = $client->analytic->summary($connectionId, $fromDate, $toDate);
    

    You can also omit connection id and then we will use the "me" alias to reference the default connection

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.analytic().summary({CONNECTION}, {FROM_DATE}, {TO_DATE}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    client.analytic().summary().then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSUser
    
        - (void)getNetworkDetailsFromDate:(NSDate *)startDate
                                                             toDate:(NSDate *)endDate
                                                             mccmnc:(BSMCCMNC *)mccmnc
                                    withCompletionBlock:(void(^)(NSArray *networkDetails, NSArray *errors))block;
    
    @end
    
    @interface BSConnection
    
        - (void)getNetworkDetailsFromDate:(NSDate *)startDate
                                                             toDate:(NSDate *)endDate
                                                             mccmnc:(BSMCCMNC *)mccmnc
                                    withCompletionBlock:(void(^)(NSArray *networkDetails, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    //Use current user to check analytics summary
    [[BSUser currentUser] getAnalyticsSummaryFromDate:[NSDate date] toDate:[NSDate date] withCompletionBlock:^(NSArray *statistics, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (array of BSAccumulatedStatistics objects)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    
    //You can use default connection or any other connection for analytics summary
    [[BSConnection currentConnection] getAnalyticsSummaryFromDate:[NSDate date] toDate:[NSDate date] withCompletionBlock:^(NSArray *statistics, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (array of BSAccumulatedStatistics objects)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This call will give you granular delivery statistics for all messages sorted by each recipient network between two specified dates. The call counts all messages submitted via SMPP and HTTP alike.

    The call supports parameter to specify a list of MCC and/or MNC. If these parameters are omitted all MCC and MNC that has traffic will be returned.

    The call supports a summary for available connections on used token. Either a specific Connection ID or using the short hand alias "me" for the authenticated connection if Connection token was used when authenticating or the default connection if User token was used instead. If no ID is provided all connections available is returned as list.

    GET /2/analytics/network/<ID>
    GET /2/analytics/network/me
    GET /2/analytics/network/
    Parameter Type  Description
    from_date
    Optional
    int Begin Date in Unix time.
    to_date
    Optional
    int End dates in Unix time.
    MCC
    Optional
    string Mobile Country Code
    MNC
    Optional
    string Mobile Network Code

    Response

    [
        {
            "mccmnc": {
                "mcc": "648",
                "mnc": "03"
            },
            "statistics": {
                "delivered": 100,
                "mo": 0,
                "expired": 12,
                "unknown": 20,
                "rejected": 0,
                "undelivered": 10,
                "no_dlr": 0
            },
            "total": 142
        }
    ]
    
    Key Type Description
    mccmnc.mnc string Mobile Country Code
    mccmnc.mcc string Mobile Network Code
    statistics.delivered int Amount of messages with status delivered to handset
    statistics.mo int Incoming messages from Operator
    statistics.expired int Amount of messages that suffered time out
    statistics.unknown int Failed messages without a clear error
    statistics.rejected int Messages not accepted by Operator
    statistics.undelivered int Failed messages. Unlike unknown, an error code was returned
    statistics.no_dlr int Messages still in the process of sending
    total int Total amount of messages for the MCC MNC

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X GET \
    "https://api.beepsend.com/2/analytics/network/"
    

    DEFINITION

    $client->analytic->network({CONNECTION}, {FROM_DATE}, {TO_DATE}, {MCC}, {MNC});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $connectionId = 1;
    $fromDate = 1388534400;
    $toDate = 1619984000;
    
    $summary = $client->analytic->network($connectionId, $fromDate, $toDate);
    

    You can also omit connection id and then we will use the "me" alias to reference the default connection

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.analytic().network({CONNECTION}, {FROM_DATE}, {TO_DATE}, {MCC}, {MNC}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    client.analytic().network().then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSUser
    
        - (void)getNetworkDetailsFromDate:(NSDate *)startDate
                                                             toDate:(NSDate *)endDate
                                                             mccmnc:(BSMCCMNC *)mccmnc
                                    withCompletionBlock:(void(^)(NSArray *networkDetails, NSArray *errors))block;
    
    @end
    
    @interface BSConnection
    
        - (void)getNetworkDetailsFromDate:(NSDate *)startDate
                                                             toDate:(NSDate *)endDate
                                                             mccmnc:(BSMCCMNC *)mccmnc
                                    withCompletionBlock:(void(^)(NSArray *networkDetails, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    //Use current user to check network analytics
    [[BSUser currentUser] getNetworkDetailsFromDate:[NSDate date] toDate:[NSDate date] mccmnc:nil withCompletionBlock:^(NSArray *networkDetails, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (array of BSNetworkDetails objects)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    
    //You can use default connection or any other connection for network analytics
    [[BSConnection currentConnection] getNetworkDetailsFromDate:[NSDate date] toDate:[NSDate date] mccmnc:nil withCompletionBlock:^(NSArray *networkDetails, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (array of BSNetworkDetails objects)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This call will give you delivery statistics for a whole sendout.

    GET /2/analytics/sendouts/
    GET /2/analytics/sendouts/<ID>
    GET /2/analytics/sendouts/?<parameter>=<value>
    Parameter Type Description
    count
    Optional
    int How many objects to fetch. Maximum 200, default 200.
    offset
    Optional
    int What row offset in result set to fetch data from.

    Response

    [
        {
            "id": 23,
            "name": "My sendout",
            "total": 142,
            "statistics": {
                "delivered": 100,
                "expired": 12,
                "unknown": 20,
                "rejected": 0,
                "undelivered": 10,
                "no_dlr": 0
            },
            "total_responses": 10,
            "responses": [
                {
                    "text": "yes",
                    "count": 7
                },
                {
                    "text": "no",
                    "count": 3
                }
            ]
        }
    ]
    
    Key Type Description
    id int Unique sendout id
    name string sendout name
    total int Total amount of messages in the sendout
    statistics.delivered int Amount of messages with status delivered to handset
    statistics.expired int Amount of messages that suffered time out
    statistics.unknown int Failed messages without a clear error
    statistics.rejected int Messages not accepted by Operator
    statistics.undelivered int Failed messages. Unlike unknown, an error code was returned
    statistics.no_dlr int Messages still in the process of sending
    responses_total int Number of responses.
    responses array
    responses.text string The content of the response.
    responses.count int The amount of responses with this text.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X GET \
    "https://api.beepsend.com/2/analytics/sendouts/"
    

    DEFINITION

    $client->analytic->batch({BATCH_ID});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $connectionId = 1;
    $fromDate = 1388534400;
    $toDate = 1619984000;
    
    $analytics = $client->analytic->batch();
    
    /* For getting analytics for specific batch set batch id */
    $batchId = 23;
    $analytics = $client->analytic->batch($batchId);
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.analytic().batch({BATCH_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var batchId = 23;
    
    client.analytic().batch(batchId).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSBatch
    
        - (void)getDeliveryStatisticsWithCompletionBlock:(void(^)(NSArray *statistics, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    BSBatch *batch = [[BSBatch alloc] initWithID:@"1234" andLabel:@"batch"];
    
    [batch getDeliveryStatisticsWithCompletionBlock:^(NSArray *statistics, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (array of BSStatistics objects)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This call will give you delivery statistics for a HLR batch.

    GET /2/analytics/hlrbatch/
    GET /2/analytics/hlrbatch/<ID>
    GET /2/analytics/hlrbatch/?<parameter>=<value>
    Parameter Type Description
    count
    Optional
    int How many objects to fetch. Maximum 200, default 200.
    offset
    Optional
    int What row offset in result set to fetch data from.

    Response

    [
        {
            "id": 23,
            "name": "My hlr batch",
            "total": 142,
            "statistics": {
                "delivered": 100,
                "expired": 12,
                "unknown": 20,
                "rejected": 0,
                "undelivered": 10,
                "no_dlr": 0
            }
        }
    ]
    
    Key Type Description
    id int Unique batch id
    name string HLR batch name
    total int Total amount of HLRs in the sendout
    statistics object
    statistics.delivered int Amount of HLRs with status delivered to handset
    statistics.expired int Amount of HLRs that suffered time out
    statistics.unknown int Failed HLRs without a clear error
    statistics.rejected int HLRs not accepted by Operator
    statistics.undelivered int Failed HLRs. Unlike unknown, an error code was returned
    statistics.no_dlr int HLRs still in the process of sending

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X GET \
    "https://api.beepsend.com/2/analytics/hlrbatch/"
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    List your user conversations.

    GET /2/conversations/
    GET /2/conversations/?<parameter>=<value>
    Parameter Type Description
    count
    Optional
    int How many objects to fetch. Maximum 200, default 200.
    offset
    Optional
    int What row offset in result set to fetch data from.

    Response

    [
        {
            "id": "46736007500-46736000005",
            "to": "46736007500",
            "from": {
                "number": "46736000005",
                "contact": {
                    "id": 10,
                    "firstname": "Foo",
                    "lastname": "Bar"
                }
            },
            "body": "Hi. This is a test message.",
            "timestamp": 1383225355
        }
    ]
    
    Key Type Description
    id string Unique ID for this conversation. Based on to and from values.
    to string Your system phone number.
    from object
    from.number string The receiving number.
    from.contact object
    from.contact.id int | null Id of the matching contact, if any.
    from.contact.firstname string | null Firstname of contact.
    from.contact.lastname string | null Lastname of contact.
    body string Last received body from the
    timestamp int Unixtime of the last received message.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" \
    -X GET "https://api.beepsend.com/2/conversations/"
    

    DEFINITION

    $client->message->conversations();
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $conversations = $client->message->conversations();
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.messages().conversations().then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    client.messages().conversations().then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSUser
    
        - (void)getConversationsOnCompletion:(void(^)(NSArray *conversations, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    [[BSUser currentUser] getConversationsOnCompletion:^(NSArray *conversations, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (array of BSConversation objects)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    List all messages sent back and forth in to a single contact/number.

    GET /2/conversations/<id>

    The items list is paginated and this endpoint accepts the same parameters as sms lookup.

    {
        "id": "46736007500-46736000005",
        "to": "46736007500",
        "from": {
            "number": "46736000005",
            "contact": {
                "id": 10,
                "firstname": "Foo",
                "lastname": "Bar"
            }
        },
        "body": "Hi. This is a test message.",
        "timestamp": 1383225355,
        "items": [
            {
                "id": "12345",
                "batch": null,
                "body": "Hello World!",
                "connection": {
                    "id": 7,
                    "label": "superman-connection"
                },
                "to": {
                    "address": "46406007500",
                    "ton": 1,
                    "npi": 1
                },
                "from": {
                    "address": "Beepsend",
                    "ton": 1,
                    "npi": 1
                },
                "validity_period": "131102072704000-",
                "data_coding": 3,
                "timestamps": {
                    "sms": {
                        "in": 1383225355,
                        "delivered": null
                    },
                    "dlr_out": null
                },
                "dlr": {
                    "status": null,
                    "error": null
                },
                "price": 0.068,
                "mccmnc": {
                    "mcc": "240",
                    "mnc": "01"
                }
            }
        ]
    }
    
    Key Type Description
    id string Unique ID for this conversation. Based on to and from values.
    to string Your system phone number.
    from object
    from.number string The receiving number.
    from.contact object
    from.contact.id int | null Id of the matching contact, if any.
    from.contact.firstname string | null Firstname of contact.
    from.contact.lastname string | null Lastname of contact.
    body string Last received body from the
    items array A list of sms objects

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" \
    -X GET "https://api.beepsend.com/2/conversations/1"
    

    DEFINITION

    $client->message->fullConversation({CONVERSATION_ID}, {OPTIONS});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $conversationId = 123;
    $conversations = $client->message->conversations($conversationId);
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.messages().conversation({CONVERSATION_ID}, {OPTIONS}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var conversationId = 1;
    
    client.messages().conversation(conversationId).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSConnection
    
        - (void)getDetailsForConversation:(BSConversation *)conversation onCompletion:(void(^)(BSConversation *fullConversation, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    [[BSUser currentUser] getDetailsForConversation:conversation onCompletion:^(BSConversation *fullConversation, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (BSConversation object that contains array of BSSMSLookup objects)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    Get all contacts belonging to your user. Specify a group id or name to filter your results. To get a specific contact by number, use /msisdn/. When fetching all contacts the endpoint is paginated, add parameters to the query string to browse contacts.

    GET /2/contacts/<id>
    GET /2/contacts/?<parameter>=<value>
    GET /2/contacts/msisdn/<msisdn>
    Parameter Type Description
    group
    Optional
    int | string Group id or name.
    since_id
    Optional
    int Returns results more recent than the specified id.
    max_id
    Optional
    int Returns results with an id older than or equal to the specified id.
    count
    Optional
    int How many objects to fetch. Maximum 200, default 200.
    offset
    Optional
    int What row offset in result set to fetch data from (as an alternative to max_id).
    sort
    Optional
    string Sorting of the dataset. Available keys: name, id. Can be prepended with + or - to change the sorting direction (+ ASC, - DESC).
    include_global
    Optional
    boolean Include contacts that belong to global groups. Global groups are shared between users under the same customer. false by default.

    Response

    [
        {
            "id": 22594418,
            "msisdn": "46736007518",
            "name": "Phone",
            "groups": []
        },
        {
            "id": 22594420,
            "msisdn": "46406007500",
            "name": "Beepsend",
            "groups": [
                {
                    "id": 213,
                    "name": "Beepnumbers"
                }
            ]
        }
    ]
    
    Key Type Description
    id id The id of the group.
    msisdn string Mobile number.
    name string Contact name.
    groups array  List of linked groups.
    groups.x.id int id of a group this contact is linked to.
    groups.x.name string Name of a group this contact is linked to.

    CURL EXAMPLE

    Get all contacts

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" \
    -X GET "https://api.beepsend.com/2/contacts/"
    

    Get contacts from a certain group

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" \
    -X GET "https://api.beepsend.com/2/contacts/?group=2"
    

    DEFINITION

    $client->contact->all({GROUP_ID}, {OPTIONS});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $contacts = $client->contact->all();
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.contacts().all({GROUP_ID}, {SORT}, {SINCE_ID}, {MAX_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    client.contacts().all().then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSUser
    
        - (void)getAllContactsfromGroup:(BSGroup *)group sorted:(NSString *)sort forNextPage:(BOOL)nextPage onCompletion:(void(^)(NSArray *contacts, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    [[BSUser currentUser] getAllContactsfromGroup:nil sorted:@"+" forNextPage:NO onCompletion:^(NSArray *contacts, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (array of BSContact objects)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    POST /2/contacts/
    Parameter Type Description
    msisdn
    Required
    string Mobile number.
    firstname
    Optional
    string Contacts first name.
    lastname
    Optional
    string Contacts last name.
    groups
    Optional
    array List of group objects.
    groups.x.id
    Optional
    int Group id this contact should be linked to.

    Request Body

    {
        "msisdn": "1234567",
        "firstname": "Example contact"
    }
    

    Response

    {
        "id": 22594443,
        "msisdn": "1234567",
        "firstname": "Example contact",
        "lastname": "",
        "groups": [],
        "errors": null
    }
    

    Status code: 201 created.

    Multiple contacts

    Multiple contacts can be added at once.

    Request body

    [
        {
            "msisdn": "12345",
            "firstname": "Multi-example"
        },
        {
            "msisdn": "34525",
            "groups": [
                {
                    "id": 1
                },
                {
                    "id": 14
                }
            ]
        }
    ]
    

    Response

    [
        {
            "id": 22594444,
            "msisdn": "12345",
            "firstname": "Multi-example",
            "lastname": "",
            "groups": [],
            "errors": null
        },
        {
            "id": null,
            "msisdn": "34525",
            "firstname": "",
            "lastname": "",
            "groups": [
                {
                    "id": 1,
                    "name": "Customers"
                }
                {
                    "id": 14,
                    "name": "The lorem ipsum group"
                }
            ],
            "errors": null
        }
    ]
    
    Status code Case
    201 All contacts created successfully.
    200 Some contacts created, check errors.
    403 All contacts failed to be added.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" -H "Content-Type: application/json" \
    -X POST -d '{"msisdn" : "46736007518", "firstname" : "Christian", "lastname" : "Nilsson"}' \
    "https://api.beepsend.com/2/contacts/"
    

    DEFINITION

    $client->contact->add({MSISDN}, {FIRST_NAME}, {LAST_NAME}, {GROUP_IDS});
    
    Note: Groups are optional and always an array of ids when used.
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $contact = $client->contact->add('46736007502', 'Jane', 'Doe', array(137, 235));
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.contacts().add({MSISDN}, {FIRSTNAME}, {LASTNAME}, {GROUPS}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var msisdn = 1234567;
    var firstName = "Example"; //Or you can pass null to method
    var lastName = "Contact"; //Or you can pass null to method
    var groups = ["1", "2"];
    
    client.contacts().add(msisdn, firstName, lastName, groups).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSContact
    
        @property (nonatomic, strong) NSString *firstName;
        @property (nonatomic, strong) NSString *lastName;
        @property (nonatomic, strong) NSString *phoneNumber;
    
        - (void)saveContactOnCompletion:(void(^)(BSContact *contact, NSArray *errors))block;
    
    @end
    
    @interface BSUser
    
        - (void)addMultipleContacts:(NSArray *)contacts onCompletion:(void(^)(NSArray *response, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    //create single contact and save it
    BSContact *contact = [[BSContact alloc] initContactWithPhoneNumber:@"123456789000" firstName:@"First" lastName:@"Last" group:nil];
    
    [contact saveContactOnCompletion:^(BSContact *contact, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            if (contact.errors && contact.errors.count > 0) {
    
                //Handle errors (array of BSError objects)
    
            }
            else {
    
                //Contact successfully added
    
            }
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    
    //For adding multiple contacts create contacts and use user method for adding multiple contacts
    BSContact *c1 = [[BSContact alloc] initContactWithPhoneNumber:@"123456789001" firstName:@"First1" lastName:@"Last1" group:nil];
    BSContact *c2 = [[BSContact alloc] initContactWithPhoneNumber:@"123456789002" firstName:@"First2" lastName:@"Last2" group:nil];
    BSContact *c3 = [[BSContact alloc] initContactWithPhoneNumber:@"123456789003" firstName:@"First3" lastName:@"Last3" group:nil];
    
    [[BSUser currentUser] addMultipleContacts:@[c1, c2, c3] onCompletion:^(NSArray *response, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            for (BSContact *contact in response) {
    
                if (contact.errors && contact.errors.count > 0) {
    
                    //Handle errors (array of BSError objects)
    
                }
                else {
    
                    //Contact successfully added
    
                }
            }
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    PUT /2/contacts/<id>
    Parameter Type Description
    msisdn
    Optional
    string Mobile number.
    firstname
    Optional
    string Contacts first name.
    lastname
    Optional
    string Contacts last name.
    groups
    Optional
    array A list of objects containing group ids that should be linked to contact. Can be used to move a contact between groups. NOTE If empty or not specified all contact links will be cleared.
    groups.x.id
    Optional
    int Group id this contact should be linked against.

    This endpoint supports partial updates. Any omitted field in a model will read in the current value.

    Request Body

    {
        "msisdn": "3456789",
        "firstname": "Still an example"
    }
    

    Response

    {
        "id": 22594443,
        "msisdn": "3456789",
        "firstname": "Still an example",
        "lastname": "",
        "groups": [],
        "errors": null
    }
    

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X PUT \
    -d '{"msisdn" : "46736007518", "firstname" : "Christian", "lastname" : "Nilsson"}' \
    "https://api.beepsend.com/2/contacts/1"
    

    DEFINITION

    $client->contact->update({CONTACT_ID}, {OPTIONS});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $contactId = 123;
    $options = array(
        'msisdn' => 46736007518,
        'firstname' => 'Mary'
    );
    
    $contact = $client->contact->update($contactId, $options);
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.contacts().update({CONTACT_ID}, {OPTIONS}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var contactId = 22594443;
    var options = {
        "msisdn": "3456789",
        "firstname": "Still an example"
    };
    
    client.contacts().update(contactId, options).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSContact
    
        - (void)updateContactOnCompletion:(void(^)(BSContact *contact, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    BSContact *contact = existingContactToEdit;
    
    contact.firstName = @"NewFirstName";
    contact.lastName = @"NewLastName";
    contact.phoneNumber = @"012345678900";
    
    [contact updateContactOnCompletion:^(BSContact *contact, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Contact successfully updated
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    DELETE /2/contacts/<id>
    

    This will remove the contact and its link from every group it belonged to. To unlink a contact from a specific group, use Update with only the groups you want or an empty list to remove all links.

    Response

    204 no content header.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" \
    -X DELETE "https://api.beepsend.com/2/contacts/1"
    

    DEFINITION

    $client->contact->delete({CONTACT_ID});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $contactId = 123;
    $contact = $client->contact->delete($contactId);
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.contacts().delete({CONTACT_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var contactId = 22594443;
    
    client.contacts().delete(contactId).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSContact
    
        - (void)removeContactOnCompletion:(void(^)(BOOL success, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    BSContact *contact = existingContactToDelete;
    
    [contact removeContactOnCompletion:^(BOOL success, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Contact successfully deleted
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    Get all contact groups belonging to your user. Specify a group id to filter your results. When fetching all groups the endpoint is paginated, add parameters to the query string to browse groups.

    GET /2/contacts/groups/<id>
    GET /2/contacts/groups/?<parameter>=<value>
    Parameter Type Description
    since_id
    Optional
    int Returns results more recent than the specified id.
    max_id
    Optional
    int Returns results with an id older than or equal to the specified id.
    count
    Optional
    int How many objects to fetch. Maximum 200, default 200.
    include_global
    Optional
    boolean Include global groups that are shared between users under the same customer. false by default.

    Response

    [
        {
            "id": 1,
            "name": "Customers",
            "contacts_count": 27,
            "processing": 1,
            "owner": {
                "id": 15000,
                "name": "Beepsend-user"
            },
            "global": 0
        },
        {
            "id": 2,
            "name": "Others",
            "contacts_count": 2,
            "processing": 0,
            "owner": {
                "id": 15000,
                "name": "Beepsend-user"
            },
            "global": 1
        }
    ]
    
    Key Type Description
    id id The id of the group.
    name string Contact group name.
    contacts_count int Number of contacts in the group.
    processing int | null This flag is 1 if contacts are being imported, otherwise 0.
    owner string User that owns the group.
    global int, 0/1 1 means that the group is shared between all users under the same customer.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" \
    -X GET "https://api.beepsend.com/2/contacts/groups/"
    

    DEFINITION

    $client->contact->groups({SINCE_ID}, {MAX_ID}, {COUNT});
    $client->contact->group({GROUP_ID}, {GROUP_NAME});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $groups = $client->contact->groups();
    
    /* Get single group */
    $groupId = 123;
    $group = $client->contact->group($groupId);
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.contacts().groups().then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    
    client.contacts().group({GROUP_ID}, {SINCE_ID}, {MAX_ID}, {COUNT}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    /* Get all contact groups belonging to your user */
    
    client.contacts().groups().then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    
    /* Get content of specific group */
    
    var groupId = 1;
    
    client.contacts().group(groupId).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSUser
    
        - (void)getAllGroupsForNextPage:(BOOL)nextPage onCompletion:(void(^)(NSArray *groups, NSArray *errors))block;
        - (void)getGroupDetails:(NSString *)groupID onCompletion:(void(^)(BSGroup *group, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    // Get all groups
    [[BSUser currentUser] getAllGroupsForNextPage:NO onCompletion:^(NSArray *groups, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (array of BSGroup objects)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    
    // Get details for specific group
    [[BSUser currentUser] getGroupDetails:@"1234" onCompletion:^(BSGroup *group, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (BSGroup object)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    POST /2/contacts/groups/
    Parameter Type Description
    name
    Required
    string Group name.
    global
    Optional
    int 1 makes this group shared between users under the same customer. This can only be changed later by the group owner.

    Request Body

    {
        "name": "Important people"
    }
    

    Response

    {
        "id": 2,
        "name": "Important people",
        "contacts_count": 0,
        "processing": 0,
        "owner": {
            "id": 15000,
            "name": "Beepsend-user"
        },
        "global": 0
    }
    

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" \
    -X POST -d '{"name" : "Important people"}' \
    "https://api.beepsend.com/2/contacts/groups/"
    

    DEFINITION

    $client->contact->addGroup({GROUP_NAME});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $group = $client->contact->addGroup('Important people');
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.contacts().addGroup({NAME}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var groupName = "Important people";
    
    client.contacts().addGroup(groupName).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSGroup
    
        - (void)saveGroupOnCompletion:(void(^)(BSGroup *group, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    BSGroup *group = [[BSGroup alloc] initGroupWithName:@"Group name"];
    
    [group saveGroupOnCompletion:^(BSGroup *group, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (BSGroup object)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    PUT /2/contacts/groups/<id>
    Parameter Type Description
    name
    Required
    string Group name.
    global
    Optional
    int 1 makes this group shared between users under the same customer. This can only be changed by the group owner.

    This endpoint supports partial updates. Any omitted field in a model will read in the current value.

    Request Body

    {
        "name": "Still very important people",
        "global": 1
    }
    

    Response

    {
        "id": 2,
        "name": "Still very important people",
        "contacts_count": 0,
        "processing": 0,
        "owner": {
            "id": 15000,
            "name": "Beepsend-user"
        },
        "global": 1
    }
    

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" \
    -X PUT -d '{"name" : "New name of group"}' \
    "https://api.beepsend.com/2/contacts/groups/1"
    

    DEFINITION

    $client->contact->updateGroup({GROUP_ID}, {GROUP_NAME});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $groupId = 123;
    $group = $client->contact->updateGroup($groupId, 'Still very important people');
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.contacts().updateGroup({GROUP_ID}, {NAME}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var groupId = 1;    
    var groupName = "Important people";
    
    client.contacts().updateGroup(groupId, groupName).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSGroup
    
        - (void)updateGroupOnCompletion:(void(^)(BSGroup *group, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    BSGroup *group = existingGroupToEdit;
    
    [group updateGroupOnCompletion:^(BSGroup *group, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Group successfully updated
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    DELETE /2/contacts/groups/<id>
    

    Note: This will delete the group and all members of it. Make sure to update with a new group_id to move them.

    Response

    204 no content header.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X DELETE \
    "https://api.beepsend.com/2/contacts/groups/1"
    

    DEFINITION

    $client->contact->deleteGroup({GROUP_ID});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $groupId = 123;
    $group = $client->contact->deleteGroup($groupId);
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.contacts().deleteGroup({GROUP_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var groupId = 1;    
    
    client.contacts().deleteGroup(groupId).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSGroup
    
        - (void)removeGroupOnCompletion:(void(^)(BOOL success, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    BSGroup *group = existingGroupToDelete;
    
    [group removeGroupOnCompletion:^(BOOL success, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Group successfully deleted
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    DELETE /2/contacts/groups/members/<id>
    

    Note: This will delete the members inside the affected group and not the group itself.

    Response

    204 no content header.

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    File format

    If the uploaded file contains a header we'll try and parse the names and use that order. If there is no header the ordering below is used as default.

    Number First name Last name
    46760005630 Malcolm Reynolds

    If we can't guess the column order or if there are less than 3 columns we'll fall back to use the first column as phone number.

    Post /2/contacts/upload/
    Parameter Type Description
    group_id int group id
    data string file with contacts

    CURL EXAMPLE

    curl -v \
    -H "Authorization: Token ApiToken123" \
    -H "Content-Type: multipart/form-data" \
    -F "group_id=<id>" \
    -F "data=@path/to/file/christmasCampaign2017.csv" \
    https://api.beepsend.com/2/contacts/uploads/
    
    GET /2/contacts/upload/

    Response

    [
      {
        "id": 4142,
        "group": {
          "id": 16412,
          "name": "easter"
        },
        "filename": "easter_sendout.csv",
        "upload_date": 1469172663,
        "report_available": true,
        "total": 40001,
        "successful": 40001,
        "failed": 0,
        "skipped": 0,
        "status": 2,
        "error": null
      },
      {
        "id": 3244,
        "group": {
          "id": 16003,
          "name": "christmas"
        },
        "filename": "christmas_sendout.csv",
        "upload_date": 1469172641,
        "report_available": true,
        "total": 25000,
        "successful": 25000,
        "failed": 0,
        "skipped": 0,
        "status": 2,
        "error": null
      },
      {
        "id": 3243,
        "group": {
          "id": 16003,
          "name": "christmas"
        },
        "filename": "christmas_sendout.gif",
        "upload_date": 1469172631,
        "report_available": false,
        "total": 25000,
        "successful": 25000,
        "failed": 0,
        "skipped": 0,
        "status": 3,
        "error": "Could not parse uploaded file."
      }
    ]
    
    Key Type Description
    id id The id of the upload.
    group.id id The id of the group.
    group.name string Group name.
    groups array  List of linked groups.
    filename string Name of the uploaded file.
    upload_date int, Unix time Time of the upload.
    report_available boolean If a upload report is ready.
    total int Number of contacts found.
    successful int Number of successful imports.
    failed int Number of failed imports.
    skipped int Number of skipped contacts due to duplicate entries in the group.
    status int 0=uploaded, 1=uplode job started, 2= finished, 3=failed to import contacts.
    errors string / null error description.

    CURL EXAMPLE

    curl \
    -H "Authorization: Token ApiToken123" \
    https://api.beepsend.com/2/contacts/uploads/
    
    GET /2/contacts/upload/

    Response

      {
        "id": 4142,
        "group": {
          "id": 16412,
          "name": "easter"
        },
        "filename": "easter_sendout.csv",
        "upload_date": 1469172663,
        "report_available": true,
        "total": 40001,
        "successful": 40001,
        "failed": 0,
        "skipped": 0,
        "status": 2,
        "error": null
      }
    
    Key Type Description
    id id Upload id.
    group.id id Group id.
    group.name string Group name.
    filename string Name of the uploaded file.
    upload_date int, Unix time Time of the upload.
    report_available boolean If a upload report is ready.
    total int Number of contacts found.
    successful int Number of successful imports.
    failed int Number of failed imports.
    skipped int Number of skipped contacts due to duplicate entries in the group.
    status int 0=uploaded, 1=uplode job started, 2= finished, 3=failed to import contacts.
    errors string / null error description.

    CURL EXAMPLE

    curl \
    -H "Authorization: Token ApiToken123" \
    https://api.beepsend.com/2/contacts/uploads/<id>
    
    GET /2/contacts/upload/<id>/report

    Get a detailed report on contacts or rows in your file that we did no upload.

    Response

    Line number Phone number First name Last name comment
    2 46702137998 46702137998 46702137998 Duplicate: Contact already exist in this group.
    39 1976 Ryan Reynolds Failed: Invalid phone number.
    74 1944 Gary Busey Failed: Invalid phone number.

    CURL EXAMPLE

    curl \
    -H "Authorization: Token ApiToken123" \
    https://api.beepsend.com/2/contacts/uploads/<id>/report
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    GET /2/search/contacts/?query=search_text
    Parameter Type Description
    query
    Required
    string Will search entries matching on id, msisdn, firstname and lastname.
    group_id
    Optional
    int Specify which group to search in.
    include_global
    Optional
    boolean Include contacts that belong to global groups. Global groups are shared between users under the same customer. false by default.
    limit
    Optional
    int Limit the amount of search results.

    Response

    [
        {
            "id": 22594418,
            "msisdn": "46736007518",
            "name": "Phone",
            "groups": []
        },
        {
            "id": 22594420,
            "msisdn": "46406007500",
            "name": "Beepsend",
            "groups": [
                {
                    "id": 213,
                    "name": "Beepnumbers"
                }
            ]
        }
    ]
    
    Key Type Description
    id id The id of the group.
    msisdn string Mobile number.
    name string Contact name.
    groups array  List of linked groups.
    groups.x.id int id of a group this contact is linked to.
    groups.x.name string Name of a group this contact is linked to.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X GET \
    "https://api.beepsend.com/2/search/contacts/?query=Beepsend"
    

    DEFINITION

    $client->search->contacts({QUERY}, {GROUP_ID});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $contacts = $client->search->contacts(46736007518);
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.search().contacts({QUERY}, {GROUP_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var query = "Test contact";
    
    client.search().contacts(query).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSUser
    
        - (void)searchContactsWithQuery:(NSString *)query inGroup:(BSGroup *)group limit:(NSNumber *)limit onCompletion:(void(^)(NSArray *results, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    [[BSUser currentUser] searchContactsWithQuery:@"con" inGroup:nil limit:@100 onCompletion:^(NSArray *results, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (array of BSContact objects)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    GET /2/search/contact_groups/?query=search_text
    Parameter Type Description
    query
    Required
    string Will search entries with matching name.
    include_global
    Optional
    boolean Include global groups that are shared between users under the same customer. false by default.
    limit
    Optional
    int Limit the amount of search results.

    Response

    [
        {
            "id": 1,
            "name": "Customers",
            "contacts_count": 27,
            "processing": 1,
            "owner": {
                "id": 15000,
                "name": "Beepsend-user"
            },
            "global": 0
        },
        {
            "id": 2,
            "name": "Others",
            "contacts_count": 2,
            "processing": 0,
            "owner": {
                "id": 15000,
                "name": "Beepsend-user"
            },
            "global": 1
        }
    ]
    
    Key Type Description
    id id The id of the group.
    name string Contact group name.
    contacts_count int Number of contacts in the group.
    processing int | null This flag is 1 if contacts are being imported, otherwise 0.
    owner string User that owns the group.
    global int, 0/1 1 means that the group is shared between all users under the same customer.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X GET \
    "https://api.beepsend.com/2/search/contact_groups/?query=Test"
    

    DEFINITION

    $client->search->groups({QUERY});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $contacts = $client->search->groups('Test');
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.search().groups({QUERY}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var query = "Test";
    
    client.search().groups(query).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSUser
    
        - (void)searchGroupsWithQuery:(NSString *)query limit:(NSNumber *)limit onCompletion:(void(^)(NSArray *results, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    [[BSUser currentUser] searchGroupsWithQuery:@"group" limit:@100 onCompletion:^(NSArray *results, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (array of BSGroup objects)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    External recipient Emails for pricelist notifications

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    By default, all pricelist and wallet notifications will be sent to the email registered to your user. If you wish to have updates sent to more emails you can add external recipients.

    Get a list of your external emails.

    GET /2/wallets/<wallet id>/emails/

    Response

    [
        {
            "id": 1,
            "email": "support@beepsend.com"
        },
        {
            "id": 2,
            "email": "example@beepsend.com"
        }
    ]
    
    Key Type Description
    id int Email id.
    email string Email address.

    Get details for a specific wallet

    GET /2/wallets/<wallet id>/emails/<email id>
    Parameter Type Description
    id int Id of the requested email
    email string Id of the requested email

    Response

    {
        "id": 1,
        "email": "support@beepsend.com"
    }
    
    Key Type Description
    id int Email id.
    email string Email address.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X GET \
    "https://api.beepsend.com/2/wallets/1/emails/"
    

    DEFINITION

    $client->wallet->notifications({WALLET_ID});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $walletId = 123;
    $emails = $client->wallet->notifications($walletId);
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.wallet().notifications({WALLET_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var walletId = 1;
    
    client.wallet().notifications(walletId).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSWallet
    
        - (void)getEmailsOnCompletion:(void(^)(NSArray *emails, NSArray *errors))block;
        - (void)getEmailWithID:(NSString *)emailID onCompletion:(void(^)(BSEmail *email, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    //List all emails associated with wallet
    BSWallet *wallet = walletToListEmails;
    
    [wallet getEmailsOnCompletion:^(NSArray *emails, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (array of BSEmail objects)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    
    //Check for email with given ID
    [wallet getEmailWithID:@"1234" onCompletion:^(BSEmail *email, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (BSEmail object)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    POST /2/wallets/<wallet id>/emails/
    Parameter Type Description
    email
    Required
    string Email address you want to add as a recipient

    Request Body

    {
        "email": "mailman@beepsend.com"
    }
    

    Response

    {
        "id": 3,
        "email": "mailman@beepsend.com"
    }
    
    Key Type Description
    id int Email id.
    email string Email address.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X POST \
    -d '{"email": "mailman@beepsend.com"}' \
    "https://api.beepsend.com/2/wallets/1/emails/"
    

    DEFINITION

    $client->wallet->addNotificationEmail({WALLET_ID}, {EMAIL});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $walletId = 123;
    $email = $client->wallet->addNotificationEmail($walletId, 'mailman@beepsend.com');
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.wallet().addNotificationEmail({WALLET_ID}, {EMAIL}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var walletId = 1;
    var email = "mailman@beepsend.com";
    
    client.wallet().addNotificationEmail(walletId, email).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSWallet
    
        - (void)addEmail:(NSString *)email onCompletion:(void(^)(BSEmail *email, NSArray *errors))block
    
    @end
    

    CODE EXAMPLE

    BSWallet *wallet = walletToAddNewEmail;
    
    [wallet addEmail:@"email@mail.com" onCompletion:^(BSEmail *email, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (BSHLR object)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    DELETE /2/wallets/<wallet id>/emails/<email id>
    

    Response

    204 no content header.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X DELETE \
    "https://api.beepsend.com/2/wallets/1/emails/2"
    

    DEFINITION

    $client->wallet->deleteNotificationEmail({WALLET_ID}, {EMAIL});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $walletId = 123;
    $emailId = 12;
    $email = $client->wallet->deleteNotificationEmail($walletId, $emailId);
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.wallet().deleteNotificationEmail({WALLET_ID}, {EMAIL_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var walletId = 1;
    var emailId = 2;
    
    client.wallet().deleteNotificationEmail(walletId, emailId).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSWallet
    
        - (void)removeEmail:(BSEmail *)email onCompletion:(void(^)(BOOL success, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    BSWallet wallet = walletToRemoveEmail;
    BSEmail *email = emailToDelete;
    
    [wallet removeEmail:email onCompletion:^(BOOL success, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Email successfully deleted
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    
    }];
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    Get the info for your wallet.

    GET /2/wallets/
    GET /2/wallets/<wallet id>

    Response

    {
        "id": 1,
        "name": "Beepsend new wallet",
        "balance": 47.60858,
        "notify_limit": 10,
        "max_negative_balance": 0,
        "topup_limit": {
            "limit": 20,
            "interval": {
                "amount": 0,
                "seconds": 86400
            }
        },
        "users": [
            {
                "id": 1,
                "name": "Beep Beepson",
                "email": "user@beepsend.se"
            }
        ],
        "connections": [
            {
            "system_id": "beepsend",
            "name": "beepsend-connection",
            "id": 1
            }
        ]
    }
    
    Key Type Description
    id int Wallet id.
    name string Name of the wallet.
    balance float Current balance. In Euro (€).
    notify_limit float When balance is equal to or below this value notification mails is sent to all users of type Financial Contact.
    max_negative_balance float The allowed negative balance for your wallet.
    topup_limit.limit int The maximum allowed amount to top up within a 24 hour period.
    topup_limit.interval.amount float Amount topped up so far within the last 24h period (period started topup.interval.seconds seconds ago)
    topup_limit.interval.seconds int Number of seconds from now that is used to summarize the amount topped up so far (defaults to 86400s = 24h).
    users array Users which will receive warning notification when low balance.
    users.email string  Email address that will receive notification emails.
    users.name string User name
    users.id int User ID.
    connections array Linked connections.
    connections.system_id string Connection login name. Used for SMPP and HTTP v1 api.
    connections.name string  Connection name.
    connection.id int Connection ID.

    CURL EXAMPLE

    Get all wallets connected to account

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X GET \
    "https://api.beepsend.com/2/wallets/"
    

    Get specific wallet

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X GET \
    "https://api.beepsend.com/2/wallets/1"
    

    DEFINITION

    $client->wallet->all();
    $client->wallet->get({WALLET_ID});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    /* Get all wallets  */
    $wallets = $client->wallet->all();
    
    /* Get single wallet */
    $walletId = 123;
    $wallet = $client->wallet->get($walletId);
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.wallet().all().then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    
    client.wallet().get({WALLET_ID}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    /* Get all wallets connected to account */
    
    client.wallet().all().then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    
    /* Get specific wallet by provided id */
    
    var walletId = 1;
    
    client.wallet().get(walletId).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSUser
    
        - (void)getAvailableWalletsOnCompletion:(void(^)(NSArray *wallets, NSArray *errors))block;
        - (void)getWalletDetailsForID:(NSString *)walletID onCompletion:(void(^)(BSWallet *wallet, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    Get list of wallets

    [[BSUser currentUser] getAvailableWalletsOnCompletion:^(NSArray *wallets, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (array of BSWallet objects)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    Get wallet details

    [[BSUser currentUser] getWalletDetailsForID:@"1234" onCompletion:^(BSWallet *wallet, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (BSWallet object)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    Update wallet settings.

    PUT /2/wallets/<wallet id>
    Parameter Type Description
    name
    Optional
    string Wallet name.
    notify_limit
    Optional
    int At what balance level Beepsend should send a notification email about low balance. Email will be sent to your Financial Contact user as well as your external subscribers.

    If you'd like to update your balance, see Wallet Topup

    This endpoint supports partial updates. Any omitted field in a model will read in the current value.

    Request body

    {
        "name": "Beepsend new wallet",
        "notify_limit": 10
    }
    

    Response

    {
        "id": 1,
        "name": "Beepsend new wallet",
        "balance": 47.60858,
        "notify_limit": 10,
        "max_negative_balance": 0,
        "topup_limit": {
            "limit": 20,
            "interval": {
                "amount": 0,
                "seconds": 86400
            }
        },
        "users": [
            {
                "id": 1,
                "name": "Beep Beepson",
                "email": "user@beepsend.se"
            }
        ],
        "connections": [
            {
            "system_id": "beepsend",
            "name": "beepsend-connection",
            "id": 1
            }
        ]
    }
    
    Key Type Description
    id int Wallet id.
    name string Name of the wallet.
    balance float Current balance. In Euro (€).
    notify_limit float When balance is equal or below this value a notification email will be sent to all listed users.
    max_negative_balance float The allowed negative balance for your wallet.
    topup_limit.limit int The maximum allowed amount to top up within a 24 hour period.
    topup_limit.interval.amount float Amount topped up so far within the last 24h period (period started topup.interval.seconds seconds ago)
    topup_limit.interval.seconds int Number of seconds from now that is used to summarize the amount topped up so far (defaults to 86400s = 24h).
    users array Users which will receive warning notification when low balance.
    users.email  string  Email address that will receive notification emails.
    users.name string User name
    users.id  int User ID.
    connections array Linked connections.
    connections.system_id string Connection login name. Used for SMPP and HTTP v1 api.
    connections.name string  Connection name.
    connection.id  int Connection ID.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X PUT \
    -d '{"name": "Beepsend new wallet", "notify_limit": 10}' \
    "https://api.beepsend.com/2/wallets/1"
    

    DEFINITION

    $client->wallet->update({WALLET_ID}, {NAME}, {NOTIFY_LIMIT});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $walletId = 123;
    $wallet = $client->wallet->update($walletId, 'Beepsend new wallet', 10);
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.wallet().update({WALLET_ID}, {NAME}, {NOTIFY_LIMIT}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var walletId = 1;
    var name = "new wallet name";
    var notifyLimit = 10;
    
    client.wallet().update(walletId, name, notifyLimit).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSWallet
    
        @property (nonatomic, strong) NSString *name;
        @property (nonatomic, strong) NSNumber *minimumBalanceForNotification;
    
        - (void)updateWalletOnCompletion:(void(^)(BSWallet *wallet, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    BSWallet *wallet = walletToUpdate;
    wallet.name = @"wallet new name";
    wallet.minimumBalanceForNotification = @0.5;
    
    [wallet updateWalletOnCompletion:^(BSWallet *wallet, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Wallet successfully updated
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    View transactions for given wallet.

    GET /2/wallets/<wallet id>/transactions/
    Parameter Type Description
    since_id
    Optional
    string Return more recent transactions than given ID.
    max_id
    Optional
    string Return transactions with an ID older than or equal to given ID.
    count
    Optional
    int How many transactions to fetch. Maximum 200, default 50.

    Response

    [
      {
        "id": 20,
        "timestamp": 1388669449,
        "new_balance": 8085.56838,
        "change": 200,
      }
    ]
    
    Key Type Description
    id int Transaction id.
    timestamp int Unix time when the transaction took place.
    new_balance float Balance after the transaction.
    change float Amount that was added/deducted from the wallet.
    comment string Comment attached to transaction.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X GET \
    "https://api.beepsend.com/2/wallets/1/transactions/"
    

    DEFINITION

    $client->wallet->transactions({WALLET_ID}, {SINCE_ID}, {MAX_ID}, {COUNT});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $walletId = 123;
    $transactions = $client->wallet->transactions($walletId);
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.wallet().transactions({WALLET_ID}, {SINCE_ID}, {MAX_ID}, {COUNT}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var walletId = 1;
    
    client.wallet().transactions(walletId).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSWallet
    
        - (void)getTransactionLogForNextPage:(BOOL)nextPage onCompletion:(void(^)(NSArray *log, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    BSWallet *wallet = walletForGettingTransactionLog;
    
    [wallet getTransactionLogForNextPage:NO onCompletion:^(NSArray *log, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (array of BSLog objects)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    Transfer credits between your connection wallets.

    POST /2/wallets/<source id>/transfer/<target id>/

    Request Body

    {
        "amount": 123.45
    }
    

    Response

    {
        "source_wallet": {
            "id": 1,
            "name": "wallet-1",
            "balance": 273.45
        },
        "target_wallet": {
            "id": 2,
            "name": "wallet-2",
            "balance": 125
        },
        "amount": 123.45
    }
    

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X POST \
    -d '{"amount": 123.45}' \
    "https://api.beepsend.com/2/wallets/1/transfer/3/"
    

    DEFINITION

    $client->wallet->transfer({SOURCE_ID}, {TARGET_ID}, {AMOUNT});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $sourceId = 123;
    $targetId = 321;
    $response = $client->wallet->transfer($sourceId, $targetId, 123.45);
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.wallet().transfer({SOURCE_ID}, {TARGET_ID}, {AMOUNT}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var sourceId = 1;
    var targetId = 2;
    var amount = 10;
    
    client.wallet().transfer(sourceId, targetId, amount).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSWallet
    
        - (void)transferFunds:(NSNumber *)funds toWallet:(BSWallet *)wallet onCompletion:(void(^)(BSTransfer *transfer, NSArray *errors))block;
        - (void)transferFunds:(NSNumber *)funds fromWallet:(BSWallet *)wallet onCompletion:(void(^)(BSTransfer *transfer, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    BSWallet *wallet1 = walletToTransferFundsFrom;
    BSWallet *wallet2 = walletToTransferFundsTo;
    
    [wallet1 transferFunds:@1.0 toWallet:wallet2 onCompletion:^(BSTransfer *transfer, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (BSTransfer object)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    Calculate the amount after VAT has been applied.

    GET /2/wallets/<wallet id>/topup/vat-check/<amount>

    Response

    {
        "topup_amount": 100,
        "vat_amount": 125,
        "vat_percentage": 25
    }
    
    Key Type Description
    topup_amount float Amount added to your wallet.
    vat_amount float VAT that will be added to your topup_amount when paying.
    vat_percentage float VAT percentage applied.

    This endpoint requres a valid User API-Token. Read more about Users and Connections.

    Add credit to wallet.

    POST /2/wallets/<wallet id>/topup/paypal/
    Parameter Type Description
    amount
    Required
    float The amount in euro to add to the wallet.
    url.return
    Optional
    string The URL to redirect a user when a payment is complete and successful. Default: https://beepsend.com/success.html
    url.cancel
    Optional
    string The URL to redirect a user when a payment is aborted. Default: https://beepsend.com/cancel.html

    Request Body

    {
        "amount": 123.45,
        "url": {
            "return": "https://beepsend.com/success.html",
            "cancel": "https://beepsend.com/cancel.html"
        }
    }
    

    Response

    {
        "url": "https:\/\/www.sandbox.paypal.com\/cgi-bin\/webscr?cmd=_ap-payment&paykey=foo"
    }
    
    Key Type Description
    url string URL to redirect the user to, to complete the transaction.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X POST \
    -d '{"amount": 123.45, "url": {"return": "https://yourdomain.com/success.html", "cancel": "https://yourdomain.com/cancel.html"}}' \
    "https://api.beepsend.com/2/wallets/1/topup/paypal/"
    

    DEFINITION

    $client->wallet->topup({WALLET_ID}, {AMOUNT});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $walletId = 123;
    $response = $client->wallet->topup($walletId, 123.45);
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.wallet().topup({WALLET_ID}, {AMOUNT}, {RETURN_URL}, {CANCEL_URL}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var walletId = 1;
    var amount = 10;
    var returnUrl = "https://beepsend.com/success.html";
    var cancelUrl = "https://beepsend.com/cancel.html";
    
    client.wallet().topup(walletId, amount, returnUrl, cancelUrl).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    Each estimation require a token either assigned to a Connection or a User that has a default connection set up. By specifying a label of a different Connection belonging to your Company this will instead be used, granted the User has access-rights to this Connection. If authenticated by User token and no Connection is specified, the default assigned Connection will be used.

    The endpoints for estimating messages cost are:

    Get details for a default connection

    POST /2/sms/costestimate/

    Get details for a specific connection

    POST /2/sms/costestimate/<connection id>
    POST /2/sms/costestimate/<connection label>

    If you want to check costs for specified mobile numbers send same object as for single send:

    Parameter Type Description
    to
    Required
    string | array The mobile phone number starting with country code and no + sign. Also referred to sometimes as MSISDN. Supports multiple values in an array.
    message
    Optional
    string Message body. If using international characters, You will need to URL encode the message. Note Multiple destinations count as multiple messages and will be charged as such.
    encoding
    Optional
    string UTF-8, ISO-8859-15 or Unicode. If omitted, the default charset is UTF-8. The unicode uses the UCS2 standard UTF16-BE.

    You can also check cost for groups, just replace parameter to by groups

    Parameter Type Description
    groups
    Required
    string | array The id of contacts group that have to exist in our system. Supports multiple values in an array.

    Request body

    {
        "to": "46736007518",
        "message": "Hello World! 你好世界!"
    }
    

    For groups

    {
        "groups": [
            "11",
            "34"
        ],
        "message": "Hello World! 你好世界!"
    }
    

    You can also send batch. Just put your SMS objects into an array.

    [
        {
            "to": "46736007518",
            "message": "Hello World! 你好世界!",
        },
        {
            "groups": [
                "11",
                "34"
            ],
            "message": "Hello World! 你好世界!",
        }
    ]
    

    Response

    [
        {
           "total_cost": 0.0032,
           "to": [
              "46736007518": 0.0032
           ]
        },
        {
           "total_cost": 358.57,
           "groups": [
              "11": 13.45,
              "34": 345.12
           ]
        }
    ]
    
    Key Type Description
    total_cost float Total estimated cost for all messages
    to array(string:float) Array containing number and it's cost

    or

    Key Type Description
    total_cost float Total estimated cost for all messages
    groups array(string:float) Array containing group id and it's cost

    CURL EXAMPLE

    Estimate SMS cost

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X POST \
    -d '{"to": "46736007518", "message": "Hello World! 你好世界!"}' \
    "https://api.beepsend.com/2/sms/costestimate/"
    

    Estimate group SMS cost

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X POST \
    -d '{"groups":["11","34"],"message": "Hello World! 你好世界!"}' \
    "https://api.beepsend.com/2/sms/costestimate/"
    

    Estimate batch SMS cost

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X POST \
    -d '[{"to": ["46736007518","35736007505"],"message": "Hello Mr. Nilsson!"},{"groups": ["11","34"],"message": "Hello World! 你好世界!"}]' \
    "https://api.beepsend.com/2/sms/costestimate/"
    

    DEFINITION

    $client->message->estimateCost({TO}, {MESSAGE}, {CONNECTION}, {ENCODING});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    /* Get estimate cost for sms */
    $sms = $client->message->estimateCost(46736007518, 'Hello World! 你好世界!');
    
    /* Get estimate cost for sendin sms to groups */
    $sms = $client->message->estimateCostGroup(array(11, 34), 'Hello World! 你好世界!');
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.messages().estimateCost({TO}, {MESSAGE}, {CONNECTION}, {ENCODING}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    
    client.messages().estimateCostGroup({GROUPS}, {MESSAGE}, {CONNECTION}, {ENCODING}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    /* Estimate cost for single message */
    
    var to = 46736007518;
    var message = "Hello World!";
    var connection = "";
    var encoding = "UTF-8";
    
    client.messages().estimateCost(to, message, connection, encoding).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    
    /* Estimate cost for group message */
    
    var groups = ["11", "34"];
    var message = "Hello World!";
    var connection = "";
    var encoding = "UTF-8";
    
    client.messages().estimateCostGroup(groups, message, connection, encoding).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSConnection
    
        - (void)estimateSMSCostForMessages:(NSArray *)messages onCompletion:(void(^)(NSArray *cost, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    BSMessage *sms1 = [BSMessage messageWithBody:@"Message body" from:@"Sender name or number" to:@"012345678900"];
    [sms1 addGroupsRecipients:@[group1, group2]];
    
    BSMessage *sms2 = [BSMessage messageWithBody:@"Message body" from:@"Sender name or number" toMultiple:@[@"012345678900", @"012345678901"]];
    [sms2 addGroupsRecipients:@[group1]];
    
    BSMessage *sms3 = [BSMessage messageWithBody:@"Message body" from:@"Sender name or number" toGroups:@[group1, group2]];
    
    [[BSConnection currentConnection] estimateSMSCostForMessages:@[sms1, sms2, sms3] onCompletion:^(NSArray *cost, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (array of BSEstimateCost objects)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    

    Miscellaneous

    Get list of all message status errors with response codes.

    GET /2/errors/

    Response

    [
        {
            "id": 0,
            "description": "No error."
        },
        {
            "id": 1,
            "description": "Absent subscriber. The HLR responded to the SRI for SM request with an error indicating the subscriber is absent."
        }
    ]
    
    Key Type Description
    id int Error id
    description string Error description

    Get details for specific message status error code.

    GET /2/errors/<error id>

    Response

    {
        "id": 4,
        "description": "Equipment not equipped with short-message capability."
    }
    
    Key Type Description
    id int Error id
    description string Error description

    Codes that represent message status.

    Id Description
    0 No error.
    1 Absent subscriber. The HLR responded to the SRI for SM request with an error indicating the subscriber is absent.
    2 Handset memory capacity exceeded. Handset has run out of free memory to store new message.
    3 Equipment protocol error.
    4 Equipment not equipped with short-message capability.
    5 Unknown subscriber. The IMSI is unknown in the HLR. The HLR responded to the SRI for SM request with an error indicating the subscriber is unknown.
    6 Illegal subscriber. The mobile station failed authentication.
    7 Teleservice not provisioned. Mobile subscription identified by the MSISDN number does include the short message service.
    8 Illegal equipment. IMEI check failed, i.e. The IMEI is either blacklisted or not whitelisted.
    9 Call barred. Operator barred the MSISDN number.
    10 Facility not supported. VLR in the PLMN does not support MT short message service.
    11 Subscriber busy for MT short message.
    12 System failure. Task cannot be completed because of a problem in another entity.
    13 Data missing. Necessary parameter is not present in the primitive.
    14 Unexpected data value. Necessary data is badly formatted in the primitive.
    15 Unidentified subscriber. Subscriber is not contained in the database and it has not or cannot be established whether or not a subscription exists.
    16 Absent subscriber. No paging response via MSC.
    17 Absent subscriber. IMSI detached.
    18 Absent subscriber. Roaming restriction.
    20 Mobile subscriber not reachable
    21 Local cancel - No response for the SRI for SM request was received.
    47 TCAP error.
    49 SMS discarded. This error is specific to IP-based protocols like SMPP.
    50 SMS window exceeded.
    51 SMS malformed. SMS is not formed correctly. This error is specific to IP-based protocols like SMPP.
    52 SMS expired.
    53 Insufficient credit. The user has insufficient credit/not allowed to send to that destination.
    54 Invalid destination. Receiver is not a valid number.
    55 Unable to find outbound route for this SMS.
    56 SMS buffered.
    57 Timeout waiting for response from peer.
    58 Throttling Error. The user has exceeded allowed message limit.
    59 Absent Subscriber: The message is undeliverable because the subscriber is temporarily absent, e.g. their phone is switch off, they cannot belocated on the network.
    60 Portability error: The message was failed due to the ported combinations being unreachable.
    61 Invalid PDU Format
    62 ESME Client Error
    63 Local ACL Deny
    64 Invalid Payload Length
    65 Remote Logic Error
    66 Remote Logic Deny
    67 DCS inconsistency
    68 Route error, please contact Beepsend support
    69 Rejected - SMSC rejected the SRI for SM request.
    70 PSA Connection failed
    162 Abort - The HLR (or some other entity in the network) aborted the SRI for SM re- quest.
    205 Illegal subscriber
    206 Illegal equipment
    218 Screening error, Terminating IMSI blocked
    255 Unknown error
    711 Destination network or country is blocked. Contact with your AM to unblock this network/country
    712 Insufficient credits to send message
    713 SMS sent, no delivery report received.
    714 Route loop detected
    716 Flood protection – Multiple identical messages to Recipient detected
    717 Invalid srcAddr
    718 Invalid msisdn/destAddr
    800 The end user does not exist
    801 The end user is blocked
    802 The end user belongs to a network operator that does not allow charge
    803 The end user is not allowed to purchase premium services.
    804 The end user has insufficient funds
    805 Unknown operator
    810 Subscription failed
    811 SMS submit from SMSGW to SMSC failure
    812 No MT connection found for short number
    813 The recipient has no credit
    814 Charged failed
    815 Invalid service id from the request.
    816 The subscription period to the associated service is already expired.
    817 Invalid input format. Mandatory parameter MSISDN not found in request.
    826 Message body error
    827 No route found
    828 Message too long
    829 Internal server error
    830 Invalid source address
    831 Invalid destination address
    832 Login incorrect
    833 Missing params
    834 Invalid params
    835 Data not found
    907 Credit related message may be being retried
    920 Permanent operator error
    921 Credit related: message has been retried by operator
    925 Operator network failure
    926 Phone related error
    927 Permanent phone related error
    928 Blocked due to spam
    929 Content related error
    930 Subscriber spend limit exceeded
    931 Subscriber unable to be billed
    933 Age verification failure parental lock
    935 Age verification failure no previous AV
    936 Age verification failure temporary AV error
    937 National blacklist

    Error codes for api responses.

    Note: These codes won't come up in the /2/errors/ endpoint or be searchable trough /2/errors/<error id> since we throw them before accepting the SMS traffic. The /2/errors/ endpoint is for codes regarding already accepted traffic.

    Id Description
    1024 Out of credits
    1025 Illegal characters in message body
    1026 Message body error
    1027 No Valid Route found
    1028 Message too long
    1029 Internal server error
    1030 Invalid source address
    1031 Invalid destination address
    1032 Invalid account or password
    1033 Invalid send time
    1034 Login incorrect
    1035 Flood detected
    1036 Invalid parameter
    1037 Invalid receive dlr value
    1038 Access error
    1039 Requested object does not exist
    1040 Requested object not modifiable
    1041 Invalid validity period

    CURL EXAMPLE

    Get all error codes and the descriptions

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X GET \
    "https://api.beepsend.com/2/errors/"
    

    Get an error code and the description

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" -X GET \
    "https://api.beepsend.com/2/errors/1"
    

    DEFINITION

    $client->error->all();
    $client->error->get({id});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    /* Get all error codes and the descriptions */
    $client->error->all()
    
    /* Get an error code and the description */
    $client->error->get(1)
    

    An email will be sent out after changing your email address asking you to verify that you have indeed changed it. Use the unique hash in the verification link to perform the verification.

    GET /2/users/email/<hash>

    Response

    204 no content header.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/users/email/<hash>"
    

    DEFINITION

    $client->user->verifyEmail({HASH});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $user = $client->user->verifyEmail('<hash>');
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.user().verifyEmail({HASH}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var hash = "1231as141";
    
    client.user().verifyEmail(hash).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    After changing your phone number. An SMS will be sent out asking you to verify the change. Use the unique hash to verify.

    GET /2/users/phone/<hash>

    Response

    204 no content header.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" "https://api.beepsend.com/2/users/phone/<hash>"
    

    DEFINITION

    $client->user->verifyPhone({HASH});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $user = $client->user->verifyPhone('<hash>');
    

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.user().verifyPhone({HASH}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var hash = "1231as141";
    
    client.user().verifyPhone(hash).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    When doing pagination with the Beepsend API you use the parameters since_id and max_id.

    It is a great way to efficiently filter the data you want, but we understand that they can be confusing to understand at first,

    We would like to refer to the following text by Twitter to get a deeper understanding of how it works.

    https://dev.twitter.com/docs/working-with-timelines

    We strongly recommend that you use our new /2/send endpoint for sending a single message and /2/sendouts endpoint for sending multiple messages as this endpont will soon be unavailable!

    Each sent message require a token either assigned to a Connection or a User that has a default connection set up. By specifying a label of a different Connection belonging to your Company this will instead be used, granted the User has access-rights to this Connection. If authenticated by User token and no Connection is specified, the default assigned Connection will be used.

    A message can carry 160 characters if in the Latin alphabet and 70 if content is Unicode. The Beepsend Gateway will automatically split up the message if the content exceeds the maximum character limit based on the content encoding. When sending UTF-8 encoding the Beepsend Gateway will try and convert to GSM7 if possible to avoid splitting at 70 characters.

    The endpoint for sending messages is:

    POST /2/sms/

    Specify which connection to use for sending this message. This can be useful if you are authenticating with a User token and do not want to send with your default connection.

    POST /2/sms/<connection id>
    POST /2/sms/<connection label>
    Parameter Type Description
    to
    Required
    string | array The mobile phone number starting with country code and no + sign. Also referred to sometimes as MSISDN. Supports multiple values in an array.
    Note Multiple destinations count as multiple messages and will be charged as such.
    message
    Required
    string Message body.
    from
    Required
    string Sender id. Check below for a list of allowed formats.
    batch_id
    Optional
    int The id of an existing batch of messages. This can later be used to look up details regarding your messages.
    batch_label
    Optional
    string The name of your batch of messages. Can be used to create a new batch or reuse an older batch with the same name. If batch_id is also specified, batch_label will be ignored.
    send_time
    Optional
    int, Unix time Schedule message to be delivered at a certain time in the future. Note Credits will be deducted from your connection at the time of sending for the price at that time. Therefore we do not encourage delivery dates set long in the future.
    encoding
    Optional
    string UTF-8, ISO-8859-15 or Unicode. If omitted, the default charset is UTF-8. The unicode uses the UCS2 standard UTF16-BE.
    message_type
    Optional
    string flash or binary. If omitted, a normal message will be sent. Flash sms can contain only ASCII alphanumeric characters.
    validity_period
    Optional
    int, Unix time How long a message is relevant to the end user. If this expires, the message won't continue to be routed. Default is infinite.
    receive_dlr
    Optional
    int Specify whether delivery reports should be sent to your DLR Callback URL.
    0: Disable, 1: Always, 2: Only on failure. Default is 1.
    auto_gsm7_conversion
    Optional
    true | false Setting this flag to false will disable UTF-8 to GSM7 conversion. By default this flag is true.

    Request body

    {
        "batch_label": "My custom name for my batch",
        "to": "46736007518",
        "message": "Hello World! 你好世界!",
        "from": "Beepsend",
        "send_time": 1383225355,
        "encoding": "UTF-8",
        "receive_dlr": false
    }
    

    Response

    [
        {
            "id": "07595980013893439611559146736007518",
            "batch": {
                "id": 3,
                "label": "My custom name for my batch"
            },
            "to": "46736007518",
            "from": "Beepsend",
            "errors": null
        }
    ]
    
    Key Type Description
    id string | null Unique Beepsend generated ID. If the SMS got rejected, null.
    batch array | null Object with id and label. null if neither batch_label nor batch_id was supplied or the SMS got rejected.
    batch.id int Unique batch id.
    batch.label string Name of batch.
    to string Input destination for this particular SMS.
    from string Input source.
    errors null | array Null if everything went ok. Else an array of errors. See Errors.

    The following formats are allowed for from.

    • Alphanumeric signs with upper or lower case characters (a-z, A-Z, 0-9). The maximum allowed characters are 11. We crop the from address at 11 characters.

    • MSISDN numbers, international format. Minimum 9 chars, max 17 chars.

    • Short numbers / codes, national format. Maximum length 7 chars.

    Local restrictions apply. Check with your account manager for the destinations you aim to send to for details.

    Long SMS

    Long SMS are messages with more than 160 (70 if unicode encoding) characters.
    Beepsend will automatically split up your long messages before sending so you don't have to worry about it. Unless you're sending binary SMS.

    Since long SMS are really just two or more messages with a special identifier that connects them, you will receive a response with separate IDs for each message you are sending. Similar to the response of multi address sending or batch sendouts.

    Billing is done based on how many parts the message in total requires.

    Send multiple messages to one or more receivers.

    POST /2/sms/
    POST /2/sms/<connection id>
    POST /2/sms/<connection label>

    Messages are sent either as single objects, or multiple objects inside an array. So it's easy to send different messages at the same time.

    Request body

    It's like sending a single SMS. Just put your SMS objects into an array.

    [
        {
            "batch_label": "Lottery winner",
            "to": "12345",
            "message": "You won!",
            "from": "Beepsend",
            "send_time": 1383225355,
            "encoding": "UTF-8",
            "message_type": "flash"
        },
        {
            "batch_label": "Lottery contestants",
            "to": [
                "123456",
                "1234567"
            ],
            "message": "Better luck next time!",
            "from": "Beepboop",
            "send_time": 1383225385,
            "encoding": "UTF-8"
        }
    ]
    

    Response

    You receive individual response objects for each SMS.

    [
        {
            "id": "03003620013893441731559112345",
            "batch": {
                "id": 10,
                "label": "Lottery winner"
            },
            "to": "12345",
            "from": "Beepsend",
            "errors": null
        },
        {
            "id": "030889300138934417315591123456",
            "batch": {
                "id": 11,
                "label": "Lottery contestants"
            },
            "to": "123456",
            "from": "Beepboop",
            "errors": null
        },
        {
            "id": "0310373001389344173155911234567",
            "batch": {
                "id": 11,
                "label": "Lottery contestants"
            },
            "to": "1234567",
            "from": "Beepboop",
            "errors": null
        }
    ]
    
    Status code Case
    201 All messages sent successfully.
    200 Some messages sent, check errors.
    403 All messages failed.
    POST /2/sms/
    POST /2/sms/<connection id>
    POST /2/sms/<connection label>

    If your system rather sends the messages using binary content we offer a service for this. The combined length of a binary message and UDH can not be longer than 140 bytes (280 hex characters), if you want to send concatenated messages you have to do this by sending a sequence of messages with the appropriate UDH.

    To send a binary SMS. You need to have message_type set to binary. When sending binary SMS the following options become available.

    Parameter Type Description
    udh
    Optional
    string User Data Header. Can be used to send Concatenated or Wap Push messages.
    dcs
    Optional
    int Data coding settings. For binary messages this is set to 4 (8-bit binary) by default. Should be 0 for gsm7 encoded messages and 8 for UCS-2 encoded messages.

    Send one message to multiple receivers.

    POST /2/sms/
    POST /2/sms/<connection id>
    POST /2/sms/<connection label>

    Request body

    To send to multiple destinations, just make to an array of addresses instead of a string.

    {
        "batch_id": 7,
        "to": [
            "12345",
            "123456",
            "1234567"
        ],
        "message": "Hello World!",
        "from": "Beepsend",
        "send_time": 1383225355,
        "encoding": "UTF-8",
        "message_type": "flash"
    }
    

    Response

    You will receive individual objects in response.

    [
        {
            "id": "07177940013893440591559112345",
            "batch": {
                "id": 7,
                "label": "My multi destination batch"
            },
            "to": "12345",
            "from": "Beepsend",
            "errors": null
        },
        {
            "id": "072644000138934405915591123456",
            "batch": {
                "id": 7,
                "label": "My multi destination batch"
            },
            "to": "123456",
            "from": "Beepsend",
            "errors": null
        },
        {
            "id": "0727961001389344059155911234567",
            "batch": {
                "id": 7,
                "label": "My multi destination batch"
            },
            "to": "1234567",
            "from": "Beepsend",
            "errors": null
        }
    ]
    
    Status code Case
    201 All messages sent successfully.
    200 Some messages sent, check errors.
    403 All messages failed.

    The API can be utilized to get details of any message sent through Beepsend no matter if you submitted it via SMPP or HTTP.

    Get details regarding one message. This end point is subject to rate limits. The API is restricted to allow 90 requests in a 15 minute interval for a specific sms id and token.

    GET /2/sms/<sms id>

    Response

    {
        "id": "12345",
        "batch": {
            "id": 52,
            "label": "Super batch!"
        },
        "body": "Hello World!",
        "hex_body": "48656c6c6f20576f726c6421",
        "connection": {
            "id": 7,
            "label": "superman-connection"
        },
        "to": {
            "address": "46406007500",
            "ton": 1,
            "npi": 1
        },
        "from": {
            "address": "Beepsend",
            "ton": 1,
            "npi": 1
        },
        "validity_period": "131102072704000-",
        "data_coding": 3,
        "timestamps": {
            "sms": {
                "in": 1383225355,
                "delivered": 1383225359
            },
            "dlr_out": 1383225359
        },
        "dlr": {
            "status": "DELIVRD",
            "error": 0
        },
        "price": 0.068,
        "mccmnc": {
            "mcc": "240",
            "mnc": "01"
        }
    }
    
    Key Type Description
    id string Unique Beepsend generated ID.
    batch array | null Array with id and label or null if message was sent with no batch specified.
    body string The message body of sent SMS.
    hex_body string Hex encoded string containing the raw body of sent SMS (or sms part if it's multipart message).
    connection array Connection details.
    connection.id int The id of the connection that was used to send the SMS.
    connection.label string The name of the connection that was used to send the SMS.
    to.address string Destination address.
    to.ton int Type of number.
    to.npi int Number Plan Index.
    from.address string Source address.
    from.ton int Type of number.
    from.npi int Number Plan Index.
    validity_period string Until what date and time the message is considered valid for routing. Formatted like YYMMDDhhmmsstnnp according to the SMPP standard.
    data_coding int Data coding settings. 0 for Gsm7 encoded messages. 8 for UCS-2 encoded messages and 4 for binary messages. Can be set manually if sending Binary SMS.
    timestamps.sms.in int When the message reached Beepsend in Unix time.
    timestamps.sms.delivered int | null When the message was delivered to handset. In Unix time. null if not yet delivered.
    timestamps.dlr_out int | null When the Delivery Report left our system to reach your DLR Callback URL. null if message has not been delivered yet.
    dlr.status string | null One of the following: DELIVRD, EXPIRED, REJECTD, UNKNOWN, UNDELIV, FAILED. Or null if message has not yet been delivered.
    dlr.error int | null Specific return codes regarding message delivey. 0 if OK. Beepsend Return Codes. null if message has not been delivered yet.
    price float Message price.
    mccmnc.mcc string Destination mcc.
    mccmnc.mnc string Destination mnc.

    In case of a multipart SMS. body will be concatenated to contain all the parts.

    Get details regarding multiple sent messages with filters. Result is sorted by date in descending order.

    GET /2/sms/?<parameter>=<value>
    Parameter Type Description
    to
    Optional
    string MSISDN, the to address.
    from
    Optional
    string Sender id. The from address.
    connection_id
    Optional
    int ID of the connection used to send the message.
    batch_id
    Optional
    string The id of your batch of messages. Will return every message sent with the same batch id or batch label.
    status
    Optional
    string Comma separated list of statuses to search for. Available: delivrd, undeliv, expired, rejectd, unknown, failed, mosms, deleted.
    from_date
    Optional
    int, Unix time Filter messages sent from this date (inclusive interval).
    to_date
    Optional
    int, Unix time Filter messages sent till this date (inclusive interval).
    count
    Optional
    int How many SMS objects to fetch. Maximum 200, default 100.

    Response

    you will receive multiple SMS objects in an array as a response.

    [
        {
            "id": "12345",
            "batch": null,
            "body": "Hello World!",
            "hex_body": "48656c6c6f20576f726c6421",
            "connection": {
                "id": 7,
                "label": "superman-connection"
            },
            "to": {
                "address": "46406007500",
                "ton": 1,
                "npi": 1
            },
            "from": {
                "address": "Beepsend",
                "ton": 1,
                "npi": 1
            },
            "validity_period": "131102072704000-",
            "data_coding": 3,
            "timestamps": {
                "sms": {
                    "in": 1383225355,
                    "delivered": null
                },
                "dlr_out": null
            },
            "dlr": {
                "status": null,
                "error": null
            },
            "price": 0.068,
            "mccmnc": {
                "mcc": "240",
                "mnc": "01"
            }
        }
    ]
    
    Key Type Description
    id string Unique Beepsend generated ID.
    batch array | null Array with id and label or null if message was sent with no batch specified.
    body string The message body of sent SMS.
    hex_body string Hex encoded string containing the raw body of sent SMS (or sms part if it's multipart message).
    connection array Connection details.
    connection.id int The id of the connection that was used to send the SMS.
    connection.label string The name of the connection that was used to send the SMS.
    to.address string Destination address.
    to.ton int Type of number.
    to.npi int Number Plan Index.
    from.address string Source address.
    from.ton int Type of number.
    from.npi int Number Plan Index.
    validity_period string Until what date and time the message is considered valid for routing. Formatted like YYMMDDhhmmsstnnp according to the SMPP standard.
    data_coding int Data coding settings. 0 for Gsm7 encoded messages. 8 for UCS-2 encoded messages and 4 for binary messages. Can be set manually if sending Binary SMS.
    timestamps.sms.in int When the message reached Beepsend in Unix time.
    timestamps.sms.delivered int | null When the message was delivered to handset. In Unix time. null if not yet delivered.
    timestamps.dlr_out int | null When the Delivery Report left our system to reach your DLR Callback URL. null if message has not been delivered yet.
    dlr.status string | null One of the following: DELIVRD, EXPIRED, REJECTD, UNKNOWN, UNDELIV, FAILED. Or null if message has not yet been delivered.
    dlr.error int | null Specific return codes regarding message delivey. 0 if OK. Beepsend Return Codes. null if message has not been delivered yet.
    price float Message price.
    mccmnc.mcc string Destination mcc.
    mccmnc.mnc string Destination mnc.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" \
    -X POST -d '{"to": "46736007518", "message": "Hello World! 你好世界!", "from": "Beepsend", "encoding": "UTF-8", "receive_dlr": false}' \
    "https://api.beepsend.com/2/sms/"
    

    DEFINITION

    $client->message->send({TO}, {FROM}, {MESSAGE}, {CONNECTION}, {ENCODING}, {OPTIONS});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $connectionId = 1;
    
    $options = array(
        'batch_label' => 'My custom name for my batch',
        'receive_dlr' => false
    );
    
    $message = $client->message->send(
        46736007518, 
        'Beepsend', 
        'Hello World! 你好世界!', 
        $connectionId, 
        'UTF-8', 
        $options
    );
    

    You can also set null for connection id and the "me" alias is used to reference the default connection

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.messages().send({FROM}, {TO}, {MESSAGE}, {CONNECTION}, {ENCODING}, {OPTIONS}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var from = "Beepsend";
    var to = "46736007518";
    var message = "Hello World!";
    /* You can provide specific connection if you want to send from another connection account */
    var connection = "";
    var encoding = "UTF-8";
    
    /* Aditional options */
    var options = {
        "batch_label": "My custom name for my batch",
        "send_time": 1383225355,
        "receive_dlr": false
    };
    
    client.messages().send(from, to, message, connection, encoding, options).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSConnection
    
        - (NSInteger)sendSMS:(BSMessage *)message withCompletionBlock:(void(^)(BSMessage *message, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    BSMessage *sms = [BSMessage messageWithBody:@"Message body" from:@"Sender name or number" to:@"012345678900"];
    
    [[BSConnection currentConnection] sendSMS:sms withCompletionBlock:^(BSMessage *message, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (BSMessage object)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    
    We strongly recommend that you use our new /2/send endpoint for sending a single message and /2/sendouts endpoint for sending multiple messages as this endpont will soon be unavailable!

    Each sent message require a token either assigned to a Connection or a User that has a default connection set up. By specifying a label of a different Connection belonging to your Company this will instead be used, granted the User has access-rights to this Connection. If authenticated by User token and no Connection is specified, the default assigned Connection will be used.

    Get your previous batches with messages.

    GET /2/batches/
    GET /2/batches/?<parameter>=<value>
    Parameter Type Description
    count
    Optional
    int How many objects to fetch. Maximum 200, default 200.
    offset
    Optional
    int What row offset in result set to fetch data from.

    Response

    [
        {
            "id": 3,
            "label": "My custom name for my batch",
            "date_created": 1386777418,
            "last_used": 1387442294
        },
        {
            "id": 4,
            "label": "batch testing",
            "date_created": 1387457467,
            "last_used": 1387457467
        }
    ]
    
    Key Type Description
    id int Batch id.
    label string Batch name.
    date_created int, Unix time Creation time of batch.
    last_used int, Unix time Last time the batch was used to send a message.

    Get details for a specific batch.

    GET /2/batches/<batch id>

    Response

    {
        "id": 2,
        "label": "batch testing",
        "date_created": 1387457467,
        "last_used": 1387457467
    }
    
    Key Type Description
    label string Batch name.
    date_created int, Unix time Creation time of batch.
    last_used int, Unix time Last time the batch was used to send a message

    Two Way Batch

    This call will give a paginated overview of messages in a batch, complete with sent and received message body, recipient number and contact details, if recipient number exists in user contacts. The mobile terminated messages are matched with their mobile originated counterpart

    GET /2/batches/<ID>/messages/
    Parameter Type Description
    count
    Optional
    int How many objects to fetch. Maximum 200, default 200.
    offset
    Optional
    int What row offset in result set to fetch data from. Default is 0.

    Response

    [
      {
        "mt_sms_id": "889000680270500421",
        "mt_body": "What is your name?",
        "mt_timestamp": 1418030569,
        "mo_sms_id": "889000680270500422",
        "mo_body": "Sir Lancelot",
        "mo_timestamp": 1418030569,
        "dlr_stat": "DELIVRD",
        "to" : {
            "number": "46736007500",
            "contact" : {
                "firstname": "Foo",
                "lastname": "Bar"
            }
        }
      },
      {
        "mt_sms_id": "889000680141388005",
        "mt_body": "What is your quest?",
        "mt_timestamp": 1418030569,
        "mo_sms_id": "889000680141388006",
        "mo_body": "To seek the holy grail",
        "mo_timestamp": 1418030569,
        "dlr_stat": "DELIVRD",
        "to" : {
            "number": "46736007500",
            "contact" : {
                "firstname": "Foo",
                "lastname": "Bar"
            }
        }
      },
      {
        "mt_sms_id": "889000680141388005",
        "mt_body": "What is your favorite color?",
        "mt_timestamp": 1418030569,
        "mo_sms_id": "889000680141388006",
        "mo_body": "BLUE!",
        "mo_timestamp": 1418030569,
        "dlr_stat": "DELIVRD",
        "to" : {
            "number": "46736007500",
            "contact" : {
                "firstname": "Foo",
                "lastname": "Bar"
            }
        }
      }
    ]
    
    Key Type Description
    mt_sms_id string Unique Beepsend generated ID.
    mt_body string UTF-8 encoded message body of the mobile terminated message.
    mt_timestamp int|null Unix time of when the message was sent.
    mo_sms_id string Unique Beepsend generated ID.
    mo_body string UTF-8 encoded message body of the mobile originated message.
    mo_timestamp int|null Unix time of when a reply was received.
    dlr_stat string Response status.
    to object
    to.number string Recipient number
    to.contact object
    to.contact.firstname string Firstname of contact.
    to.contact.lastname string Lastname of contact.

    Two Way Batch CSV

    This call will give all messages in a batch formatted as CSV.

    GET /2/batches/<ID>/messages.csv
    Parameter Type Description
    delimiter
    Optional
    string What delimiter to use for the csv output. (Default: , <comma>)

    Fields in the CSV file are

    Field Description
    number Recipient's number.
    firstname Firstname of the contact (might be empty).
    lastname Lastname of the contact (might be empty).
    sent_sms_id Outgoing SMS ID.
    sent_body Text sent to the recipient.
    sent_sms_timestamp ISO-8601 formatted time when the message was sent.
    delivery_status Status of the outgoing message.
    incoming_sms_id Incoming SMS ID.
    incoming_message Text received from the recipient.
    incoming_sms_timestamp ISO-8601 formatted time when the message was received.
    ## Batch Details

    This call will give you delivery statistics for a whole batch.

    GET /2/analytics/batches/
    GET /2/analytics/batches/<ID>
    GET /2/analytics/batches/?<parameter>=<value>
    Parameter Type Description
    count
    Optional
    int How many objects to fetch. Maximum 200, default 200.
    offset
    Optional
    int What row offset in result set to fetch data from.

    Response

    [
        {
            "id": 23,
            "label": "My batch",
            "total": 142,
            "statistics": {
                "delivered": 100,
                "expired": 12,
                "unknown": 20,
                "rejected": 0,
                "undelivered": 10,
                "no_dlr": 0
            },
            "total_responses": 10,
            "responses": [
                {
                    "text": "yes",
                    "count": 7
                },
                {
                    "text": "no",
                    "count": 3
                }
            ]
        }
    ]
    
    Key Type Description
    id int Unique batch id
    label string Batch name
    total int Total amount of messages in the batch
    statistics.delivered int Amount of messages with status delivered to handset
    statistics.expired int Amount of messages that suffered time out
    statistics.unknown int Failed messages without a clear error
    statistics.rejected int Messages not accepted by Operator
    statistics.undelivered int Failed messages. Unlike unknown, an error code was returned
    statistics.no_dlr int Messages still in the process of sending
    responses_total int Number of responses.
    responses array
    responses.text string The content of the response.
    responses.count int The amount of responses with this text.

    In Batch

    Send multiple messages to one or more receivers.

    POST /2/sms/
    POST /2/sms/<connection id>
    POST /2/sms/<connection label>

    Messages are sent either as single objects, or multiple objects inside an array. So it's easy to send different messages at the same time.

    Request body

    It's like sending a single SMS. Just put your SMS objects into an array.

    [
        {
            "batch_label": "Lottery winner",
            "to": "12345",
            "message": "You won!",
            "from": "Beepsend",
            "send_time": 1383225355,
            "encoding": "UTF-8",
            "message_type": "flash"
        },
        {
            "batch_label": "Lottery contestants",
            "to": [
                "123456",
                "1234567"
            ],
            "message": "Better luck next time!",
            "from": "Beepboop",
            "send_time": 1383225385,
            "encoding": "UTF-8"
        }
    ]
    

    Response

    [
        {
            "id": "03003620013893441731559112345",
            "batch": {
                "id": 10,
                "label": "Lottery winner"
            },
            "to": "12345",
            "from": "Beepsend",
            "errors": null
        },
        {
            "id": "030889300138934417315591123456",
            "batch": {
                "id": 11,
                "label": "Lottery contestants"
            },
            "to": "123456",
            "from": "Beepboop",
            "errors": null
        },
        {
            "id": "0310373001389344173155911234567",
            "batch": {
                "id": 11,
                "label": "Lottery contestants"
            },
            "to": "1234567",
            "from": "Beepboop",
            "errors": null
        }
    ]
    

    Response for message sent to groups:

    Key Type Description
    batch array | null Object with id and label. null if neither batch_label nor batch_id was supplied or the SMS got rejected.
    batch.id int Unique batch id.
    batch.label string Name of batch.
    groups array (string) Ids of groups to which this message was sent
    from string Input source.
    errors null | array Null if everything went ok. Else an array of errors. See Errors.
    Status code Case
    201 All messages sent successfully.
    200 Some messages sent, check errors.
    403 All messages failed.

    Sending to imported groups of numbers

    Send messages to groups or numbers.

    POST /2/batches/

    Use specific connections to send messages

    POST /2/batches/<connection id>
    POST /2/batches/<connection label>

    You can send single SMS or batch SMS but instead using 1 or more to addresses you can import contacts and send to a full contacts group

    To send message to contacts groups just add to standard sms parameter groups, parameter to is optional

    Parameter Type Description
    groups
    Required
    string | array The id of contants group that have to exist in our system. Supports multiple values in an array.
    to
    Optional
    string | array The mobile phone number starting with country code and no + sign. Also referred to sometimes as MSISDN. Supports multiple values in an array.

    Request body

    [
        {
            "batch_label": "Lottery winner",
            "groups": [
                "1",
                "2"
            ],
            "to": [
                "123456",
                "1234567"
            ],
            "message": "You won!",
            "from": "Beepsend",
            "send_time": 1383225355,
            "encoding": "UTF-8",
            "message_type": "flash"
        }
    ]
    

    Response

    [
        {
            "batch": {
                "id": 10,
                "label": "Lottery winner"
            },
            "groups": [
                "1",
                "2"
            ],
            "from": "Beepsend",
            "errors": null
        },
        {
            "id": "030889300138934417315591123456",
            "batch": {
                "id": 10,
                "label": "Lottery winner"
            },
            "to": "123456",
            "from": "Beepsend",
            "errors": null
        },
        {
            "id": "0310373001389344173155911234567",
            "batch": {
                "id": 10,
                "label": "Lottery winner"
            },
            "to": "1234567",
            "from": "Beepsend",
            "errors": null
        }
    ]
    

    Response for message sent to groups:

    Key Type Description
    batch array | null Object with id and label. null if neither batch_label nor batch_id was supplied or the SMS got rejected.
    batch.id int Unique batch id.
    batch.label string Name of batch.
    groups string | array Ids of groups to which this message was sent
    from string Input source.
    errors null | array Null if everything went ok. Else an array of errors. See Errors.
    Status code Case
    201 All messages sent successfully.
    200 Some messages sent, check errors.
    403 All messages failed.
    ## With multiple destination addresses

    Send one message to multiple receivers.

    POST /2/sms/
    POST /2/sms/<connection id>
    POST /2/sms/<connection label>

    Request body

    To send to multiple destinations, just make to an array of addresses instead of a string.

    {
        "batch_id": 7,
        "to": [
            "12345",
            "123456",
            "1234567"
        ],
        "message": "Hello World!",
        "from": "Beepsend",
        "send_time": 1383225355,
        "encoding": "UTF-8",
        "message_type": "flash"
    }
    

    Response

    You will receive individual objects in response.

    [
        {
            "id": "07177940013893440591559112345",
            "batch": {
                "id": 7,
                "label": "My multi destination batch"
            },
            "to": "12345",
            "from": "Beepsend",
            "errors": null
        },
        {
            "id": "072644000138934405915591123456",
            "batch": {
                "id": 7,
                "label": "My multi destination batch"
            },
            "to": "123456",
            "from": "Beepsend",
            "errors": null
        },
        {
            "id": "0727961001389344059155911234567",
            "batch": {
                "id": 7,
                "label": "My multi destination batch"
            },
            "to": "1234567",
            "from": "Beepsend",
            "errors": null
        }
    ]
    
    Status code Case
    201 All messages sent successfully.
    200 Some messages sent, check errors.
    403 All messages failed.

    CURL EXAMPLE

    curl -H "Authorization: Token abc123" \
    -H "Content-Type: application/json" \
    -X POST -d '[{"batch_label": "Lottery winner", "to": "46736007518", "message": "You won!", "from": "TheLottery", "send_time": 1383225355, "encoding": "UTF-8", "message_type": "flash"}, {"batch_label": "Lottery contestants", "to": ["46736007502", "46736007505"], "message": "Better luck next time!", "from": "TheLottery", "encoding": "UTF-8"}]' \
    "https://api.beepsend.com/2/sms/"
    

    DEFINITION

    $helper->message({TO}, {FROM}, {MESSAGE}, {ENCODING}, {OPTIONS});
    $client->message->multiple({HELPER}, {CONNECTION});
    

    CODE EXAMPLE

    require_once __DIR__ . '/vendor/autoload.php';
    
    use Beepsend\Client;
    $client = new Client('abc123');
    
    $connectionId = 1;
    $helper = $client->getHelper('message');
    
    $helper->message(
        46736007518, 
        'Beepsend', 
        'You won!', 
        'UTF-8', 
        array(
            'batch_label' => 'Lottery winner',
            'message_type' => 'flash'
        )
    );
    
    $helper->message(
        array(46736007502, 46736007505), 
        'Beepboop', 
        'No win, better luck next time!', 
        'UTF-8', 
        array(
            'batch_label' => 'Lottery contestants'
        )
    );
    
    /* Send all messages */
    $client->message->multiple($helper, $connectionId)
    

    You can also set null for connection id and then the "me" alias is used to reference the default connection

    DEFINITION

    var client = new beepsend(
        {
            "api_token" : "abc123"
        }
    );
    
    client.messages().multiple({beepsend.messagesHelper}, {CONNECTION}).then({SUCCESS_FUNCTION}, {ERROR_FUNCTION});
    

    CODE EXAMPLE

    var aditionalOptions = {
        "batch_label": "Lottery winner",
        "send_time": 1383225355,
        "message_type": "flash"
    };
    
    /* Instance of messages helper */
    
    var messages = new beepsend.messagesHelper();
    messages.message('Beepsend', ["123","12345"], "Hello World 1 !!!", "UTF-8", aditionalOptions);
    messages.message('Beepsend', ["1235123", "1235123", "1235112315"], "Hello world 2 !!!");
    
    /* parameter connection is not required, you have to provide it only if you want to send messages from specific connection, otherwise system will use your default connection */
    
    client.messages().multiple(messages, connection).then(
        function(success) {
            // Write your success handler function here
        },
        function(error) {
            // Write your error handler function here
        }
    );
    

    DEFINITION

    @interface BSConnection
    
        - (NSInteger)sendMultipleSMS:(NSArray *)messages withCompletionBlock:(void(^)(NSArray *messages, NSArray *errors))block;
    
    @end
    

    CODE EXAMPLE

    BSBatch *batch = someBatch;
    
    BSMessage *sms = [BSMessage messageWithBody:@"Message body" from:@"Sender name or number" to:@"012345678900"];
    
    //For batch sending it is necessary to set parameter batch in message
    sms.batch = batch;
    
    
    [[BSConnection currentConnection] sendMultipleSMS:@[sms] withCompletionBlock:^(NSArray *messages, NSArray *errors) {
    
        if (!errors || errors.count == 0) {
    
            //Handle response (array of BSMessage objects)
    
        }
        else {
    
            //Handle error (array of BSError objects)
    
        }
    
    }];
    
    This endpoint has been deprecated. We strongly suggest that you use our current endpoint Batch HLR Lookup.

    If you POST a request with multiple msisdns the result is posted back to your connection's specified DLR Callback URL.

    POST /2/hlr/<connection id>
    Parameter Type Description
    msisdn
    Required
    string Mobile number
    connection
    Optional
    int Specify your preferred connection to use for this operation.

    Request body

    {
        "msisdn": [
            "46736007518",
            "46736007505",
            "046736007512"
        ]
    }
    

    Response

    As acknowledgement you will receive an array of objects with a unique request ID for every msisdn.

    [
        {
            "id": "08087780013866630151559112345",
            "msisdn": "46736007518",
            "errors": null
        },
        {
            "id": "08087780013866301515591123456",
            "msisdn": "46736007505",
            "errors": null
        },
        {
            "id": null,
            "msisdn": "046736007512",
            "errors": [
                {
                    "code": 1031,
                    "description": "\"msisdn\" can't have leading zeroes or pluses"
                }
            ]
        }
    ]
    
    Status code Case
    201 All HLR lookups sent successfully.
    200 Some HLR lookups sent, check errors.
    403 All HLR lookups failed.