engageSPARK API (1.0.0)

Download OpenAPI specification:Download

License: MIT Terms of Service

API documentation for engageSPARK.

Please see the documentation for other integration methods such as inbound SMS rules, Zapier zaps, or Make API Request actions.

Organization

Balance

Balance of the organization.

Authorizations:
apiToken
path Parameters
orgId
required
string

engageSPARK ID of the organization. You can find this ID in your Organization Profile.

Responses

Response samples

Content type
application/json
{
  • "balance": 3.141592,
  • "balanceMicro": 3141592,
  • "balanceHuman": "3.14",
  • "autoRecharge": true,
  • "autoRechargeThreshold": 50,
  • "autoRechargeAmount": 100
}

SMS

Send SMS

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.

Authorizations:
apiToken
Request Body schema: application/json
required
required
integer or string

ID of the organization. It can be a string or a number. You can find it in your Organization Profile.

from
required
string

Sender ID. In general these need to be set, unless you use a default one.

message
required
string

The content of the message. A message can be up to 7 parts long; longer messages will be rejected.

You can personalize the SMS using the contact's data, for example the first name. Example: Hello {{contact.firstName}}

In many countries, Unicode characters can be used. Country-specific GSM 03.38 code pages, however, are generally not supported.

⚠️ Please note that when using unicode-characters, the SMS length calculation changes. Read more about SMS character limits.

clientDedup
string

If not empty; if we already send a message with the given value we won't send the message again. Useful when a POST failed thanks to network errors.

clientPushURL
string

Whenever we get a delivery receipt we POST to this URL.

clientRef
string

ID we'll return in lists of SMSs. Can be anything and doesn't need to be unique. engageSPARK doesn't do anything with this.

integer or string

engageSPARK ID of the contact. If provided, the contact must exist and be part of the organization.

fullPhoneNumber
string

Full phone number including the country code, may have a leading "+".

This number needs to have an international dialing code.

For example, for a number from the Philippines (with the dialing code 63), 639123456789 would be correct, whereas 9123456789 would be missing the dialing code. If you are not sure about the dialing code of the country you want to send calls or SMS to, check this Wikipedia article on dialing codes.

phoneNumber
string

Country part of phone number. If this us used phoneNumberCountry must also be set.

phoneNumberCountry
string

Two letter ISO code of the country. Used with the "phoneNumber" option.

to
string

Legacy, same as "fullPhoneNumber".

Responses

Request samples

Content type
application/json
{
  • "orgId": 0,
  • "from": "string",
  • "message": "string",
  • "clientDedup": "string",
  • "clientPushURL": "string",
  • "clientRef": "string",
  • "contactId": 0,
  • "fullPhoneNumber": "631234567890",
  • "phoneNumber": "1234567890",
  • "phoneNumberCountry": "PH",
  • "to": "string"
}

Response samples

Content type
application/json
{
  • "messageId": "SMS20240325T122739-500492-1545",
  • "estimateParts": 2,
  • "estimateMicro": 10000,
  • "estimate": "0.02",
  • "deliveryDeadline": "2024-03-26T12:35:15.530548089Z",
  • "to": "631234567890",
  • "message": "string",
  • "clientDedup": "string",
  • "clientPushURL": "string",
  • "clientRef": "string"
}

Send SMS without contact

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.

Authorizations:
apiToken
Request Body schema: application/json
required
required
integer or string

ID of the organization. It can be a string or a number. You can find it in your Organization Profile.

from
required
string

Sender ID. In general these need to be set, unless you use a default one.

message
required
string

The content of the message. A message can be up to 7 parts long; longer messages will be rejected.

Personalized messages are not supported in this API.

In many countries, Unicode characters can be used. Country-specific GSM 03.38 code pages, however, are generally not supported.

⚠️ Please note that when using unicode-characters, the SMS length calculation changes. Read more about SMS character limits.

clientDedup
string

If not empty; if we already send a message with the give value we won't send a message again. Useful when a POST failed thanks to network errors.

clientPushURL
string

Whenever we get a delivery receipt we POST to this URL.

clientRef
string

ID we'll return in lists of SMSs. Can be anything and doesn't need to be unique. engageSPARK doesn't do anything with this.

fullPhoneNumber
string

Full phone number including the country code, may have a leading "+".

phoneNumber
string

