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
   • /group/create
   • /group/set
   • /group/delete
   • /group/list
   • /group/join
   • /group/invite/check
5. Member commands
   • /member/find
   • /member/login
   • /member/groups
   • /member/add
   • /member/remove
   • /member/set
   • /member/bye
   • /member/hi
   • /member/logout
6. Message commands
   • /message/count
   • /message/get
   • /message/send
   • /message/grand/total
   • /message/schedule
   • /message/schedule/list
   • /message/schedule/delete
7. Device commands
   • /device/register
   • /device/release
8. Account commands
   • /account/set
   • /account/password
   • /account/balance
   • /account/charge

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

• Italic words represent fields names
• UPPER CASE words represent input data or error tokens
• Every returned data structure has a status field that holds either OK or ERROR
• Date and time stamps are in UTC
• Fields are required unless noted as optional
• All phone numbers are returned by the API as fully qualified numbers i.e. "+14445556666".
• Phone numbers may be sent to the API in any format i.e. "+14445556666" or "(444) 555-6666" or "4445556666"
• Flags are numeric fields with a 1 or 0 value for true or false

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	This command creates the group. To activate the group the owner must reply to the message sent to them. 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	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	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	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	The account parameter is not returned if the member does not own any groups 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 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	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	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	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