Developers

All the returned 'Response Parameter' will be enclosed in an array with an associated key data.

A meta array may be returned with requests as well.

The API Token field is mandatory for all the API requests as a GET Parameter.

List Credits

Endpoint: GET /api/v1/credits

Show a list of your credits.

Request Parameters

Name	Type	Description	Default
api_token	string	Your account's API Token.	Mandatory

Example

curl "https://www.smswords.net/api/v1/credits?api_token=YOUR_API_TOKEN"

Response Parameters

An array of your credits (credit objects) will be returned. Each item of the array will contain the following field:

Name	Type	Description
country	A Country Object	The country for that credits record.
credits	int	The credits for the country.

Example

{
    "data": [
        {
            "credits": 64015,
            "country": {
                "code": "GB",
                "name": "United Kingdom",
                "default_timezone": "Europe\/London",
                "has_cities": true,
                "has_areas": true,
                "has_district": true
            }
        }
    ],
    "meta": {
        "pagination": {
            "total": 1,
            "count": 1,
            "per_page": 1,
            "current_page": 1,
            "total_pages": 1,
            "links": {
                "next": null,
                "previous": null
            }
        }
    }
}

Show Credit

:country_code is a country code.

Show the credit information for a single country.

Request Parameters

Name	Type	Description	Default
api_token	string	Your account's API Token.	Mandatory

Example

Response Parameters

A single credit object. Each object has the following fields:

Name	Type	Description
country	A Country Object	The country for that credits record.
credits	int	The credits for the country.

Example

{
    "data": {
        "credits": 64015,
        "country": {
            "code": "GB",
            "name": "United Kingdom",
            "default_timezone": "Europe\/London",
            "has_cities": true,
            "has_areas": true,
            "has_district": true
        }
    }
}

List Business Categories

Endpoint: GET /api/v1/industries

Show a list of the business categories.

Request Parameters

Name	Type	Description	Default
api_token	string	Your account's API Token.	Mandatory

Example

curl "https://www.smswords.net/api/v1/industries?api_token=YOUR_API_TOKEN"

Response Parameters

No Pagination will be used on this request. All the business categories will be returned in a single response.

An array of business category objects will be returned.

Example

{
    "data": [
        {
            "id": 1,
            "name": "Automotive"
        },
        {
            "id": 2,
            "name": "Consumer Electronics"
        },
        {
            "id": 3,
            "name": "E-Business & E-Commerce"
        }
    ]
}

List Countries

Endpoint: GET /api/v1/location/countries

Show a list of the countries.

Request Parameters

Name	Type	Description	Default
api_token	string	Your account's API Token.	Mandatory

Example

curl "https://www.smswords.net/api/v1/location/countries?api_token=YOUR_API_TOKEN"

Response Parameters

No Pagination will be used on this request. All the countries will be returned in a single response.

An array of country objects will be returned.

Example

{
    "data": [
        {
            "code": "GB",
            "name": "United Kingdom",
            "default_timezone": "Europe\/London",
            "has_cities": true,
            "has_areas": true,
            "has_district": true
        },
        {
            "code": "TR",
            "name": "Turkey",
            "default_timezone": "Europe\/Istanbul",
            "has_cities": true,
            "has_areas": true,
            "has_district": true
        }
    ]
}

List Cities

:country_code is a country code.

Show a list of the cities for a selected country.

Request Parameters

Name	Type	Description	Default
api_token	string	Your account's API Token.	Mandatory
name	string\|null	You can use this field to filter cities by name.	`null`

Example

Response Parameters

An array of city objects will be returned.

Example

