Manage

The Group API allows for integration with Falkor's Groups feature. The Manage endpoint allows for bulk adding and removal of users for a single group. When new users are added, Falkor app invites are sent automatically within 1 - 5 minutes.

Parameters

Key	Type
REQUIRED
group	String
OPTIONAL
add	Array of users (see below)
remove	Array of strings (valid emails)
app	String (e.g io.falkor.app)
invite	Integer (defaults to 1)

Invite Parameter

By default any new users added to groups will be sent an invite to the app. If you would like to disable this you can set the invite parameter to "0". Disabling invites will require invites to be manually sent from Falkor's Groups feature.

App Parameter

If you account is assigned multiple Falkor apps you can use the app parameter to assign the group to a specific app. The app parameter takes the app's reverse domain identity as an argument. If you only have 1 app on your account you would not need to provide this parameter as this is automatically assigned.

User

When using the add parameter it must be an array of users. firstname, lastname and email are required. If the email parameter is not valid, the response will contain warnings with applicable messages.

Key	Type
REQUIRED
firstname	String
lastname	String
email	String (Valid Email)
OPTIONAL
dialCode	String (e.g +44)
phoneNumber	String (e.g 0840001234)

The telephone parameter in the user object is deprecated. If you would like to add a telephone number use dialCode + phoneNumber

Example

The example below adds the user "[e-mail]" and removes the user "[e-mail]" from the "Group API" group. When adding users to groups it will only insert new users and ignore existing users in the group.

Hint. If the group does not exist, it will automatically be created.

curl -X POST \
  v1/groups/manage \
  -H 'Authorization: Basic <Your Base64 Encoded Token>' \
  -d '{
	"group" : "Your Group Name",
	"add"  : [
		{
			"firstname" : "Test",
			"lastname"  : "User",
			"email"     : "[e-mail]"   
		}
	],
	"remove" : ["[e-mail]"]
}'

Success Response

Inserts & Deletes The response will contain information about how many users where inserted & deleted. An insert will only occur if the email was not currently part of the group. A deletion will only occur if the email was current part of the group.

{
    "status": "success",
    "data": {
        "inserts": 1,
        "deletes": 1,
        "warnings": 0
    },
    "hash": "dd60caf42926ff3de481f6f4c3a5ebba",
    "response_time": 0.11101603507995605
}

Success Response With Warning

If there are any issues detected with the add or remove parameter a warning will occur. If the response has a warning an array of messages will detail what went wrong.

{
    "status": "success",
    "data": {
        "inserts": 0,
        "deletes": 0,
        "warnings": 2,
        "messages": [
            {
                "parameter": "add",
                "index": 0,
                "error": "User object did not have valid parameters, make sure firstname, lastname and email are valid"
            },
            {
                "parameter": "remove",
                "index": 0,
                "error": "The provided string was not a valid email"
            }
        ]
    },
    "hash": "3bb8a3a6e2db9eb9422d60ad3ddb7312",
    "response_time": 0.09190487861633301
}