SMS API

Lefoka makes sending and receiving SMS messages easy.

API Reference

The Lefoka SMS API uses a RESTful approach, accepts form-encoded requests, returns JSON responses that incorporate HATEOAS principles, uses standard HTTP codes, and requires authentication for secure access.

The Lefoka SMS API offers a test/sandbox mode that does not affect your live data. Authentication is required for both test mode and live mode requests.

The Lefoka SMS API enables interaction with your customers through SMS messages, supporting both one-way and two-way communication. By making HTTPS calls directly to the API, you can easy send single or multiple SMS messages. Additionally, you have the option to set up webhooks to allow for two-way messaging integration through webhooks.

Be sure to have a look at our , and to get examples and inspiration of how people are integrating SMS messaging into their businesses and applications, quick and easy!

At any point during your integration we are here to help you through our live chat.

Was this section helpful?

LIVE BASE URL

https://api.lefoka.co.za

SANDBOX BASE URL

https://sandbox.lefoka.co.za

Authentication

The Lefoka SMS API uses API keys to authenticate requests. You can view and manage your API Keys in the Lefoka Account.

Keep your API keys secure as they carry important privileges. Avoid sharing your API keys in public platforms like GitHub or client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth.. Provide your API key as the basic auth username value and leave the password blank.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API request without Authentication will also fail.

Was this section helpful?

EXAMPLE OF AN AUTHENTICATED REQUEST

curl https://api.lefoka.co.za/v1/messages/balance \
-u pk_89d6a0e39886f68518c54086a68912cfe38efdd6d92774284d1d45a229e73

Errors

The Lefoka SMS API uses standard HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate errors related to the provided information (e.g., a required parameter missing, a incorrect value format, etc.). Codes in the 5xx range indicate an error with Lefoka's servers (these are rare).

All 4xx errors return an error type, a helpful message and a URL to the documentation to expore the correct method of apporoach. The full breakdown of the errors can be found in the error responses section.

Was this section helpful?

Attributes

message STRING

Error message name, can be sent to us when assistance is required.

description STRING

Human friendly description of the error message.

documentation_url STRING

A URL you can visit to find out what could have went wrong in the implementation.

HTTP STATUS CODE SUMMARY

200 - OK

201 - Created

400 - Bad Request

401 - Unauthorized

402 - Request Failed

403 - Forbidden

404 - Not Found

405 - Method Not Allowed

429 - Too Many Requests

500, 502, 503, 504 - Server Errors

Everything worked as expected.

Everything worked as expected.

The request was unacceptable,
often due to missing a required
parameter.

No valid API key provided.

The parameters were valid but
the request failed.

The API key doesn't have
permissions to perform the
request.

The requested resource doesn't
exist.

The HTTP request method is
not allowed.

Too many requests hit the API
too quickly. We recommend an
exponential backoff of your
requests.

Something went wrong on
Lefoka's end. (These are rare.)

EXAMPLE ERROR RESPONSE OBJECT

{
  "error": {
    "message": UNAUTHORIZED,
    "description": "No autentication method is provided.",
    "documentation_url": "https://developer.lefoka.co.za/docs/sms/reference#authentication"
  }
}

Versioning and Changelog

The Lefoka SMS API is still in it's earliest version. The current version is 0.0.1 dated 2024-01-02. For all API updates, view our API changelog. We try our best not to introduce new version, or introduce breaking changes.

Was this section helpful?

Balance

This is an object representing your Lefoka SMS credits. You can retrieve it to see the current balance or you can view it directly in your Lefoka Account.

Was this section helpful?

ENDPOINT

GET /v1/messages/balance

The balance object

Attributes

balance INTEGER

Balance amount.

documentation_url STRING

Documentation helper URL to the endpoint for a quick reference.

HATEOAS links

None.

THE BALANCE OBJECT

{
  "balance": 44,
  "documentation_url": "https://developer.lefoka.co.za/docs/sms/reference#balance"
}

Retrieve the balance

Retrieves the balance, based on the authentication that was used to make the request.

Parameters

No parameters.

Returns

Returns a balance object for the account that was authenticated in the request.

GET /v1/messages/balance

curl https://api.lefoka.co.za/v1/messages/balance \
-u pk_89d6a0e39886f68518c54086a68912cfe38efdd6d92774284d1d45a229e73