Country part of phone number. If this us used phoneNumberCountry must also be set.

phoneNumberCountry
string

Two letter ISO code of the country. Used with the "phoneNumber" option.

to
string

Legacy, same as "fullPhoneNumber".

Responses

Request samples

Content type
application/json
{
  • "orgId": 0,
  • "from": "string",
  • "message": "string",
  • "clientDedup": "string",
  • "clientPushURL": "string",
  • "clientRef": "string",
  • "fullPhoneNumber": "631234567890",
  • "phoneNumber": "1234567890",
  • "phoneNumberCountry": "PH",
  • "to": "string"
}

Response samples

Content type
application/json
{
  • "messageId": "SMS20240325T122739-500492-1545",
  • "estimateParts": 2,
  • "estimateMicro": 10000,
  • "estimate": "0.02",
  • "deliveryDeadline": "2024-03-26T12:35:15.530548089Z",
  • "to": "631234567890",
  • "message": "string",
  • "clientDedup": "string",
  • "clientPushURL": "string",
  • "clientRef": "string"
}

List SMSs

List SMSs. Newest first.

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

Authorizations:
apiToken
path Parameters
orgId
required
string

engageSPARK ID of the organization. You can find this ID in your Organization Profile.

query Parameters
after
string

See "nextPage" in the response.

limit
integer <= 100
Default: 100

Maximum number of results per API call.

dir
string
Default: "all"
Enum: "inbound" "outbound" "all"

Limit to only egress, only ingress, or all directions. Empty value is same as "all".

failed
string
Default: "all"
Enum: "true" "false" "all"

Limit to/exclude failed deliveries. Failed means the message didn't get delivered at all. Delivery Receipts are not taken into account here. Empty value is same as "all".

search
string

Keyword search in the message, sender, receiver, and contact fields.

startDate
string <date-time>

Create time of the message must be >= this timestamp.

endDate
string <date-time>

Create time of the message must be < this timestamp.

Responses

Response samples

Content type
application/json
{
  • "messages": [
    ],
  • "hasNextPage": true,
  • "nextPage": "string"
}

Get single SMS

Load an SMS, including its delivery status.

Authorizations:
apiToken
path Parameters
orgId
required
string

engageSPARK ID of the organization. You can find this ID in your Organization Profile.

messageId
required
string

ID of the SMS.

Responses

Response samples

Content type
application/json
{
  • "id": "SMS20240325T122739-500492-1545",
  • "direction": "egress",
  • "created": "2024-03-26T12:35:15.530548089Z",
  • "sender": "string",
  • "recipient": "string",
  • "contactId": 123456,
  • "pricePerPart": 20000,
  • "done": true,
  • "successPartCount": 2,
  • "successT": "2024-03-26T12:35:15.530548089Z",
  • "message": "Hello Mary Sue, we will visit you coconut farm Monday 1 April around 12:00.",
  • "error": "string",
  • "deliveryError": "string",
  • "deliveredToTelco": true,
  • "deliveredToPhone": "unknown",
  • "client_ref": "string"
}

Campaigns

Subscribe contact to a campaign

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.

Authorizations:
apiToken
path Parameters
orgId
required
string

engageSPARK ID of the organization. You can find this ID in your Organization Profile.

campaignId
required
string

engageSPARK ID of the campaign. You can find this ID when editing your campaign, or copy it in the actions drop down in the campaigns list.

Request Body schema: application/json
required
integer or string

engageSPARK ID of the contact. If provided, the contact must exist and be part of the organization.

fullPhoneNumber
string

Full phone number including the country code, may have a leading "+".

phoneNumber
string

Country part of phone number. If this us used phoneNumberCountry must also be set.

phoneNumberCountry
string

Two letter ISO code of the country. Used with the "phoneNumber" option.

allowResubscribe
boolean
Default: true

Should a contact be resubscribed if it has a previous, already finished subscription?

object

Delays the start of the subscription. If omitted, the subscriptions start immediately.

You always must set the value field. When using the day unit, you can additionally set the time and timezone fields. When using the week unit, you can additionally set the time, timezone, and dayOfWeek fields.

Note that “0 days 9:00” can give a different result than “1 day 9:00”, depending on the current time of day. The former means “the upcoming 9:00” and the latter means “tomorrow's 9am”. For example, if now it's 8:30, then the former means the subscription starts in half an hour. The latter would mean that the subscription starts in 24 hours and 30 minutes.

