All group endpoints require authentication. Include the JWT token in the Authorization header.
Create Group
Create a new expense-sharing group.
Bearer token for authentication
Request Body
Group name (max 50 characters)
Group description (max 500 characters)
Array of member objects with email addressesShow Member object structure
Member’s email address. If user doesn’t exist, a new account will be created automatically.
Response
Group’s unique identifier
Array of member objects
User object with _id, name, and email
Member’s current balance in the group
Creator’s user object with _id, name, and email
Whether the group has been settled
Example Request
curl -X POST https://api.billbuddy.com/api/groups \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{
"name": "Weekend Trip",
"description": "Expenses for our camping trip",
"members": [
{ "email": "[email protected]" },
{ "email": "[email protected]" }
]
}'
Example Response
{
"_id": "507f191e810c19729de860ea",
"name": "Weekend Trip",
"description": "Expenses for our camping trip",
"members": [
{
"user": {
"_id": "507f1f77bcf86cd799439011",
"name": "John Doe",
"email": "[email protected]"
},
"balance": 0
},
{
"user": {
"_id": "507f1f77bcf86cd799439012",
"name": "Alice Smith",
"email": "[email protected]"
},
"balance": 0
}
],
"createdBy": {
"_id": "507f1f77bcf86cd799439011",
"name": "John Doe",
"email": "[email protected]"
},
"expenses": [],
"isSettled": false,
"createdAt": "2024-01-15T10:30:00.000Z"
}
Get All Groups
Retrieve all groups the current user is a member of.
Bearer token for authentication
Response
Returns an array of group objects with populated member and creator information.
Example Request
curl -X GET https://api.billbuddy.com/api/groups \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Example Response
[
{
"_id": "507f191e810c19729de860ea",
"name": "Weekend Trip",
"description": "Expenses for our camping trip",
"members": [
{
"user": {
"_id": "507f1f77bcf86cd799439011",
"name": "John Doe",
"email": "[email protected]"
},
"balance": 0
}
],
"createdBy": {
"_id": "507f1f77bcf86cd799439011",
"name": "John Doe",
"email": "[email protected]"
},
"expenses": [],
"isSettled": false,
"createdAt": "2024-01-15T10:30:00.000Z"
}
]
Get Single Group
Retrieve detailed information about a specific group.
Bearer token for authentication
Path Parameters
Response
Returns a group object with populated members, creator, and expenses.
Example Request
curl -X GET https://api.billbuddy.com/api/groups/507f191e810c19729de860ea \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Example Response
{
"_id": "507f191e810c19729de860ea",
"name": "Weekend Trip",
"description": "Expenses for our camping trip",
"members": [
{
"user": {
"_id": "507f1f77bcf86cd799439011",
"name": "John Doe",
"email": "[email protected]"
},
"balance": 0
}
],
"createdBy": {
"_id": "507f1f77bcf86cd799439011",
"name": "John Doe",
"email": "[email protected]"
},
"expenses": [
{
"_id": "507f191e810c19729de860eb",
"description": "Groceries",
"amount": 150.50
}
],
"isSettled": false,
"createdAt": "2024-01-15T10:30:00.000Z"
}
Error Responses
{
"message": "Group not found"
}
{
"message": "Not authorized to access this group"
}
Update Group
Update group information. Only the group creator can update the group.
Bearer token for authentication
Path Parameters
Request Body
Updated group name (max 50 characters)
Updated group description (max 500 characters)
Array of user IDs to set as group members. This will replace existing members (except the creator).
Example Request
curl -X PUT https://api.billbuddy.com/api/groups/507f191e810c19729de860ea \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{
"name": "Updated Weekend Trip",
"description": "Updated description"
}'
Example Response
{
"_id": "507f191e810c19729de860ea",
"name": "Updated Weekend Trip",
"description": "Updated description",
"members": [...],
"createdBy": "507f1f77bcf86cd799439011",
"expenses": [],
"isSettled": false,
"createdAt": "2024-01-15T10:30:00.000Z"
}
Error Responses
{
"message": "Group not found"
}
{
"message": "Not authorized to update this group"
}
Delete Group
Delete a group. Only the group creator can delete the group.
Bearer token for authentication
Path Parameters
Example Request
curl -X DELETE https://api.billbuddy.com/api/groups/507f191e810c19729de860ea \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Example Response
{
"message": "Group removed"
}
Error Responses
{
"message": "Group not found"
}
{
"message": "Not authorized to delete this group"
}
Add Member to Group
Add a new member to an existing group. Only the group creator can add members.
Bearer token for authentication
Path Parameters
Request Body
Email address of the user to add
Response
Returns the updated group object with populated member and creator information.
Example Request
curl -X POST https://api.billbuddy.com/api/groups/507f191e810c19729de860ea/members \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]"
}'
Example Response
{
"_id": "507f191e810c19729de860ea",
"name": "Weekend Trip",
"description": "Expenses for our camping trip",
"members": [
{
"user": {
"_id": "507f1f77bcf86cd799439011",
"name": "John Doe",
"email": "[email protected]"
},
"balance": 0
},
{
"user": {
"_id": "507f1f77bcf86cd799439013",
"name": "New Member",
"email": "[email protected]"
},
"balance": 0
}
],
"createdBy": {
"_id": "507f1f77bcf86cd799439011",
"name": "John Doe",
"email": "[email protected]"
},
"expenses": [],
"isSettled": false,
"createdAt": "2024-01-15T10:30:00.000Z"
}
Error Responses
{
"message": "User is already a member of this group"
}
{
"message": "Group not found"
}
{
"message": "User not found"
}
{
"message": "Not authorized to add members to this group"
}