RESPONSE

{
  "balance": 44,
  "documentation_url": "https://developer.lefoka.co.za/docs/sms/reference#balance"
}

SMS Delivery Statuses

Below are all the available delivery statuses, as well what the status means.

delivered status means the SMS was successfully submitted to the recipient's number.

undelivered status means the SMS was not successfully delivered to the recipient's number due to inactive or unreachable numbers.

expired status means no status update were received within the validity period due to the recipent's mobile device either being powered off, redirected to another number or is currently out of network coverage.

blist status means the SMS delivery to the specified number is restricted due to a request by the owner or WASPA (Wireless Application Service Providers' Association).

submitted status means the SMS has been handed over to the recipient's cellular network to be delivered and we are waiting for a status update from the recipent's cellular network.

noroute status means no route being available for the number.

failed status means the scheduled SMS failed due to insufficient SMS credits.

Was this section helpful?

Send SMS

Send SMS message immediately. Currently the API only supports sending messages to all South African mobile numbers.

Lefoka SMS API has the ability to send bulk SMS. If you wish to send in batch, you can add more than one number in the recipient array. There is a limit of 500 numbers for a single request. Make sure that the number is correctly formatted, if not correctly formatted the gateway will reject the number and you will be charged.

To enforce security and legitimacy, when you send or schedule your SMS make sure sign your request by including the SHA-256 Signature Header. See how to generate a signature for more information.

Lefoka SMS API has the ability to perform an HTTP Post to a URL of your choice, useful to listen for events related to your SMS message, see webhook.

Was this section helpful?

ENDPOINT

POST /v1/messages

The SMS object

Attributes

id STRING

The message ID. Can be used to query the API.

type STRING

The message type.

recipient ARRAY

An array of recipient mobile numbers.

schedule STRING

The time the message is schedule for in ISO 8601 format.

client_reference STRING

A custom string variable which can be used as pass-through variable.

status STRING

The message status. Available statuses are delivered undelivered expired blist submitted submitted noroute and failed. See delivery statuses for a description of each status.

credit INTEGER

The number of SMS credits used.

creation_date STRING

The time the message was crated at in ISO 8601 format.

documentation_url STRING

Documentation helper URL to the endpoint for a quick reference.

HATEOAS links

_links ARRAY

A list of available possible endpoints you can send requests. Authentication is still required.

_links.self ARRAY

The self identifier for the request.

_links.self.href STRING

The URL you can follow to get the message object.

list.self.method STRING

The HTTP method you need to use.

_links.edit ARRAY

The edit identifier for the request. Only scheduled SMS message can be edited or modified.

_links.edit.href STRING

The URL you can follow to edit or modify the message object. See edit scheduled SMS for more information.

list.edit.method STRING

The HTTP method you need to use.

_links.delete ARRAY

The delete identifier for the request. Only scheduled SMS message can be deleted.

_links.delete.href STRING

The URL you can follow to delete the message object. See delete scheduled SMS for more information.

list.delete.method STRING

The HTTP method you need to use.

THE IMMEDIATE SEND MESSAGE OBJECT

{
  "id": "f8cf92ceff5a5646c0eb53a0736ba1776286bb77430f65e0390af37fd5324cdd",
  "type": "sms",
  "recipient": [
    "27637885448",
    "27800055555"
  ],
  "message": "test",
  "client_reference": "your reference",
  "schedule": null,
  "status": "pending",
  "credit": 2,
  "creation_date": "2023-06-25T08:55:23+02:00",
  "_links": {
    "self": {
      "href": "https://api.lefoka.co.za/v1/messages/f8cf92ceff5a5646c0eb53a0736ba1776286bb77430f65e0390af37fd5324cdd",
      "method": "GET"
    }
  },
  "documentation_url": "https://developer.lefoka.co.za/docs/sms/reference#send"
}

THE SCHEDULED MESSAGE OBJECT

{
  "id": "c31dd77c7337cbe074660af10488a02b49a84e0288d67d8366f1c760c9338c7a",
  "type": "sms",
  "recipient": [
    "27637885448",
    "27800055555"
  ],
  "message": "test",
  "schedule": "2023-06-27T04:41:08+02:00",
  "client_reference": "your reference",
  "status": "scheduled",
  "credit": 0,
  "creation_date": "2023-06-25T08:55:23+02:00",
  "_links": {
    "self": {
      "href": "https://api.lefoka.co.za/v1/messages/f8cf92ceff5a5646c0eb53a0736ba1776286bb77430f65e0390af37fd5324cdd",
      "method": "GET"
    },
    "edit": {
      "href": "https://api.lefoka.co.za/v1/messages/f8cf92ceff5a5646c0eb53a0736ba1776286bb77430f65e0390af37fd5324cdd",
      "method": "PATCH"
    },
    "delete": {
      "href": "https://api.lefoka.co.za/v1/messages/f8cf92ceff5a5646c0eb53a0736ba1776286bb77430f65e0390af37fd5324cdd",
      "method": "DELETE"
    }
  },
  "documentation_url": "https://developer.lefoka.co.za/docs/sms/reference#send"
}

Send the SMS immediately

SMS messages can be sent out immediately or scheduled, to immediately send out the message leave out the schedule parameter on your request. See Schedule SMS if you wish to schedule your SMS messages.

Parameters

recipient ARRAY REQUIRED

An array of recipients mobile numbers (MSISDN). Limited to 500 mobile numbers per single request.

message STRING REQUIRED

This is the text of the message you want to send. Limited to 440 characters.

client_reference OPTIONAL

A custom string variable which can be used as pass-through variable. This will be posted back to the supplied webhook URL. Limited to 100 characters.

Headers

Signature STRING REQUIRED

A generated SHA-256 signature hash string of the request. Learn how to generate the signature or use our sandbox sigature generator.

Returns

Returns the message object if successful. This call returns an error if something goes wrong. A common source of error is a signature mismatch, or invalid phone number(s), or insufficient avaliable balance.

POST /v1/message

curl 'https://api.lefoka.co.za/v1/messages' \
-H 'Signature: c17bf166eb57f54fa86ca593dc713b06fab635f141218d4ce045aed7eeb3ac16' \
-H 'Content-Type: application/json' \
-u pk_89d6a0e39886f68518c54086a68912cfe38efdd6d92774284d1d45a229e73 \
-d '{
    "recipient": [
        "27637885448",
        "27800055555"
    ],
     "message": "test",
     "client_reference": "your reference"

}'

