Application Programming Interface

Welcome Developers

Our API makes it easy to add powerful group texting functionality to your site or application. This is the same API our web and mobile clients use so you have full access to a rich set of commands to create and manage texting groups. Contact us at support@groupflier.com with any questions or feedback. Finally, please drop us a note and let us know about your project.

Table of contents

  1. Introduction
  2. Global information
  3. Error handling
  4. Group commands
  5. Member commands
  6. Message commands
  7. Device commands
  8. Account commands

Introduction

The API is implemented as a REST interface. A call is made to a URL using either a POST or a GET. The URL will return either a HTTP error code or a JSON data structure.

Global information

Error handling

Errors are returned as either an HTTP error code or an error data structure. Errors should be checked as follows:
  1. Check the HTTP return code.
    • 401 Authorization required - The call needs a valid, logged in session id (sid). The session id (sid) passed is either missing, invalid, logged out or expired.
  2. Check the status flag in the data structure. If it is set to ERROR the error_type and the optional error_subtype fields will hold tokens that describe the error.

Group commands

Description Create a group
URL /group/create
Parameters group • The name of the group
name • The name of the group creator
number • The mobile number of the group creator
email • The email address of the group creator (optional)
name_N • The name of the additional member. N is an sequential integer from 0 to 100
number_N • The number of the additional member. N is an sequential integer from 0 to 100
source • The name of the application that is creating the group (optional)
reply_to_owner • A flag, if set messages only go to the group creator (optional)
send_pin • A flag, if set a PIN will be send (optional)
Returns status • OK
number • The group number
first_group • Flag is true if this is the first group for an account
Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
INVALID_NUMBER • An invalid phone number was passed. The error_subtype holds the phone number
TOO_LONG • A name was over 30 characters long. The error_subtype holds the name
GROUP_FLIER_NUMBER • A groupflier phone number was passed. The error_subtype holds the phone number. You can not nest groups
BLOCKED_NUMBER • The number has requested a block of all groupflier texts
DUP_NUMBER • The group has a duplicate phone number in it. The error_subtype holds the phone number.
DUP_NAME • The group has a duplicate name in it. The error_subtype holds the name.
TOO_MANY_PENDING_GROUPS • You have staged too many groups and can not create more groups until you activate the staged groups
NOT_ENOUGH_MEMBERS • The group needs at least one member
TOO_MANY_MEMBERS • The group is full
Notes
  1. This command creates the group. To activate the group the owner must reply to the message sent to them.
  2. If an additional member row does not have both a name and number it is ignored.

Description Update the group settings
URL /group/set
Parameters sid • The session id
pin • The PIN from send_pin in /group/create (optional)
pin_number • The number the PIN was sent to (optional)
number • The group number
name • The name of the group (optional)
notify_on_add • A flag to notify the group when a new member is added (optional)
reply_to_owner • A flag, if set messages only go to the group creator (optional)
disable_who • Flag to disable the *who command for group members (optional)
disable_add • Flag to disable the *add command for group members (optional)
invite_code • The invitation code for the group (optional)
is_public • Flag to make this a public group (optional)
description • Description of the group (optional)
Returns status • OK
invite_code • See notes
Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
TOO_LONG • The name was over 30 characters long.
DESCRIPTION_TOO_LONG • The description was over 150 characters long.
MEMBER_LOOKUP_FAILED • Unable to find the member in this group
NOT_OWNER • The member is not the owner of the group
INVALID_INVITE_CODE • The invite code has to be between 4 and 50 characters long and can only contain alphanumerics, underscores and dashes
USED_INVITE_CODE • Another group is already using that invite code
CANT_MAKE_PUBLIC • A group can only be made public if it has a name and a description
Notes
  1. If the is_public flag is set but no invite code is passed a random invite_code will be generated and returned in the return hash

Description Delete the group
URL /group/delete
Parameters sid • The session id
number • The group number to delete
Returns status • OK
Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
INVALID_NUMBER • An invalid phone number was passed
MEMBER_LOOKUP_FAILED • Unable to find the member in this group
NOT_OWNER • The member is not the owner of the group
Notes

