• API

    General

    API Keys

    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.

    Calls

    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:

    URL: http://sl.holmesmobile.com/api/<operation> orhttps://sl.holmesmobile.com/api/<operation> (SSL support)

    Data Types

    Parameters that you specify in the calls to API and receive in callbacks from the API can be of different types.

    String

    Regular text string.

    Integer

    Integer number, either positive or negative.

    Boolean

    We are quite flexible with booleans.

    • They are case-insensitive and can take the following shapes:
      • TRUE: 1, t, true, y, yes
      • FALSE: 0, f, false, n, no

    Dates / Times

    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:

    • 16:30 — takes current date as basis and uses provided time
    • Aug 31 — take current year, users the given date and sets time to 00:00
    • 7/31 — the same as above
    • 2/9/2007 or 2007-02-09 — date only
    • 02-09-2007 12:30:44 AM or 2007-09-02T00:30:44Z — UTC (GMT) time
    • 02-09-2007 12:30:44 PM EST or 2007-09-02T12:30:44-0500 — localized time
    • Wednesday, January 10, 2001 — human-readable date

    If you need a stricter definition, you can refer to RFC2822 (3.3. Date and Time Specification).

    Keywords

    Keywords

    This set of calls let the application to associate / dissociate more keywords with itself. All necessary checks are performed automatically to avoid conflicts.

    Associate Keyword (associate_keyword)

    Associates the keyword with the application.

    Parameters:

    • api_key – (String) API key of the application
    • keyword – (String) keyword
    • mode – (Integer) 0 – match exactly, 1 – start with
    • auto_subscribe – (Boolean, Optional) TRUE – keyword will initiate the subscription
    • auto_subscribe_tags – (String, Optional) comma-separated list of tags to assign to the newly created auto-subscription

    Responses:

    • HTTP Code 500 and error message in the body
    • HTTP Code 200 with JSON hash (text/javascript):
      • errors – optional array of error messages, in case of any problems with the keyword registration (duplicates, incorrect format etc). If this element isn’t present, the operation was successful.

    Dissociate Keyword (dissociate_keyword)

    Breaks the link between the keyword and the application.

    Parameters:

    • api_key – (String) API key of the application
    • keyword – (String) keyword

    Responses:

    • HTTP Code 500 and error message in the body
    • HTTP Code 200 with JSON hash (text/javascript):
      • errors – optional array of error messages. For example, when the keyword belongs to a different application.

    Messaging

    Send Message (send_message)

    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:

    • (1/3) The beginning …
    • (2/3) … continuation …
    • (3/3) … the ending.

    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.

    Split Modes:

    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.

    • Character Boundary – the message will be split in part without looking for gaps between the words and the ends of sentences. It’s the most compact way of breaking the messages that ensures the minimal number of parts being sent.
    • Word Boundary – the message text is analyzed for the gaps between the words and split so that no word is broken unless the message becomes severely under-filled (more than a half of the message is empty). In this case the Character Boundary mode is used to fill the rest of the part and the operation switches back to normal Word Boundary operation for the next part.
    • Sentence Boundary – the message is broken into parts preferably on the sentence edges which are (commas, exclamation and question marks, and line breaks). Again if the message appears to be under-filled, the mode is switched to the Word Boundary and if even this doesn’t help, it is lowered to the Character Boundary.

    Parameters:

    • api_key – (String) API key of the application
    • phone_number or phone_numbers – (String) destination phone number (10 digits with or without country code) or a comma-separated list of phone numbers.
    • body – (String) message text
    • action_expected – (Boolean, Optional) send TRUE if the response from the target phone is expected. In this case, the session between the phone and the Application is established for seamless directing of the response MO’s to the application without the need of sending the Keyword to select the Application first.
    • on – (String, Optional) time when the message is to be sent

    Responses:

    • HTTP Code 500 and error message in the body
    • HTTP Code 200
      • Comma-separated list of scheduled message IDs is returned with the “message_ids” key. This is useful for matching sent messages with delivery reports and message cancellation. Negative IDs are possible in these cases:
        • -1 — if phone number was invalid
        • -2 — if phone number is currently blacklisted
        • -3 — if phone is being flooded reached the limit of messages for a configured period of time for this app

    Send Messages (send_messages)

    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:

    • template = “Hello {{name}}. You have {{credits}} credits left.”
    • recipients = ‘{“0123456789″: {“name”: “John”, “credits”: “5”}, “9876543210”: {“name”: “Mary”, “credits”: “10”}}’

    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.”

    Parameters:

    • api_key – (String) API key of the application
    • template – (String) template string to use for generation of recipient messages.
    • recipients – (String) JSON-hash with phone numbers (10 digits) as keys and the substitution hash as values. Each substitution hash contains the names of tags you mentioned in the template body as keys and the replacement values as values.
    • action_expected – (Boolean, Optional) send TRUE if the response from the target phone is expected. In this case, the session between the phone and the Application is established for seamless directing of the response MO’s to the application without the need of sending the Keyword to select the Application first.
    • on – (String, Optional) time when the message is to be sent

    Responses:

    • HTTP Code 500 and error message in the body
    • HTTP Code 200
      • Comma-separated list of scheduled message IDs is returned with the “message_ids” key. This is useful for matching sent messages with delivery reports and message cancellation.

    Cancel Messages (cancel_messages)

    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.

    Parameters:

    • message_ids – (String) comma-separated list of scheduled message IDs

    Responses:

    • HTTP Code 500 and error message in the body
    • HTTP Code 200
      • canceled_count – (Integer) the number of canceled messages

    Delivery status (delivery_status)

    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:

    • 0 – Pending delivery
    • 1 – Delivered to the user phone
    • 2 – Not delivered to the user phone (failed)

    Parameters:

    • message_ids – (String) comma-separated list of message IDs (either scheduled or not) returned from the send_message call

    Responses:

    • The JSON-formatted map of found message IDs to their statuses

    Subscriptions

    Tag Subscribers (tag_subscribers)

    Assigns the list of tags to the list of phone numbers among the subscribers of your application.

    Parameters:

    • api_key – (String) API key of the application
    • tags – (String) comma-separated list of tags
    • phone_numbers – (String) comma-separated list of phone numbers with or without the country code

    Responses:

    • HTTP Code 500 and error message in the body
    • HTTP Code 200

    Un-tag Subscribers (untag_subscribers)

    Removes the tags in the list from the phone numbers (all or specific, if they are given).

    Parameters:

    • api_key – (String) API key of the application
    • tags – (String) comma-separated list of tags
    • phone_numbers – (String, Optional) comma-separated list of phone numbers with or without the country code

    Responses:

    • HTTP Code 500 and error message in the body
    • HTTP Code 200

    Count Tagged Subscribers (count_tagged_subscribers)

    Returns the number of subscribers in each tag.

    Parameters:

    • api_key – (String) API key of the application
    • tags – (String) comma-separated list of tags

    Responses:

    • HTTP Code 500 and error message in the body
    • HTTP Code 200 with JSON hash (text/javascript) with tag-count pairs

    Send Subscription Message (send_subscription_message)

    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.

    Parameters:

    • api_key – (String) mandatory API Key
    • body – (String) message text
    • on – (String, Optional) time when the message is to be sent
    • tags – (String, Optional) comma-separated list of tags
    • description – (String, Optional) description of this message or any other info that you want to save

    Responses:

    • HTTP Code 500 and error message in the body
    • HTTP Code 200 with JSON hash (text/javascript)
      • If immediate subscription message:
        • recipient_count – number of recipients that received the message (only if it wasn’t a scheduled message)

    Cancel Subscription Messages (cancel_subscription_messages)

    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.

    Parameters:

    • message_ids – (String) comma-separated list of scheduled subscription message IDs

    Responses:

    • HTTP Code 500 and error message in the body
    • HTTP Code 200
      • canceled_count – (Integer) the number of canceled messages

    Subscriptions

    Carriers

    This set of calls lets the application work with carrier data.

    Carrier Info (carrier_info)

    Query for carrier info for the given phone number.

    Parameters:

    • api_key – (String) API key of the application
    • phone_number – (String) phone number to get info for (10 digits in arbitrary format)

    Responses:

    • HTTP Code 500 and error message in the body
    • HTTP Code 200 with JSON hash (text/javascript):
      • :id – internal carrier ID, unique for every carrier (e.g. 34, 140 etc)
      • :name – human-readable carrier name (e.g. Verizon, T-Mobile etc)

    Supported Carriers

    Name Carrier Id (CID) Country Code Updated Date
    Alaska Communications Systems (ACS) 592 US 2010-06-02T15:43:06GMT
    Aliant 509 CA 2010-02-12T17:55:57GMT
    Alltel 87 US 2010-02-12T17:55:57GMT
    Arch Communications 5 US 2010-06-15T15:56:38GMT
    Arch Paging 36 US 2010-02-12T17:55:57GMT
    AT&T 383 US 2010-02-12T17:55:57GMT
    Bell Mobility 80 CA 2010-09-28T00:46:40GMT
    Bluegrass Cellular 562 US 2010-02-12T17:55:57GMT
    Boost Mobile 534 US 2011-01-21T17:50:19GMT
    Boost-CDMA 586 US 2011-01-21T17:50:26GMT
    CellCom 587 US 2010-02-12T17:55:57GMT
    Cellular South 386 US 2010-02-12T17:55:57GMT
    Centennial 557 US 2010-02-12T17:55:57GMT
    Chat Mobility (Hawkeye) 619 US 2010-09-28T20:06:00GMT
    Cincinnati Bell 10 US 2010-02-12T17:55:57GMT
    Cingular Blue (AT&T) 7 US 2010-02-12T17:55:57GMT
    Claro 647 UY 2011-01-29T00:26:04GMT
    Claro 643 PY 2011-01-29T00:23:57GMT
    Claro 638 GT 2011-01-29T00:20:13GMT
    Claro 631 AR 2011-01-29T00:14:59GMT
    Cox Wireless 596 US 2010-06-02T15:51:40GMT
    Cricket (Leap Wireless) 40 US 2010-02-12T17:55:57GMT
    Dobson 535 US 2010-02-12T17:55:57GMT
    East Kentucky Network 570 US 2010-02-12T17:55:57GMT
    ECIT 590 US 2010-02-12T17:55:57GMT
    Fido (Microcell) 138 CA 2010-09-28T00:51:49GMT
    GCI Communications 603 US 2010-06-14T23:16:58GMT
    GTA Teleguam 640 US 2011-01-29T00:21:38GMT
    Hutchison 3G 474 GB 2010-07-16T22:11:51GMT
    Illinois Valley Cellular 574 US 2010-06-02T15:48:56GMT
    Immix 588 US 2010-02-12T17:55:57GMT
    Inland Cellular 575 US 2010-06-02T15:49:09GMT
    Iowa Wireless 477 US 2010-02-12T17:55:57GMT
    Metro PCS 516 US 2010-02-12T17:55:57GMT

Comments are closed.