RESPONSE

{
  "id": "f8cf92ceff5a5646c0eb53a0736ba1776286bb77430f65e0390af37fd5324cdd",
  "type": "sms",
  "recipient": [
    "27637885448",
    "27800055555"
  ],
  "message": "test",
  "client_reference": "your reference",
  "schedule": null,
  "status": "pending",
  "credit": 2,
  "creation_date": "2023-06-25T08:55:23+02:00",
  "_links": {
    "self": {
      "href": "https://api.lefoka.co.za/v1/messages/f8cf92ceff5a5646c0eb53a0736ba1776286bb77430f65e0390af37fd5324cdd",
      "method": "GET"
    }
  },
  "documentation_url": "https://developer.lefoka.co.za/docs/sms/reference#send"
}

Schedule the SMS

SMS messages can be scheduled or sent out immediately, to schedule a SMS message include the schedule parameter on your request. See Send the SMS immediately if you wish to send your SMS messages immediately.

Scheduled messages are only charged when the message goes out.

Parameters

recipient ARRAY REQUIRED

An array of recipients mobile numbers (MSISDN). Limited to 500 mobile numbers per single request.

message STRING REQUIRED

This is the text of the message you want to send. Limited to 440 characters.

schedule REQUIRED

The time the message should be scheduled for in ISO 8601 format. Format YYYY-MM-DDTHH:MM[(+-)HH:MM] (e.g. 2020-04-01T12:00:01+02:00). The time zone offset group [(+-)HH:MM] is optional. If not included, the default will be assumed to be GMT +2. The current system time is 15 minutes in the future, to ensure that the message is successfully scheduled we recommend setting it to 20 or 30 minutes in the future as a safety measure. At this point messages can only be scheduled for up to 7 days in advance.

client_reference STRING OPTIONAL

A custom string variable which can be used as pass-through variable. This will be posted back to the supplied webhook URL. Limited to 100 characters.