{
    "data": [
        {
            "id": 129,
            "name": "aberdeen",
            "country_code": "GB"
        },
        {
            "id": 130,
            "name": "aberdeenshire",
            "country_code": "GB"
        },
        {
            "id": 131,
            "name": "angus",
            "country_code": "GB"
        },
        {
            "id": 132,
            "name": "argyll and bute",
            "country_code": "GB"
        },
        {
            "id": 82,
            "name": "bedfordshire",
            "country_code": "GB"
        },
        {
            "id": 183,
            "name": "belfast",
            "country_code": "GB"
        },
        {
            "id": 83,
            "name": "berkshire",
            "country_code": "GB"
        },
        {
            "id": 161,
            "name": "blaenau gwent",
            "country_code": "GB"
        },
        {
            "id": 162,
            "name": "bridgend",
            "country_code": "GB"
        },
        {
            "id": 84,
            "name": "bristol",
            "country_code": "GB"
        },
        {
            "id": 85,
            "name": "buckinghamshire",
            "country_code": "GB"
        },
        {
            "id": 163,
            "name": "caerphilly",
            "country_code": "GB"
        },
        {
            "id": 86,
            "name": "cambridgeshire",
            "country_code": "GB"
        },
        {
            "id": 164,
            "name": "cardiff",
            "country_code": "GB"
        },
        {
            "id": 165,
            "name": "carmarthenshire",
            "country_code": "GB"
        }
    ],
    "meta": {
        "pagination": {
            "total": 113,
            "count": 15,
            "per_page": 15,
            "current_page": 1,
            "total_pages": 8,
            "links": {
                "next": "https:\/\/smswords.net\/api\/v1\/location\/GB\/cities?api_token=YOUR_API_TOKEN&page=2",
                "previous": null
            }
        }
    }
}

List Areas

:country_code is the country code.
:city_id the the city ID.

Show a list of the areas for a selected city.

Request Parameters

Name	Type	Description	Default
api_token	string	Your account's API Token.	Mandatory
name	string\|null	You can use this field to filter areas by name.	`null`

Example

Response Parameters

An array of area objects will be returned.

Example

{
    "data": [
        {
            "id": 2063,
            "name": "bridge of don"
        },
        {
            "id": 2064,
            "name": "bucksburn"
        },
        {
            "id": 2065,
            "name": "cults"
        },
        {
            "id": 2066,
            "name": "dyce"
        },
        {
            "id": 2067,
            "name": "kingswells"
        },
        {
            "id": 2068,
            "name": "milltimber"
        },
        {
            "id": 2069,
            "name": "newmachar"
        },
        {
            "id": 2070,
            "name": "peterculter"
        },
        {
            "id": 2071,
            "name": "portlethen"
        }
    ],
    "meta": {
        "pagination": {
            "total": 9,
            "count": 9,
            "per_page": 15,
            "current_page": 1,
            "total_pages": 1,
            "links": {
                "next": null,
                "previous": null
            }
        }
    }
}

List Districts

:country_code is the country code.
:city_id the the city ID.
:area_id the the area ID.

Show a list of the areas for a selected city.

Request Parameters

Name	Type	Description	Default
api_token	string	Your account's API Token.	Mandatory
name	string\|null	You can use this field to filter districts by name.	`null`

Example

Response Parameters

An array of district objects will be returned.

Example

{
    "data": [
        {
            "id": 7,
            "name": "bal\u0131k\u00e7\u0131 adas\u0131"
        },
        {
            "id": 2,
            "name": "burgazadas\u0131 mah."
        },
        {
            "id": 3,
            "name": "b\u00fcy\u00fckada maden mah."
        },
        {
            "id": 4,
            "name": "b\u00fcy\u00fckada nizam mah."
        },
        {
            "id": 5,
            "name": "heybeliada mah."
        },
        {
            "id": 1,
            "name": "ka\u015f\u0131kadas\u0131"
        },
        {
            "id": 6,
            "name": "k\u0131nal\u0131ada mah."
        },
        {
            "id": 8,
            "name": "sivri ada"
        },
        {
            "id": 9,
            "name": "yass\u0131ada"
        }
    ],
    "meta": {
        "pagination": {
            "total": 9,
            "count": 9,
            "per_page": 15,
            "current_page": 1,
            "total_pages": 1,
            "links": {
                "next": null,
                "previous": null
            }
        }
    }
}

List & Filter Campaigns

Endpoint: GET /api/v1/campaigns

Show & filter your campaigns.

Request Parameters

Name	Type	Description	Default
api_token	string	Your account's API Token.	Mandatory
country_code	string	The ISO 3166-1 alpha-2 Country Code.	`null`
city_id	int	The city ID.	`null`
area_id	int	The area ID.	`null`
district_id	int	The district ID.	`null`
sender_id	int	The ID of the Sender ID.	`null`
industry_id	int	The business category ID.	`null`
name	string	The campaign name.	`null`
created_at	string: `today` `yesterday` `last_seven_days` `last_thirty_days` `this_month` `last_month` `this_year` `last_year` `all_time` `custom_date`	Filter by campaign creation date.	`all_time`
rating	string: `non_rateable` `success` `failure` `pending` `all`	The campaign rating status.	`all`
reference	string	Filter using your reference number.	`null`

