engageSPARK API (1.0.0)

Balance of the organization.

Send a single SMS to a contact. If there is no existing contact with the phone number a contact will be created.

Unicode and multi-part SMS are supported. See message for details.

Exactly one of "contactId", "fullPhoneNumber", or "phoneNumber" with "phoneNumberCountry" need to be set.

Retries: The SMS API automatically re-tries failed messages as often as possible within 24 hours by default. To know up to when we’ll keep retrying your message, you can refer to the deliveryDeadline of your POST request.

Testing frequency: In many countries, mobile network operators limit the number of SMS you can send to a single number per minute often 5 sms/number/minute. If you are sending more than five SMS to a single number within a minute, some messages may not get through and will be lost.

This is the normal API to send an SMS.

Single SMS to a phone number without creating or using a contact.

If needed the message will be sent in multiple parts, which should automatically be reassembled on the user's phone.

Exactly one of "fullPhoneNumber", or "phoneNumber" with "phoneNumberCountry" need to be set.

List SMSs. Newest first.

Number of result per API call is limited, see "nextPage" and "after" to get more results.

Load an SMS, including its delivery status.

Add a contact to a campaign. The campaign must be launched, not stopped, and it must be open to new subscriptions.

Exactly one of "contactId", "fullPhoneNumber", or "phoneNumber" with "phoneNumberCountry" needs to be set.

This API will return an error if the contact already has an active (done == false) subscription. However, a user can have multiple subscriptions with the same campaign over time. You can set the allowResubscribe flag to false if you want the request to fail in case the user had or has any subscription to this campain.

By default, the new subscriptions start right away. Use the delay field to schedule new subscriptions into the future.

Unsubscribe a single contact from a campaign. The call will cancel any subscription from the given contact ID, if there is any active subscription. Because this is actually an abort the subscription will be listed as "error" in reports.

It's fine to call this if there a no, or no active, subscription for the contact.

With the engageSPARK Airtime Top Up API, you can send prepaid airtime to anyone on the fly! In some countries, airtime is known as prepaid phone credit or mobile credit, or load top-up.

We are able to send very specific amounts of airtime per mobile network operator in each country. For example, we cannot send 25 Philippine pesos of airtime to a mobile phone on the Smart mobile network in the Philippines, but we can send 25 pesos to a mobile phone on the Globe mobile network. The amounts available differ by the mobile network operator (telco) and by country.

With these limitations in mind, we wanted to make this API super easy to use. We didn’t want you to worry about what mobile network operator a phone number is on for you to be able to easily send prepaid airtime to the phone number. So to simplify things, we created our Airtime Top-Up API with two parameters: the maxAmount parameter and the desiredAmount parameter.

maxAmount Parameter

In the maxAmount parameter, you specify the maximum amount you want to send to the phone number. If that amount is available, we’ll send that amount; if it’s not available, then we’ll send the closest amount available that is smaller than the maxAmount you specified.

For example, if you pass a phone number on the Globe network in the Philippines and a maxAmount of 25, we’ll send 25 pesos to that phone number because that’s an available amount for mobile phones on the Globe network. But if you pass a phone number on the Smart network in the Philippines and a maxAmount of 25, we’ll send that phone number 20 pesos of airtime because that’s the closest amount available that is smaller than 25. Please refer to our pricing table to see the available amounts.

desiredAmount Parameter

The desiredAmount parameter, which is optional but recommended, flips the perspective of the API. By passing a desiredAmount, you can specify the top-up amount you prefer to send to the phone number.

If the desiredAmount is available for the phone number, then we will send that amount. If it is not available, then we will send the next amount higher that is available, but no higher than the maxAmount.

For example, if you pass a phone number on the Smart network in the Philippines, a desiredAmount of 20, and a maxAmount of 30, then we’ll send 20 pesos to that phone number because that’s an available amount for mobile phones on the Smart network. But if you pass a phone number on the Globe network in the Philippines with the same desiredAmount and maxAmount parameters, we’ll send 25 pesos to that phone number because that’s the closest amount available that is greater than or equal to the desiredAmount of 20 and less than or equal to the maxAmount of 30 for mobile phones on the Globe network. As mentioned above, you can refer to our pricing table to see the available amounts.

Currencies

For most countries, we are able to send airtime in local currency; in some countries, we can send airtime only in USD. The recipient will receive the airtime in their local currency, but the conversion from USD to the local currency will happen at the time of the transfer, so the received amount may be slightly different each time depending on exchange rates. Moreover, in countries where we can send in local currency, there are some circumstances where a slightly higher amount will be sent than what you specify, but you will still be charged what is listed in our pricing table for the amount you specify. Once again, please refer to our pricing table to see the currencies and amounts available per telco per country.

Phone number / Contact

Exactly one of contactId, fullPhoneNumber, or phoneNumber with phoneNumberCountry need to be set.

List Top Ups. Number of result per API call is limited, see "nextPage" and "after" to get more results.

Sorted by newest first.

Load a Top Up previously created.

Add a new contact to the system. This will return a contact ID which can be used in other engageSPARK APIs.

Most APIs will create a contact on the fly when you use a new phone number, but creating it explicitly gives you more control over the contact fields (such as "first name").

Exactly one of "fullPhoneNumber", or "phoneNumber" with "phoneNumberCountry" needs to be set.

Using this API you can create multiple different contacts with the same phone number.

Load a contact with all groups, segments, and custom fields.

Update a contact. Only fields which are set will be updated.