Headers

Signature STRING REQUIRED

A generated SHA-256 signature hash string of the request. Learn how to generate the signature or use our sandbox sigature generator.

Returns

Returns the message object if successful. This call returns an error if something goes wrong. A common source of error is a signature mismatch, or invalid phone number(s).

POST /v1/message

curl 'https://api.lefoka.co.za/v1/messages' \
-H 'Signature: b6401ce40af63a0a7f98a0bd13f89090044df14c2939d59a64529d6e36a8c292' \
-H 'Content-Type: application/json' \
-u pk_89d6a0e39886f68518c54086a68912cfe38efdd6d92774284d1d45a229e73 \
-d '{
    "recipient": [
        "27637885448",
        "27800055555"
    ],
     "schedule":"2025-11-09T12:15:21+02:00",
     "message": "test",
     "client_reference": "your reference"
}'

RESPONSE

{
  "id": "c31dd77c7337cbe074660af10488a02b49a84e0288d67d8366f1c760c9338c7a",
  "type": "sms",
  "recipient": [
    "27637885448",
    "27800055555"
  ],
  "message": "test",
  "schedule": "2023-06-27T04:41:08+02:00",
  "client_reference": "your reference",
  "status": "scheduled",
  "credit": 0,
  "creation_date": "2023-06-25T08:55:23+02:00",
  "_links": {
    "self": {
      "href": "https://api.lefoka.co.za/v1/messages/f8cf92ceff5a5646c0eb53a0736ba1776286bb77430f65e0390af37fd5324cdd",
      "method": "GET"
    },
    "edit": {
      "href": "https://api.lefoka.co.za/v1/messages/f8cf92ceff5a5646c0eb53a0736ba1776286bb77430f65e0390af37fd5324cdd",
      "method": "PATCH"
    },
    "delete": {
      "href": "https://api.lefoka.co.za/v1/messages/f8cf92ceff5a5646c0eb53a0736ba1776286bb77430f65e0390af37fd5324cdd",
      "method": "DELETE"
    }
  },
  "documentation_url": "https://developer.lefoka.co.za/docs/sms/reference#send"
}

Edit scheduled SMS

Only scheduled SMS messages or SMS message with the status scheduled can be edited or modified. If the SMS status is not scheduled you can not edit or modify it.

You will not be charged for editing or modifying eligible scheduled SMS messages.

Was this section helpful?

ENDPOINT

PATCH /v1/messages/MESSAGE_ID

Edit scheduled SMS

You need the MESSAGE_ID to edit the scheduled SMS message. You can edit the recipient, the message, or schedule parameters individual or all of them at one time.

Parameters

recipient ARRAY OPTIONAL

An array of recipients mobile numbers (MSISDN). Limited to 500 mobile numbers per single request.

message STRING OPTIONAL

This is the text of the message you want to send. Limited to 440 characters.

schedule OPTIONAL

client_reference STRING OPTIONAL

A custom string variable which can be used as pass-through variable. This will be posted back to the supplied webhook URL. Limited to 100 characters.

Returns

Returns the message object if successful. This call returns an error if something goes wrong. A common source of error is a signature mismatch, or invalid phone number(s).

PATCH /v1/messages/MESSAGE_ID

curl -X PATCH 'https://api.lefoka.co.za/v1/messages/e0a939f21d88be1b4ed15bbc4a3a9a7884d92ae04aad4c9dee651dfe854e2316' \
-H 'Content-Type: application/json' \
-u pk_89d6a0e39886f68518c54086a68912cfe38efdd6d92774284d1d45a229e73 \
-d '{
    "recipient": [
        "27637885448",
        "27800055555"
    ],
     "schedule":"2025-11-09T12:15:21+02:00",
     "message": "test",
     "client_reference": "your reference"
}'

RESPONSE