object (properties_contact)

Update the contact with the given fields before subscribing it.

All fields are optional. Fields that are not given, will not be updated.

Responses

Request samples

Content type
application/json
{
  • "contactId": "3456789",
  • "fullPhoneNumber": "631234567890",
  • "phoneNumber": "1234567890",
  • "phoneNumberCountry": "PH",
  • "allowResubscribe": false,
  • "delay": {
    },
  • "contact": {
    }
}

Response samples

Content type
application/json
{
  • "runId": 0,
  • "contactId": 0
}

Unsubscribe contact from campaign

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.

Authorizations:
apiToken
path Parameters
orgId
required
string

engageSPARK ID of the organization. You can find this ID in your Organization Profile.

campaignId
required
string

engageSPARK ID of the campaign. You can find this ID when editing your campaign, or copy it in the actions drop down in the campaigns list.

Request Body schema: application/json
required
integer or string

engageSPARK ID of the contact.

Responses

Request samples

Content type
application/json
{
  • "contactId": "3456789"
}

Response samples

Content type
application/json
{
  • "runId": 0
}

Top Up

Send Top Up

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.

Authorizations:
apiToken
path Parameters
orgId
required
string

engageSPARK ID of the organization. You can find this ID in your Organization Profile.

Request Body schema: application/json
required
required
integer or string

We make the topup closest to this amount (but not over). See the request description for examples and a more in-detail discussion.

integer or string

We try to use the topup closest to this amount. Optional but recommended. See the request description for examples and a more in-detail discussion.

clientRef
string

ID we'll return in lists of Top Ups. Can be anything and doesn't need to be unique. engageSPARK doesn't do anything with this.

async
boolean

If not set or false we won't return until the topup is finished. Since this can take up to 10 minutes this might give problems with timeouts. It's recommended to set async to true, and then check the result.

test
boolean

If true we don't do the actual Top Up, but we return what we would have done.

integer or string

engageSPARK ID of the contact.

fullPhoneNumber
string

Full phone number including the country code, may have a leading "+".

phoneNumber
string

Country part of phone number. If this us used phoneNumberCountry must also be set.

phoneNumberCountry
string

Two letter ISO code of the country. Used with the "phoneNumber" option.

Responses

Request samples

Content type
application/json
{
  • "maxAmount": 0,
  • "desiredAmount": 0,
  • "clientRef": "string",
  • "async": true,
  • "test": true,
  • "contactId": 0,
  • "fullPhoneNumber": "631234567890",
  • "phoneNumber": "1234567890",
  • "phoneNumberCountry": "PH"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "currency": "string",
  • "amountSent": 0,
  • "price": 0,
  • "queued": true
}

List Top Ups

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

Sorted by newest first.

Authorizations:
apiToken
path Parameters
orgId
required
string

engageSPARK ID of the organization. You can find this ID in your Organization Profile.

query Parameters
after
string

See "nextPage" in the response.

limit
integer <= 100
Default: 100

Maximum number of results per API call.

failed
string
Default: "all"
Enum: "true" "false" "all"

Limit to/exclude failed Top Ups.

search
string
Example: search=Sue

Keyword search in the contact fields.

startDate
string <date-time>
Example: startDate=2020-02-20T20:20:20Z02:00

Create time of the Top Up must be >= this timestamp.

endDate
string <date-time>
Example: endDate=2020-02-20T20:20:20Z02:00

Create time of the Top Up must be < this timestamp.

Responses

Response samples

Content type
application/json
{
  • "topups": [
    ],
  • "hasNextPage": true,
  • "nextPage": "string"
}

Get Top Up

Load a Top Up previously created.

Authorizations:
apiToken
path Parameters
orgId
required
string

engageSPARK ID of the organization. You can find this ID in your Organization Profile.

topupId
required
string

ID of the Top Up.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "done": true,
  • "success": true,
  • "error": "string",
  • "clientRef": "string",
  • "topupCurrency": "string",
  • "topupReceived": 0,
  • "priceCharged": 0,
  • "firstName": "string",
  • "lastName": "string"
}

Contacts

Create contact

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.

Authorizations:
apiToken
path Parameters
orgId
required
string

engageSPARK ID of the organization. You can find this ID in your Organization Profile.