Description List public groups
URL /group/list
Parameters search • Search expression (optional and mutually exclusive with newest)
newest • Flag to get the most recent groups (optional and mutually exclusive with search)
number • Users phone number (optional)
Returns status • OK
groups • An array of the groups. Each object holds the following fields
* invite_code • Invite code
* name • Name of the group
* description • Group description
* owner • Name of the group owner
* reply_to_owner • Flag for the messages only go to the group owner setting
* count • Number of members in the group
* full • Flag if the group is full
* is_member • Flag if number is a member of the group already
Errors THROTTLE • You have submitted too many requests too fast
SHORT_SEARCH • The search expression needs to be at least 3 characters long
Notes
  1. If a search expression is not specified the list of featured groups is returned

Description Join a group
URL /group/join
Parameters invite_code • The invitation code of the group
name • Your name (optional if the group is a reply_to_owner group)
number • Your phone number
Returns status • OK
name • Name of the group
Errors NOT_FOUND • The invitation code was not found
TOO_MANY_MEMBERS • The group is full
MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
INVALID_NUMBER • An invalid phone number was passed. The error_subtype holds the phone number
GROUP_FLIER_NUMBER • A groupflier phone number was passed.
BLOCKED_NUMBER • The number has requested a block of all groupflier texts
DUP_NUMBER • The group already has the phone number.
TOO_LONG • The name was over 30 characters long.
DUP_NAME • The group already has this name in it
THROTTLE • You have submitted too many requests too fast
Notes

Description Check an invitation code
URL /group/invite/check
Parameters invite_code • The invitation code of the group
Returns status • OK
name • Name of the group
reply_to_owner • Flag, if set messages only go to the group owner
disable_who • Flag to disable the *who command for group members
Errors NOT_FOUND • The invitation code was not found
TOO_MANY_MEMBERS • The group is full
MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
THROTTLE • You have submitted too many requests too fast
Notes

Member commands

Description Find a member and send them a login pin
URL /member/find
Parameters number • The mobile number
Returns status • OK
has_password • Do they have a password
Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
INVALID_NUMBER • An invalid phone number was passed. The error_subtype holds the phone number
NOT_FOUND • The phone number is not a member of the system
THROTTLE • You have submitted too many requests too fast
Notes
  1. If successful a one time expiring PIN will be sent to the members mobile phone if they do not have a password

Description Login a member
URL /member/login
Parameters number • The mobile number
pin • The PIN number or account password
source • The name of the application that they are logging in through (optional)
Returns status • OK
sid • The session id
Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
INVALID_NUMBER • An invalid phone number was passed.
INVALID_PIN • The PIN was invalid
LOCKOUT • Too many failed login attempts. The client will be locked out for a while
Notes

Description Returns the groups the member belongs to
URL /member/groups
Parameters sid • The session id
Returns status • OK
number • The members phone number
account • The members account object. The object has the following fields.
* type • Type of account 'F'ree, 'T'rial or 'P'aid
* balance • Account balance in pennies
* suspended • Flag if the account is suspended
groups • An array of the groups the member belongs to. Each object holds the following fields
* name • Name of the group
* number • Number of the group
* bye • Flag if they have left the group
* sms • SMS deliverly state. See notes
* owner • Flag if they are the owner of the group
* notify_on_add • Flag to notify the group when a new member is added
* reply_to_owner • Flag, if set messages only go to the group owner
* disable_who • Flag to disable the *who command for group members
* disable_add • Flag to disable the *add command for group members
* is_public • Flag if this is a public group
* invite_code • Invite code for the group
* description • Description of the group
* suspended • Flag if the group is suspended
* members • An array of the members of the group. Each object holds the following fields
 + name • Name of the member
 + number • Number of the member
 + bye • Flag if they have left the group
 + owner • Flag if they are the owner of the group
 + broadcast • Flag if they can broadcast to a reply to owner group
Errors
Notes
  1. The account parameter is not returned if the member does not own any groups
  2. Member list restrictions for non owners
    • If disable_who is set on the members list will contain only the owner and the member
    • If disable_who and reply_to_owner is set on the members list will contain only the member
  3. SMS delivery state values
    • 0 = Never deliver messages by SMS
    • 1 = Always deliver messages by SMS
    • 2 = Deliver by SMS when they are offline. Offline is when a member has not had any recent API activity or has signed out.