{
  "id": "c31dd77c7337cbe074660af10488a02b49a84e0288d67d8366f1c760c9338c7a",
  "type": "sms",
  "recipient": [
    "27637885448",
    "27800055555"
  ],
  "message": "test",
  "schedule": "2023-06-27T04:41:08+02:00",
  "client_reference": "your reference",
  "status": "scheduled",
  "credit": 0,
  "creation_date": "2023-06-25T08:55:23+02:00",
  "_links": {
    "self": {
      "href": "https://api.lefoka.co.za/v1/messages/f8cf92ceff5a5646c0eb53a0736ba1776286bb77430f65e0390af37fd5324cdd",
      "method": "GET"
    },
    "edit": {
      "href": "https://api.lefoka.co.za/v1/messages/f8cf92ceff5a5646c0eb53a0736ba1776286bb77430f65e0390af37fd5324cdd",
      "method": "PATCH"
    },
    "delete": {
      "href": "https://api.lefoka.co.za/v1/messages/f8cf92ceff5a5646c0eb53a0736ba1776286bb77430f65e0390af37fd5324cdd",
      "method": "DELETE"
    }
  },
  "documentation_url": "https://developer.lefoka.co.za/docs/sms/reference#send"
}

Delete scheduled SMS

Only scheduled SMS messages or SMS message with the status scheduled can be deleted. If the SMS status is not scheduled you can not delete it.

You will not be charged for deleted eligible scheduled SMS messages.

Was this section helpful?

ENDPOINT

DELETE /v1/messages/MESSAGE_ID

The delete scheduled SMS object

Attributes

status STRING

When you receive success in your response, the message has been successfully deleted.

HATEOAS links

None.

THE DELETE SCHEDULED SMS OBJECT

{
  "status": "successful"
}

Delete scheduled SMS

Deletes the SMS message with the given ID.

Parameters

No parameters.

Returns

Returns a status object if a valid message ID was provided. Returns an error otherwise.

GET /v1/messages/MESSAGE_ID

curl -X DELETE 'https://api.lefoka.co.za/v1/messages/ba66c3bc1a38f99c5d20e69f7a813b45016101412a598d88ffe6728e71362ffd' \
-H 'Content-Type: application/json' \
-u pk_89d6a0e39886f68518c54086a68912cfe38efdd6d92774284d1d45a229e73

RESPONSE

{
  "status": "successful"
}

List SMS

This is an object representing a list of your SMS logs. SMS Logs can also be viewed in your Lefoka account.

Was this section helpful?

ENDPOINT

GET /v1/messages
GET /v1/messages/MESSAGE_ID

Retrieve a message

Retrieves the message log with the given ID.

Parameters

No parameters.

Returns

Returns a message object if a valid message ID was provided. Returns an error otherwise.

GET /v1/messages/MESSAGE_ID

curl https://api.lefoka.co.za/v1/messaging/sms/balance.php \
-u pk_922e41a4788edae9cd0b99a4179556b6fb094d6a45c34e952b0adf4e4be22b49

RESPONSE

{
  "id": "f8cf92ceff5a5646c0eb53a0736ba1776286bb77430f65e0390af37fd5324cdd",
  "type": "sms",
  "recipient": [
    "27637885448",
    "27800055555"
  ],
  "message": "test",
  "client_reference": "your reference",
  "schedule": null,
  "status": "pending",
  "credit": 2,
  "creation_date": "2023-06-25T08:55:23+02:00",
  "_links": {
    "self": {
      "href": "https://api.lefoka.co.za/v1/messages/f8cf92ceff5a5646c0eb53a0736ba1776286bb77430f65e0390af37fd5324cdd",
      "method": "GET"
    }
  },
  "documentation_url": "https://developer.lefoka.co.za/docs/sms/reference#send"
}

List all messages

Returns a list of SMS messages. The messages are returned in sorted order, with the most recent messages appearing first.

Parameters

recipient STRING OPTIONAL

Only return messages for this recipient. You are also able to use wildcard search, for example if you supply 12345 - it will return all messages that have the number 12345 in them like 27123456789.

status STRING OPTIONAL

Only return messages that have a given status. Available statuses are delivered undelivered expired blist submitted staged cancelled noroute and failed

search STRING OPTIONAL

Only return messages that have this given string. The filter looks only at the SMS message.

page INTEGER OPTIONAL

A cursor for use in pagination. Only return messages for the given page.

limit INTEGER OPTIONAL

Number of messages to be returned. Default is 10 and maximum is 100.

Returns

A dictionary with a list property that contains an array of message object up to limit.

GET /v1/messages