Request Body schema: application/json
required
fullPhoneNumber
string

Full phone number including the country code, may have a leading "+".

phoneNumber
string

Country part of phone number. If this is used phoneNumberCountry must also be set.

phoneNumberCountry
string

Two letter ISO code of the country. Used with the phoneNumber option.

firstName
string

First name of the contact.

lastName
string

Last name of the contact.

language
string

Language is free form, you can use any standard or system, or leave it empty. The Language field is used in multi language campaigns to decide which version of a message or call to use.

Array of integers or strings

List of group IDs this contact will be a member of. Values can be either integers, or string version of integers.

customFields
object

Custom fields values. Keys of the object are the engageSPARK integer ID of the custom field, and the value is a free form string.

customFieldsByName
object

Alternative way to set Custom fields. It's the same idea as customFields, but the keys of the objects are the name of custom fields. We'll use the existing group ID, or create a new one if it doesn't exist.

  • names are compared case in-sensitive (so if you add "Gender", it'll re-use an existing column "gender").
  • if there are multiple possible matches, then we take the oldest existing custom field.
  • if the same custom field is used in customFields and customFieldsByName, then the value in customFieldsByName wins.
  • if the same custom field is given multiple times in customFieldsByName then it's not defined which one wins ({"color": "green", "COLOR": "red"}). The custom field color can now be either red or green).

Responses

Request samples

Content type
application/json
{
  • "fullPhoneNumber": "631234567890",
  • "phoneNumber": "1234567890",
  • "phoneNumberCountry": "PH",
  • "firstName": "Mary",
  • "lastName": "Sue",
  • "language": "Vietnamese",
  • "groups": [
    ],
  • "customFields": {
    },
  • "customFieldsByName": {
    }
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "fullPhoneNumber": "631234567890",
  • "firstName": "Mary",
  • "lastName": "Sue",
  • "language": "Vietnamese",
  • "groups": [
    ],
  • "customFields": {
    },
  • "createdAt": "2020-05-28T10:59:45.061156Z"
}

Get contact

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

Authorizations:
apiToken
path Parameters
orgId
required
string

engageSPARK ID of the organization. You can find this ID in your Organization Profile.

contactId
required
string

engageSPARK ID of the contact. You get this ID when creating a contact.

Responses

Response samples

Content type
application/json
{
  • "id": 12345,
  • "fullPhoneNumber": "631234567890",
  • "firstName": "Mary",
  • "lastName": "Sue",
  • "language": "Vietnamese",
  • "groups": [
    ],
  • "customFields": {
    },
  • "createdAt": "2020-05-28T10:59:45.061156Z"
}

Update contact

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

Authorizations:
apiToken
path Parameters
orgId
required
string

engageSPARK ID of the organization. You can find this ID in your Organization Profile.

contactId
required
string

engageSPARK ID of the contact. You get this ID when creating a contact.

Request Body schema: application/json
required
fullPhoneNumber
string

Full phone number including the country code, may have a leading "+".

firstName
string

First name of the contact.

lastName
string

Last name of the contact.

language
string

Language is free form, you can use any standard or system, or leave it empty. The Language field is used in multi language campaigns to decide which version of a message or call to use.

Array of integers or strings

List of group IDs this contact will be a member of. Values can be either integers, or string version of integers.

customFields
object

Custom fields values. Keys of the object are the engageSPARK integer ID of the custom field, and the value is a free form string. Groups which aren't set aren't updated. Set value to an empty string to delete the value.

customFieldsByName
object

Alternative way to set Custom fields. It's the same idea as customFields, but the keys of the objects are the name of custom fields. See the documentation in "Create Contact".

Responses

Request samples

Content type
application/json
{
  • "fullPhoneNumber": "631234567890",
  • "firstName": "Mary",
  • "lastName": "Sue",
  • "language": "Vietnamese",
  • "groups": [
    ],
  • "customFields": {
    },
  • "customFieldsByName": {
    }
}

Response samples

Content type
application/json
{
  • "id": 12345,
  • "fullPhoneNumber": "631234567890",
  • "firstName": "Mary",
  • "lastName": "Sue",
  • "language": "Vietnamese",
  • "groups": [
    ],
  • "customFields": {
    },
  • "createdAt": "2020-05-28T10:59:45.061156Z"
}