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

Endpoint: GET /api/v1/credits/:country_code
: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

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

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-commerce & Online Shopping"
        }
    ]
}

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

Endpoint: GET /api/v1/location/:country_code/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

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

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

Endpoint: GET /api/v1/location/:country_code/:city_id/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

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

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

Endpoint: GET /api/v1/location/:country_code/:city_id/:area_id/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

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

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.

Date Object

See details at Carbon Documentation

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.

Boost your sales with SMSwords!

Start Now