curl https://api.lefoka.co.za/v1/messaging/sms/balance.php \
-u pk_922e41a4788edae9cd0b99a4179556b6fb094d6a45c34e952b0adf4e4be22b49

RESPONSE

{
  "list": [
     {
       "id": "7ec8e34a3b11867438a44e2f04fb3d7f77478ed9a4505b53190fcc2c836bc6e9",
       "type": "sms",
       "recipient": [
          "27637885448"
       ],
       "message": "<script>test</script>",
       "schedule": null,
       "status": "delivered",
       "credit": 1,
       "creation_date": "2023-05-01T05:07:50+02:00"
       "delivery_date": "2023-05-01T05:07:50+02:00",
       "_links": {
          "self": {
            "href": "https://api.lefoka.co.za/v1/messages",
            "method": "GET"
          },
      }
     },
     {...},
     {...}
  ],
  "page": 1,
  "limit": 10,
  "total_pages": 7,
  "total_items": 65,
  "_links": {
    "self": {
      "href": "https://api.lefoka.co.za/v1/messages",
      "method": "GET"
    },
    "next": {
      "href": "https://api.lefoka.co.za/v1/messages?page=2",
      "method": "GET"
    },
    "last": {
      "href": "https://api.lefoka.co.za/v1/messages?page=7",
      "method": "GET"
    }
  },
  "documentation_url": "https://developer.lefoka.co.za/docs/sms/reference#send"
}

SMS Replies

SMS replies are automatically activated and sent to the webhook URL you added on your Lefoka account. SMS replies can also be viewed in your Lefoka account.

For more information see webhook below.

Was this section helpful?

SMS REPLY WEBHOOK PAYLOAD EXAMPLE

{
  "id": "624b3bf90fdb89d730b2de1b69f9be662f8cb917aee95478d4ec592f0c1de986",
  "type": "sms-reply",
  "recipient": [
    "27637885448",
    "27800055555"
  ],
  "message": "The reply message",
  "client_reference": "your reference",
  "schedule": null,
  "status": "delivered",
  "credit": 0,
  "creation_date": "2023-12-31T20:57:37Z",
  "delivery_date": "2023-12-31T20:57:37Z"
}

Webhook

Webhooks are used to send notification messages for events via HTTP callbacks. Lefoka SMS API uses webhooks to keep your application informed about specific events, ensuring that your servers stay updated with delivery information.

Instead of polling your application at regular intervals to check for a specific event, you can subscribe to webhook events. These events will be sent as POST requests from Lefoka, notifying you when the event occurs and providing event details. This approach gives you real-time data while minimising the number of API requests needed.

At this point you can only get notified about the SMS message delivery along with SMS replies.

You can configure your webhook URL in your Lefoka account.

On receiving the webhook payload from the Lefoka SMS API, return a header 200 to prevent further retries. If no 200 response is returned the notification will be re-sent immediately. Failed webhooks will be re-attempted 3 times.

Was this section helpful?

SMS WEBHOOK PAYLOAD EXAMPLE

{
  "id": "f8cf92ceff5a5646c0eb53a0736ba1776286bb77430f65e0390af37fd5324cdd",
  "type": "sms",
  "recipient": [
    "27637885448",
    "27800055555"
  ],
  "message": "test",
  "client_reference": "your reference",
  "schedule": null,
  "status": "pending",
  "credit": 2,
  "creation_date": "2023-06-25T08:55:23+02:00",
  "_links": {
    "self": {
      "href": "https://api.lefoka.co.za/v1/messages/f8cf92ceff5a5646c0eb53a0736ba1776286bb77430f65e0390af37fd5324cdd",
      "method": "GET"
    }
  },
  "documentation_url": "https://developer.lefoka.co.za/docs/sms/reference#send"
}

Signature generation

When it comes to security, some APIs only require an API key or username as a parameter when calling an endpoint. However, this approach carries the risk for your business and customers/clients, allowing unauthorised individuals to make their own calls.

This is why we require you to sign certain requests we deem as very sensitive, as such the Lefoka SMS API require you to sign them with your private key - since the private key is only used for signing request it make it that more secure since it does not leave your application(s).

More specifically, the signature parameter we require on all calls is the SHA256 hash of the request string.

Was this section helpful?

Generating the signature header

To generate the signature, you need to:

