SMS API Documentation

  1. Getting Started
  2. Where do I get my API Key?
  3. Do I have to use the API to send SMSs?
  4. What is the current API Version?
  5. What is the CompleteAPI.com SMS Service?
  6. SMS API Features
  7. Upcoming Features
  8. What countries are currently supported?
  9. Will more countries be supported in the future?
  10. What is a contact list?
  11. How much does it cost?
  12. Error Codes and Success Codes

1. Getting Started

1.1 Send an SMS:

To call the API, you simply open the following URL:

https://www.completeapi.com/v1/[API_KEY]/sms/[NUMBER]?message=[YOUR+URL+ENCODED+MESSAGE]

For example, to send the words "Hello World" to 2772XXXXXXX if your API KEY is 123, you would call:

https://www.completeapi.com/v1/123/sms/2772XXXXXXX?message=Hello+World

A succesfull response:

{
      "success":true,
      "creditUsed":"0.40",
      "creditRemaining":"50.10",
      "successMessage":"Success. Message successfully queued for sending.",
      "successCode":"900"
}

An unsuccesful response:

{
      "success":false,
      "creditUsed":0,
      "creditRemaining":"0.10",
      "errorMessage":"Not enough credit available. Please top up at https:\/\/www.completeapi.com\/sms",
      "errorCode":"804"
}

1.2 Send an SMS at a specific time:

It is also possible to schedule the SMS for a specific time by including a timestamp. For example, if you want the SMS to be sent on 3 May 2020, you could use the timestamp "1588464000" like this:

https://www.completeapi.com/v1/[API_KEY]/sms/[NUMBER]?sendAt=1588464000&message=Hello+World

1.3 Create a Contact List:

You can create a list by calling:

https://www.completeapi.com/v1/[API_KEY]/sms/contactLists/create/[NAME]

Sample response:

{
    api: "CompleteAPI.com Version 1.0",
    success: true,
    list_id: "80c871f259"
}

1.4 Get a list of al your contact lists

You can get a list of Contact Lists by calling:

https://www.completeapi.com/v1/[API_KEY]/sms/contactLists/get

Sample response:

{
  api: "CompleteAPI.com Version 1.0",
  success: true,
  listCount: 3,
  lists: 
  [
    {
      id: "c27a6129a9",
      created: "2018-08-31T08:42:35+00:00",
      name: "Swakopmund Branch"
    },
    {
      id: "08be58b0f6",
      created: "2018-08-31T08:45:04+00:00",
      name: "Windhoek Branch"
    },
    {
      id: "80c871f259",
      created: "2018-08-31T08:47:35+00:00",
      name: "Walvis Bay Branch"
    }
  ]
}

2. Where do I get my API Key?

Grab it here.

3. Do I have to use the API to send SMSs?

Certainly not! We have created an online user interface which you can access here. If the API is too technical for you, then we recommend this route. It is also useful for things the api does not provide for, such as sending to large lists of contacts or viewing SMS logs. The API should technically only be used if you want to integrate it with an application.

4. What is the current API Version?

Current version is: Version 1.0.

The SMS API used to run as an integrated solution with Namhost.com. It has now been combined with various other APIs to form "CompleteAPI.com". As a result, we have decided to go with version 1, as this is the first version of the brand new combined CompleteAPI.com solution. (Latest new and information on Version 2 will be posted here)

5. What is the CompleteAPI.com SMS Service?

Our SMS Service offers you a way to send SMSs to single or multiple users. This can be done online via the provided user interface, or alternatively, programatically using the SMS API. The SMS API allows you to build SMS capabilities into just about any application, while the Online User Interface makes it easy for you to review sent messages and also manage contact lists.

6. SMS API Features

The full list of features currently include:

  • API: Send a SMS to a single recipient (Namibia and South Africa only)
  • UI: Send a SMS to a single recipient (Namibia and South Africa only)
  • UI: Create Contact Lists
  • UI: Send a SMS to a Contact List (send to multiple recipients)

7. Upcoming Features

We are constantly improving on our API solution and frontend user interface and hope to add more features as we get more feature requests. Currently the following is planned for version 1.1.

  • Short Codes: Do you want to include a name per sms and write "Dear John Smith" instead of "Dear Client"? Short codes will solve that problem!
  • International Number Support: Currently we only support Namibia and South African cellphone numbers. We hope to add another 204 countries to that list.

8. What countries are currently supported?

We currently only supports Namibia +264 numbers and South African +27 numbers.

9. Will more countries be supported in the future?

We have already taken the first steps to allow the API to support sending to countries other than South Africa or Namibia. We hope that we will release support for many other countries throughout the duration of 2018.

10. What is a contact list?

Our User Interface allows you to send SMSs to either a single contact number, or a "Contact List". A "Contact List" is a list of numbers. For example, if you need to regularly send updates to a group of numbers, you can simply create a new Contact List with all of those numbers on it. Then, when sending an SMS, you can select this Contact List and the SMS will be sent to all the numbers on the list.

11. How much does it cost?

For those who used the old system, the first thing you probably noticed is that the SMS Service no longer works with with SMS credits. Previously 1 SMS Credit = 1 SMS. With the new system, you load cash onto your account, which is then used when you send an SMS.

The reason for this change is due to how costs can vary depending on different situations. For example, you will still only pay R 0.40 to send an SMS to anyone in South Africa. You will also still only pay R 0.40 if you send a SMS to someone in Namibia, but only if that person is on the MTC Network. If that person is on any other network, it will cost R 0.80.

The introduction of this type of billing sets the path for what is likely to be added to the API in the next few months. We hope to add world-wide SMS capabilities. This means you will be able to send an SMS to anyone in the world and not just Namibian and South Africa cellphone numbers. The problem with this is that network rates vary greatly from country to country. The most affordable country is Montserrat, which costs less than R 0.05, whereas Azerbaijan is the most expensive, costing almost R 5.00 per SMS. These difference in prices means we can no longer have a fixed price per credit and so we had to switch to this new method of loading cash onto your account.

The upside to this is that we have more control over pricing between different routes. Over time we hope to utilize these price differences to make it even more affordable to you.

12. Error Codes and Success Codes

Error Code Error Message
800 Invalid phone number prefix used.
801 No message provided.
802 The message is more than 160 characters long. Only messages of up to 160 characters can be sent.
803 Unable to retrieve credit details.
804 Not enough credit available. Please top up at https://www.completeapi.com/sms
805 Invalid timestamp specified.
900 Success. Message successfully queued for sending.
Copyright © Namhost Internet Services (Pty) Ltd | Privacy Policy | Terms of Use