Description Add a member to the group
URL /member/add
Parameters sid • The session id
group • The group number
name • The name of the new member
number • The number of the new member
Returns status • OK
Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
MEMBER_LOOKUP_FAILED • Unable to find the member in this group
INVALID_NUMBER • An invalid phone number was was passed.
GROUP_FLIER_NUMBER • A groupflier phone number was passed.
BLOCKED_NUMBER • The number has requested a block of all groupflier texts
DUP_NUMBER • The group already has the phone number.
DUP_NAME • The group already has this name in it
TOO_MANY_MEMBERS • The group is full
TOO_LONG • The name was over 30 characters long.
DISABLED_ADD • The group creator has disabled the ability for a member to add to the group.
Notes

Description Remove a member from the group
URL /member/remove
Parameters sid • The session id
group • The group number
number • The number to remove
Returns status • OK
Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
INVALID_NUMBER • An invalid phone number was passed. The error_subtype holds the phone number
MEMBER_LOOKUP_FAILED • Unable to find the member in this group
NOT_OWNER • Only the group owner can remove a member
NOT_SELF • You can not remove yourself
NOT_FOUND • Can not find the number to remove
Notes

Description Update the member information
URL /member/set
Parameters sid • The session id
group • The group number
number • The group owner can modify another members settings by passing the member number (optional)
name • The name of the member (optional)
sms • SMS deliverly state. See the notes (optional)
broadcast • Can they broad cast to a reply to owner group (optional)
Returns status • OK
Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
INVALID_NUMBER • An invalid phone number was passed
MEMBER_LOOKUP_FAILED • Unable to find the member in this group
NOT_OWNER • Only the group owner can change another members information
TOO_LONG • The name was over 30 characters long
NAME_IN_USE • Another member of the group is using this name
INVALID_SMS_STATE • Invalid delivery value
INVALID_BROADCAST • Invalid broadcast value or they are not the group owner
Notes
  1. SMS delivery state values
    • 0 = Never deliver messages by SMS
    • 1 = Always deliver messages by SMS
    • 2 = Deliver by SMS when they are offline. Offline is when a member has not had any recent API activity or has signed out.

Description Leave a group
URL /member/bye
Parameters sid • The session id
group • The group number
Returns status • OK
Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
INVALID_NUMBER • An invalid phone number was passed
MEMBER_LOOKUP_FAILED • Unable to find the member in this group
Notes

Description Re-join a group
URL /member/hi
Parameters sid • The session id
group • The group number
Returns status • OK
Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
INVALID_NUMBER • An invalid phone number was passed
MEMBER_LOOKUP_FAILED • Unable to find the member in this group
Notes

Description Logout a member
URL /member/logout
Parameters sid • The session id
Returns status • OK
Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
Notes

Message commands

Description Get a count of the messages in each group
URL /message/count
Parameters sid • The session id
number • Get the count for this group number only (optional)
Returns status • OK
results • An array of the counts for each group. Each object holds the following fields
* number • Number of the group
* count • Number of messages in the group
Errors
Notes

Description Get message(s)
URL /message/get
Parameters sid • The session id
number • The group number to get the messages for
message_id • The id of the message to get (optional)
message_from • Get messages from this id to the last message or the message_to value (optional)
message_to • Get messages from the first message or message_from value to this id (optional)
Returns status • OK
time • Epoch time on the server
messages • An array of the messages. Each object holds the following fields
* id • Id of the message, a sequential integer starting at 1
* txt • Text of the message
* time • Epoch time the message was sent
Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
INVALID_NUMBER • An invalid phone number was passed
MEMBER_LOOKUP_FAILED • Unable to find the member in this group
Notes

Description Send a message
URL /message/send
Parameters sid • The session id
number • The group number to send the message to
message • The message to send
cc • cc me a copy as a SMS or device notification. 1/0 flag (optional)
Returns status • OK
refresh • The message was a star command and caused a change in the group status (optional)
Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
INVALID_NUMBER • An invalid phone number was passed
MEMBER_LOOKUP_FAILED • Unable to find the member in this group
MESSAGE_TOO_LONG • The message was longer than 150 characters
SUSPENDED • The account is suspended
Notes
  1. Your hi/bye status will be automatically set to hi when you send a message to the group

Description Send a message
URL /message/grand/total
Parameters
Returns status • OK
cnt • The grand total of all messages processed by the system
Errors
Notes