1. Arrange all the keys in ascending order. Use a function that arranges an arry based on the keys.
2. Concatenate the name-value pairs of non-blank variables, using ‘&’ as a separator. Make sure to URL encode the values. Transform spaces to %20 (replace '+' with %20). Example:client_reference=your%20reference&message=test&recipient=…
3. Encrypt the concatenated string using SHA-256 encryption.
4. Pass the encrypted signature into the header parameter, labelling it as Signature

Need help?

SIGNATURE GENERATION PHP

// API secret
$apiSecret = 'YOUR_API_SECRET';

$sendData = [
    'recipient'        => ['27637885448'],
    'message'          => 'test',
    'client_reference' => 'your reference'
];

// Generate signature
$encoded = [];
ksort($sendData);

foreach ($sendData as $name => $value) {
    if (is_array($value)) {
        foreach ($value as $item) {
            $encoded[] = $name.'[]='.rawurlencode($item);
        }
    } else {
        $encoded[] = $name.'='.rawurlencode($value);
    }
}

$concatenated = implode('&', $encoded); // Returns client_reference=your%20reference&message=test&recipient[]=27637885448
$signature = hash_hmac('sha256', $concatenated, $apiSecret, false);

Error Responses

Explore the full list of all possible API error responses.

Was this section helpful?

The error response object

Attributes

message STRING

Error message name, can be sent to us when assistance is required.

description STRING

Human friendly description of the error message.

documentation_url STRING

A URL you can visit to find out what could have went wrong in the implementation.

ERROR RESPONSE OBJECT

{
  "message": INVALID_RECIPIENT_ENTRY,
  "description": "One or more send to numbers provided is not valid",
  "documentation_url": "https://developer.lefoka.co.za/sms#send"
}

All possible error responses

HTTP Status codes

200 - OK

Everything worked as expected.

201 - Created

Everything worked as expected.

400 - Bad Request

The request was unacceptable, often due to missing a required parameter.

401 - Unauthorized

No valid API key provided.

402 - Request Failed

The parameters were valid but the request failed.

403 - Forbidden

The API key doesn't have permissions to perform the request.

404 - Not Found

The requested resource doesn't exist.

405 - Method Not Allowed

The HTTP request method is not allowed.

429 - Too Many Requests

Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.

503, 502, 503, 504 - Server Errors

Something went wrong on Lefoka's end. (These are rare.)

Authentication errors

CONNECTION_INSECURE

Connection insecure, ensure you are using HTTPS, for example: use https://api.lefoka.co.za/balance not http://api.lefoka.co.za/balance

UNAUTHORIZED

Requests to the API endpoints require, see authentication to find out how to authenticate your requests.

INVALID_API_KEY

The provided API Key does not exist. Common reasons are mistyping the provided API Key, old API Keys. Simple fix would be to generate new keys in authentication to find out how to authenticate your requests.

Balance errors

INVALID_HTTP_REQUEST_METHOD

Invalid HTTP request method. Ensure you set the HTTP request method to GET for the balance endpoint.

Send SMS errors

INVALID_HTTP_REQUEST_METHOD

Invalid HTTP request method. Ensure you set the correct HTTP request method for the specific endpoint. Possible HTTP request methods are GET POST PATCH and DELETE

JSON_EXCEEDED

Your request is missing a signature. When sending a SMS message, the header parameter Signature is required.

SIGNATURE_MISSING

Your request is missing a signature. When sending a SMS message, the header parameter Signature is required.

RECIPIENT_MISSING_PARAMETER

Recipent parameter is missing. Ensure you specify the recipent paramater, this is the mobile number you want to send an SMS message to.

MESSAGE_MISSING_PARAMETER

Message parameter is missing. Ensure you specify the message paramater, this is the message you want to attach to the SMS message.

RECIPIENT_EMPTY_PARAMETER

Recipent parameter is provided however the value is blank. Ensure that after you have added the recipent parameter that you also add the mobile number or numbers you want to send the SMS message to.

BATCH_LIMIT_EXCEEDED

The batch per send is limited to 100 numbers. Ensure you the number of recipent mobile number(s) does not exeed 100 mobile numbers.

MESSAGE_EMPTY_PARAMETER

Message parameter is provided however the value is blank. Ensure that after you have added the message parameter that you also add the text message you want to attach to the SMS message.

