Every client Application (APP) has an API Key associated with it. This key is generated during the creation of the APP and can be re-generated from the show / edit screens in the Service Layer (SL) administrative console.
This key uniquely identifies an APP during the calls the APP does to the SL.
All calls should be performed with POST request. The API Key (api_key) is the only form field required to be present in every call to the service layer since it is necessary to identify the application.
There’s an API URL that is used at all times to which the name of the operation is appended:
https://sl.holmesmobile.com/api/<operation> (SSL support)
Parameters that you specify in the calls to API and receive in callbacks from the API can be of different types.
Regular text string.
Integer number, either positive or negative.
We are quite flexible with booleans.
Dates and times parsing is very liberal in the SL. We are capable of parsing almost everything that can be interpreted as a date / time or even a clue of them. Here are some examples of what the dates can look like:
If you need a stricter definition, you can refer to RFC2822 (3.3. Date and Time Specification).
This set of calls let the application to associate / dissociate more keywords with itself. All necessary checks are performed automatically to avoid conflicts.
Associates the keyword with the application.
Breaks the link between the keyword and the application.
If an application needs to send a message to a certain phone number, it uses this call. The message can be of arbitrary size. If it doesn’t fit into the standard message size (160 characters), the message will be broken into several parts automatically, like this:
Scheduled messages are sent in batches every 15 minutes. The format of the date (“on” field) may vary from very strict “10/12/2008 12:55AM — 0500” to the relaxed “Tuesday 9 1:15PM”. If the timezone isn’t specified, the EST (GMT-5) is assumed.
When message breaking is necessary, it can be performed in one of three predefined ways. The way can be chosen on per-application basis and is set in the Application preferences on the Service Layer side.
Sometimes you need to send several slightly different messages to several phone numbers. You could issue multiple “send_message” requests, but there’s a better way. Basically, you specify a template to use as a basis for your messages and then for each number you only give the different parts to paste into the template for each number. Here’s an example:
The phone number 0123456789 will receive “Hello John. You have 5 credits left.” and the phone number 9876543210 will receive “Hello Mary. You have 10 credits left.”
This call cancels messages scheduled for future delivery with the send_message call with parameter “on”. The send_message call returned the list of IDs corresponding to all scheduled messages or parts of the bigger message that didn’t fit into a single text message. You can use these IDs to cancel future messages at any moment.
Please note that this call can cancel only non-subscription messages. To cancel subscription-level messages, use “cancel_subscription_messages” call.
This call accepts a single sent message ID or the list of IDs separated by commas and returns the status for each of the messages. If the message wasn’t found, it’s not mentioned in the results. The statuses have numeric values and are as follows:
Assigns the list of tags to the list of phone numbers among the subscribers of your application.
Removes the tags in the list from the phone numbers (all or specific, if they are given).
Returns the number of subscribers in each tag.
Sends a message to the application subscribers. The message is split into multiple parts using the preferred application splitting mode automatically.
If the list of tags is given, subscribers with these tags are chosen. If no tag is specified, all subscribers receive the message.
If the time in the “on” field is given the call operates in the scheduling mode. It schedules a message to be sent to the application subscribers in a future. The message text will be split and otherwise processed as in the usual subscription message sending. The date of the message sending has to be tomorrow or later. The date can contain the suggested time and the application will use it as a guidance. The message is guaranteed to not be sent before this time, but can be sent later. The messages are supposed to be sent in batches periodically during the day (currently every two hours). The format of the date may vary from very strict “10/12/2008 12:55AM -0500” to the relaxed “Tuesday 9 1:15PM”. If the timezone isn’t specified, the EST (GMT-5) is assumed.
This call cancels subscription messages scheduled for future delivery with the send_subscription_message call with the parameter “on”. The send_subscription_message call returned the list of IDs corresponding to all scheduled messages. You can use these IDs to cancel future messages at any moment.
Please note that this call is for scheduled subscription messages. Use “cancel_messages” call for regular future messages cancellation.
This set of calls lets the application work with carrier data.
Query for carrier info for the given phone number.
|Name||Carrier Id (CID)||Country Code||Updated Date|
|Alaska Communications Systems (ACS)||592||US||2010-06-02T15:43:06GMT|
|Chat Mobility (Hawkeye)||619||US||2010-09-28T20:06:00GMT|
|Cingular Blue (AT&T)||7||US||2010-02-12T17:55:57GMT|
|Cricket (Leap Wireless)||40||US||2010-02-12T17:55:57GMT|
|East Kentucky Network||570||US||2010-02-12T17:55:57GMT|
|Illinois Valley Cellular||574||US||2010-06-02T15:48:56GMT|