Example

curl "https://www.smswords.net/api/v1/campaigns?api_token=YOUR_API_TOKEN"

Response Parameters

A campaign object will be returned. Each object contains the following fields:

Name	Type	Description
id	int	The campaign ID which may be used in other requests.
start_immediately	boolean	`true` if the campaign start mode was set to immediate.
volume	int	The volume for a single campaign instance.
message	string	The message body of the campaign.
cost	int	The total cost of the campaign instances.
status	string	The status of the campaign, can be one of the following: `new` `text_processed` `pending_approval` `pending_runtime` `numbers_assigned` `texts_sent` `completed` `cancelled`
recurring	string	The recurring mode of the campaign. Can be one of the following: `weekly` `monthly` `none`
include_user_number	boolean	Whether or not the campaign message is going to be sent to your mobile number.
reference	string	Your custom set reference number.
country	Country Object	The campaign's Country.
sender	Sender Object	The campaign's Sender ID.
city	null\|City Object	The campaign's City.
area	null\|Area Object	The campaign's Area.
district	null\|District Object	The campaign's District.
industry	Business Category Object	The campaign's business category.
instances	Campaign Instance Object	Details Below.

For each campaign, instances key will be associated with an array of campaign instance objects, each one has the following attributes:

Name	Type	Description
id	int	The id of the campaign instance.
name	string	The name of the campaign instance.
date	Carbon Date Object	The date at which the campaign instance should start.
report	A Campaign Instance Report Object	The mobile number reports for this campaign instance.

The Sender ID object has the following attributes:

Name	Type	Description
id	int	The ID of your Sender ID. Will be used on other requests.
title	string	Your alphanumeric Sender ID.

The Campaign Instance Report object has the following attributes:

Name	Type	Description
sent	int	The number of sent SMS Ads.
delivered	int	The number of delivered SMS Ads.
undelivered	int	The number of undelivered SMS Ads.
pending	int	The number of pending SMS Ads.
refunded	int	The number of undelivered SMS Ads that were refunded to your credits.

Example

{
    "data": [
        {
            "id": 36,
            "fta_id": [
                1,
                2,
                3
            ],
            "name": "2017 First Load",
            "start_immediately": true,
            "instances": [
                {
                    "id": 36,
                    "name": "2017 First Load",
                    "date": {
                        "date": "2017-01-14 12:24:22.000000",
                        "timezone_type": 3,
                        "timezone": "Europe\/London"
                    },
                    "report": {
                        "sent": 10000,
                        "delivered": 4996,
                        "undelivered": 5004,
                        "pending": 0,
                        "refunded": 5004
                    }
                }
            ],
            "volume": 10000,
            "message": "Check out the new candies of the new year.\nYou will love it.\nwww.popsugar.co.uk",
            "cost": 10000,
            "status": "completed",
            "recurring": "none",
            "include_user_number": false,
            "reference": null,
            "sender": {
                "data": {
                    "id": 10,
                    "title": "Popsugar"
                }
            },
            "country": {
                "data": {
                    "code": "GB",
                    "name": "United Kingdom",
                    "default_timezone": "Europe\/London",
                    "has_cities": true,
                    "has_areas": true,
                    "has_district": true
                }
            },
            "city": {
                "data": {
                    "id": 106,
                    "name": "london",
                    "country_code": "GB"
                }
            },
            "area": {
                "data": null
            },
            "district": {
                "data": null
            },
            "industry": {
                "data": {
                    "id": 7,
                    "name": "Food & Drink"
                }
            }
        }
    ],
    "meta": {
        "pagination": {
            "total": 10,
            "count": 10,
            "per_page": 15,
            "current_page": 1,
            "total_pages": 1,
            "links": {
                "next": null,
                "previous": null
            }
        }
    }
}

user/api.show_campaign

Endpoint: GET /api/v1/campaigns/:campaign_id
:campaign_id is your campaign ID.

Show details for a single campaigns.

Request Parameters

Name	Type	Description	Default
api_token	string	Your account's API Token.	Mandatory

Response Parameters

A campaign object will be returned.