MESSAGE_LIMIT_EXCEEDED

You have exceeded the 160 characters limit for the message paramater. Ensure that your characters does not exceed the 160 character limit per SMS message.

CLIENT_REFERENCE_LIMIT_EXCEEDED

You have exceeded the 100 characters limit for the client_reference paramater. Ensure that your characters does not exceed the 100 character limit per SMS message.

INVALID_RECIPIENT_ENTRY

One or more send to numbers provided is not valid. Ensure that all your mobile numbers are valid South Africa mobile numbers. All numbers need to be 11 digits in length and start with 27, have no spaces, or any special characters, for example 27637885448 is a valid number +27637885448 or 0637885448 are both invalid.

SIGNATURE_MISMATCH

Signature is invalid. This is a common issue. See how to generate a signature to learn more on how to properly generate a signature.

INSUFFICIENT_BALANCE

This is a common issue. Ensure your account has enough SMS credits when send or schedule SMS messages. You can purchase SMS credits for your Lefoka Account.

Schedule SMS errors

SCHEDULE_EMPTY_PARAMETER

Schedule parameter is provided however the value is blank. Ensure that after you have added the schedule parameter that you also add the schedule time in ISO format, for example 2023-08-07T04:41:08+02:00.

DATE_TIME_INVALID

Invalid date format provided. Possible errors are:
(a). The date and time provided is not in ISO format. For example 2023-08-07T04:41:08+02:00 is a valid date and time in ISO format i.e. YYYY-MM-DDTHH:MM:SS.
(b). The date and time provided is in the past, the API adds 15 minutes to the current time. For example if the time right now is 20:00 - the systems adds 15 minutes to ensure that the SMS message is delivered successfully. As such we recommend adding 15 minutes in the future as a safety message. So if you wanted to send a message at 8PM send 8:15PM on your request.
(c). The date and time provided exceeds 7 days, currently you can only schedule SMS up to 7 days.

SIGNATURE_MISMATCH

Signature is invalid. This is a common issue. See how to generate a signature to learn more on how to properly generate a signature.

INTERNAL_SERVER_ERROR

These are very rare, it means something went wrong on our end. Feel free to contact us if you think this is an error, on our chat bot or send an email to support@lefoka.co.za, or call us on +27 633 788 5448

List SMS errors

NO_SMS_MESSAGES

No SMS messages. This is technically not an error. You usually recieve this if you do not have any records (especially for new accounts), or used pagination to retrieve SMS messages from a page that does not have any records.

JSON errors

JSON_EXCEEDED

Maximum stack depth exceeded.

JSON_MALFORMED

Underflow or the modes mismatch.

JSON_ERROR_CTRL_CHAR

Unexpected control character found.

JSON_INVALID_SYNTAX

Syntax error, malformed JSON.

JSON_MALFORMED_UTF8

Malformed UTF-8 characters, possibly incorrectly encoded.

JSON_UNKNOWN

Unknown error, please contact us.

Need help?

For anything else, feel free to contact to send an email to support@lefoka.co.za, or call on +27 633 788 5448 or .

SMS API

API Reference

Authentication

Errors

Attributes

Versioning and Changelog

Balance

The balance object

Attributes

HATEOAS links

Retrieve the balance

Parameters

Returns

SMS Delivery Statuses

Send SMS

The SMS object

Attributes

HATEOAS links

Send the SMS immediately

Parameters

Headers

Returns

Schedule the SMS

Parameters

Headers

Returns

Edit scheduled SMS

Edit scheduled SMS

Parameters

Returns

Delete scheduled SMS

The delete scheduled SMS object

Attributes

HATEOAS links

Delete scheduled SMS

Parameters

Returns

List SMS

Retrieve a message

Parameters

Returns

List all messages

Parameters

Returns

SMS Replies

Webhook

Signature generation

Generating the signature header

Error Responses

The error response object

Attributes

All possible error responses

HTTP Status codes

Authentication errors

Balance errors

Send SMS errors

Schedule SMS errors

List SMS errors

JSON errors

Need help?

API examples

Use cases

Account notifications.

SMS customer service.

SMS marketing made easy.

OPT or Two-factor authentication.

Start building

PHP

JSON Response Payload