# Manage

The Group API allows for integration with Falkor's [Groups ](https://docs.falkor.io/groups/managing-users)feature. The **Manage** endpoint allows for bulk adding and removal of users for a single group. When new users are added, [Falkor app invites](https://docs.falkor.io/groups/managing-users/sending-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 ](https://docs.falkor.io/groups/managing-users)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) |

{% hint style="warning" %}
The telephone parameter in the user object is **deprecated**. If you would like to add a telephone number use `dialCode` + `phoneNumber`
{% endhint %}

### Example

The example below adds the user "<test@example.com>" and removes the user "<test2@example.com>" from the "Group API" group. When adding users to groups it will only insert new users and ignore existing users in the group.

{% hint style="info" %}
**Hint.** If the group does not exist, it will automatically be created.
{% endhint %}

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

### 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.&#x20;

```
{
    "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. &#x20;

```
{
    "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
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://everyday-digital.gitbook.io/falkor-dev-docs/groups/manage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.