user/api.calculate_campaign_cost

Endpoint: POST /api/v1/campaigns/calculate-cost

Used to calculate a campaign's cost without actually creating it.

Example

curl -X POST -H "Content-Type: application/json" -d '{
	"target_mode": "location",
	"country_code": "DE",
	"city_id": 191,
	"industry_id": 5,
	"recurring": "monthly",
	"date_from": "2017-03-01",
	"date_to": "2017-05-01",
	"time": "10:00",
	"original_name": "API test campaign",
	"volume": 1000,
	"sender_id": 12,
	"message": "API test message",
	"reference": "fbec7d54112232a38948123cc890257"
}' "https://www.smswords.net/api/v1/campaigns/calculate-cost?api_token=YOUR_API_TOKEN"

Request Parameters

The same as Create Campaign Parameters.

Response Parameters

Name	Type	Description
cost	int	The total campaign cost.

Example

{
    "data": {
        "cost": 3000
    }
}

Create Campaign

Endpoint: POST /api/v1/campaigns

Request Parameters

Name	Type	Description	Default
api_token	string	Your account's API Token.	Mandatory
target_mode	string: `location` `fta`	Either the campaign will be created using an FTA campaign, or by specifying location	Mandatory
country_code	string	The ISO 3166-1 alpha-2 Country Code.	Mandatory if `target_mode` is location.
city_id	int	The City ID.	`null`
area_id	int	The Area ID.	`null`
district_id	int	The District ID.	`null`
fta_id	array\|null	The FTA Campaign IDs.	Mandatory if `target_mode` is fta.
industry_id	int	The Business Category ID.	Mandatory
immediate	boolean	Whether or not to start campaign immediately.	`false`
recurring	string: `none` `weekly` `monthly`	The Campaign Recurring Mode.	Mandatory if `immediate` is `false`, `null` otherwise.
date	string (Y-m-d Date Format)	The date when the campaign should run.	Mandatory if `recurring` is `none`
date_from	string (Y-m-d Date Format)	The date when the campaign recurring starts.	Mandatory if `recurring` is not `none`
date_to	string (Y-m-d Date Format)	The date when the campaign recurring ends.	Mandatory if `recurring` is not `none`
time	string (H:i Date Format)	The time when the campaign recurring runs.	Mandatory
original_name	string	The Campaign's Name.	Mandatory
volume	int	The Campaign's volume.	Mandatory
sender_id	int	The Sender ID.	Mandatory
message	string	The Campaign Message.	Mandatory
reference	string	The Campaign Customer Reference Number. An unique number to identify each of your customers. This is specially useful if you plan to use our API in your SMS mobile advertising website	Mandatory

Example

curl -X POST -H "Content-Type: application/json" -d '{
	"target_mode": "location",
	"country_code": "DE",
	"city_id": 191,
	"industry_id": 5,
	"recurring": "monthly",
	"date_from": "2017-03-01",
	"date_to": "2017-05-01",
	"time": "10:00",
	"original_name": "API test campaign",
	"volume": 1000,
	"sender_id": 12,
	"message": "API test message",
	"reference": "fbec7d54112232a38948123cc890257"
}' "https://www.smswords.net/api/v1/campaigns?api_token=YOUR_API_TOKEN"

Request Parameters

A campaign object on success.

Example