Description Schedule a message for later delivery
URL /message/schedule
Parameters sid • The session id
number • The group number to send the message to
message • The message to send
cc • cc me a copy as a SMS or device notification. 1/0 flag (optional)
when • Comma delimited list of the UTC times to send the message at. Format is YYYY-MM-DD HH:MM:SS
Returns status • OK
Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
INVALID_NUMBER • An invalid phone number was passed
MEMBER_LOOKUP_FAILED • Unable to find the member in this group
MESSAGE_TOO_LONG • The message was longer than 150 characters
SUSPENDED • The account is suspended
NOT_OWNER • Only the owner of a group can schedule messages
INVALID_WHEN • An invalid time format or the time is not in the future. The error_subtype holds the time
Notes

Description List the scheduled messages
URL /message/schedule/list
Parameters sid • The session id
number • The group number
Returns status • OK
messages • An array of the messages. Each object holds the following fields
* id • Id of the message
* txt • Text of the message
* when • UTC time when the message will be sent. Same format as scheduled message creation.
Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
INVALID_NUMBER • An invalid phone number was passed
MEMBER_LOOKUP_FAILED • Unable to find the member in this group
NOT_OWNER • Only the owner of a group can get the message list
Notes

Description Delete a scheduled message
URL /message/schedule/delete
Parameters sid • The session id
number • The group number
message_id • The scheduled message id
Returns status • OK
Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
INVALID_NUMBER • An invalid phone number was passed
MEMBER_LOOKUP_FAILED • Unable to find the member in this group
NOT_OWNER • Only the owner of a group can delete the message
NOT_FOUND • The scheduled message can not be found
Notes

Device commands

Description Register a device
URL /device/register
Parameters number • The phone number of the device
type • Type of the device (iphone,iphone_no_notify,android)
token • Token of the device
Returns status • OK
Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
INVALID_TYPE • The type field is not valid
INVALID_NUMBER • An invalid phone number was passed. The error_subtype holds the phone number
THROTTLE • You have submitted too many requests too fast
Notes
  • If successful a one time expiring PIN will be sent to the members mobile phone and can be used for login
  • Description Release a device
    URL /device/release
    Parameters sid • The session id
    type • Type of the device (iphone,iphone_no_notify,android)
    Returns status • OK
    Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
    INVALID_TYPE • The type field is not valid
    Notes
  • When the last device for a number is released the member sms delivery state will be set to 1
  • Account commands

    Description Set the account information
    URL /account/set
    Parameters sid • The session id
    email • Email address
    zip • Billing zip
    cc_expiration • Credit card expiration in the format YYYY-MM (optional)
    cc_number • Credit card number (optional)
    Returns status • OK
    cc_description • Credit card description if a credit card was passed
    Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
    NO_ACCOUNT • This member does not have an account
    INVALID_EMAIL • Invalid email address
    INVALID_CC_NUMBER • Invalid credit card number
    INVALID_CC_TYPE • Invalid credit card type only Mastercard, Visa and American Express
    INVALID_CC_EXPIRATION • Invalid or expired date
    Notes
    1. If any of the cc_* fields are passed then all of them must be passed or a MISSING_FIELDS error will be returned

    Description Set the account password
    URL /account/password
    Parameters sid • The session id
    password • The password
    Returns status • OK
    Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
    NO_ACCOUNT • This member does not have an account
    Notes

    Description Get the current account balance
    URL /account/balance
    Parameters sid • The session id
    Returns status • OK
    balance • The account balance in pennies
    suspended • Is the account suspended
    type • Type of account 'F'ree, 'T'rial or 'P'aid
    Errors
    Notes

    Description Charge the account credit card
    URL /account/charge
    Parameters sid • The session id
    amount • The amount to charge in pennies
    Returns status • OK
    Errors MISSING_FIELDS • A required field is missing or does not have data in it. The error_subtype holds a array of all the missing fields
    NO_ACCOUNT • This member does not have an account
    NO_CREDIT_CARD • The account does not have a credit card on file
    EXPIRED_CREDIT_CARD • The credit card has expired
    INVALID_AMOUNT • The amount must be between 1,000 and 100,000
    DECLINED • The charge was declined. The error_subtype holds further details
    Notes