{
    "data": {
        "id": 68,
        "fta_id": [
            1,
            2,
            3
        ],
        "name": "API test campaign (21)",
        "start_immediately": false,
        "instances": [
            {
                "id": 68,
                "name": "API test campaign (21) - 01.Mar.2017",
                "date": {
                    "date": "2017-03-01 06:00:00.000000",
                    "timezone_type": 3,
                    "timezone": "Europe\/Berlin"
                },
                "report": {
                    "sent": 0,
                    "delivered": 0,
                    "undelivered": 0,
                    "pending": 0,
                    "refunded": 0
                }
            },
            {
                "id": 69,
                "name": "API test campaign (21) - 01.Apr.2017",
                "date": {
                    "date": "2017-04-01 08:00:00.000000",
                    "timezone_type": 3,
                    "timezone": "Europe\/Berlin"
                },
                "report": {
                    "sent": 0,
                    "delivered": 0,
                    "undelivered": 0,
                    "pending": 0,
                    "refunded": 0
                }
            },
            {
                "id": 70,
                "name": "API test campaign (21) - 01.May.2017",
                "date": {
                    "date": "2017-05-01 08:00:00.000000",
                    "timezone_type": 3,
                    "timezone": "Europe\/Berlin"
                },
                "report": {
                    "sent": 0,
                    "delivered": 0,
                    "undelivered": 0,
                    "pending": 0,
                    "refunded": 0
                }
            }
        ],
        "volume": 1000,
        "message": "API test message",
        "cost": 3000,
        "status": "new",
        "recurring": "monthly",
        "include_user_number": false,
        "reference": null,
        "sender": {
            "data": {
                "id": 12,
                "title": "Testing"
            }
        },
        "country": {
            "data": {
                "code": "DE",
                "name": "Germany",
                "default_timezone": "Europe\/Berlin",
                "has_cities": true,
                "has_areas": true,
                "has_district": true
            }
        },
        "city": {
            "data": {
                "id": 191,
                "name": "baden-w\u00fcrttemberg",
                "country_code": "DE"
            }
        },
        "area": {
            "data": null
        },
        "district": {
            "data": null
        },
        "industry": {
            "data": {
                "id": 5,
                "name": "Entertainment"
            }
        }
    }
}

Country Object

Whenever a country object is returned from any request, it will have the following fields

Name	Type	Description
code	string	The ISO 3166-1 alpha-2 Country Code.
name	string	The name of the country.
default_timezone	string	The Default (Capital City) Timezone for the country.
has_cities	boolean	Whether the county has associated cities or not. If set to `false` you may not request the country cities, or use a city while creating a campaign for this country.
has_areas	boolean	Whether the county has associated areas or not. If set to `false` you may not request the areas for any city in the country, or use an area while creating a campaign for this country.
has_districts	boolean	Whether the county has associated districts or not. If set to `false` you may not request the districts for any area in the country, or use a district while creating a campaign for this country.

City Object

Whenever a city object is returned from any request, it will have the following fields:

Name	Type	Description
id	int	The city ID which will be required on other requests.
name	string	The name of the city.
country_code	string	The ISO 3166-1 alpha-2 Country Code.

Area Object

Whenever an area object is returned from any request, it will have the following fields:

Name	Type	Description
id	int	The area ID which will be required on other requests.
name	string	The name of the area.
city_id	int	The associated city ID.

District Object

Whenever a district object is returned from any request, it will have the following fields:

Name	Type	Description
id	int	The district ID which will be required on other requests.
name	string	The name of the district.
area_id	int	The associated area ID.

Business Category Object

Whenever an business category object is returned from any request, it will have the following fields:

Name	Type	Description
id	int	The business category id.
name	string	The business category name.

Error Response

If anything is wrong with your request, the response will be a simple errors object.

The error object has the errors key and contain the following fields:

Name	Type	Description
message	string	The error explained.

Pagination

If your request is for a list of objects, like listing campaigns, countries, cities, business categories, credits... etc, a pagination object will be added to the meta object.

The pagination object has the pagination key and contain the following fields:

Name	Type	Description
total	int	The total number of items/objects.
count	int	The number of items/objects on this page.
per_page	int	The number of items/objects requested per page.
current_page	int	The current page number.
total_pages	int	The total number of pages.
links	Links Object	An object containing links for navigation.

The links object has the links key and contain the following fields:

Name	Type	Description
next	string\|null	The link to the next page.
previous	string\|null	The link to the previous page.

Developers

List Credits

Request Parameters

Example

Response Parameters

Example

Show Credit

Request Parameters

Example

Response Parameters

Example

List Business Categories

Request Parameters

Example

Response Parameters

Example

List Countries

Request Parameters

Example

Response Parameters

Example

List Cities

Request Parameters

Example

Response Parameters

Example

List Areas

Request Parameters

Example

Response Parameters

Example

List Districts

Request Parameters

Example

Response Parameters

Example

List & Filter Campaigns

Request Parameters

Example

Response Parameters

Example

user/api.show_campaign

Request Parameters

Response Parameters

user/api.calculate_campaign_cost

Example

Request Parameters

Response Parameters

Example

Create Campaign

Request Parameters

Example

Request Parameters

Example

Country Object

City Object

Area Object

District Object

Business Category Object

Date Object

Error Response

Pagination

Boost your sales with SMSwords!