API Teams

API – Teams

Manage team workspaces for collaborative bill management. Each team is an isolated data environment with its own bills, categories, and transactions.

Base path: /api/v1/teams

---

Endpoints

Method	Endpoint	Description
GET	/teams	List teams
POST	/teams	Create a team
GET	/teams/{team}	Get a single team
PUT	/teams/{team}	Update a team
DELETE	/teams/{team}	Delete a team (owner only)
POST	/teams/{team}/members	Add a member
DELETE	/teams/{team}/members/{user}	Remove a member
POST	/teams/{team}/switch	Switch active team

---

GET /teams

List all teams the authenticated user belongs to (as owner or member).

Query Parameters:

Parameter	Type	Description
search	string	Search name/description/slug
status	string	Filter by status
user_id	integer	Filter by user ID
sort_by	string	Column to sort by
per_page	integer	Results per page

Response 200:

{
  "data": [
    {
      "id": 1,
      "name": "Family Bills",
      "slug": "family-bills",
      "description": "Shared family expenses",
      "currency": "USD",
      "currency_symbol": "$",
      "icon_url": "https://...",
      "owner": {
        "id": 1,
        "name": "John Doe"
      },
      "members": []
    }
  ],
  "links": { ... },
  "meta": { ... }
}

---

POST /teams

Create a new team. The authenticated user automatically becomes the owner and first member.

Request:

{
  "name": "Family Bills",
  "description": "Shared family expenses",
  "currency": "USD",
  "currency_symbol": "$",
  "icon": "base64_encoded_image"
}

Field	Type	Required	Description
name	string	Yes	Team name
description	string	No	Optional description
currency	string	No	ISO currency code (e.g. USD, EUR)
currency_symbol	string	No	Display symbol (e.g. $, €)
icon	string	No	Base64-encoded team icon image

Response 201:

{
  "success": true,
  "message": "Team created successfully",
  "data": {
    "id": 1,
    "name": "Family Bills",
    "slug": "family-bills",
    "currency": "USD",
    "currency_symbol": "$"
  }
}

---

GET /teams/{team}

Get a single team by ID or slug, including the owner and all members.

Response 200:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Family Bills",
    "slug": "family-bills",
    "description": "Shared family expenses",
    "currency": "USD",
    "currency_symbol": "$",
    "icon_url": "https://...",
    "owner": {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com"
    },
    "members": [
      {
        "id": 2,
        "name": "Jane Doe",
        "email": "jane@example.com"
      }
    ]
  }
}

---

PUT /teams/{team}

Update team details. All fields are optional.

Request:

{
  "name": "Updated Team Name",
  "description": "Updated description",
  "currency": "EUR",
  "currency_symbol": "€"
}

Response 200:

{
  "success": true,
  "message": "Team updated successfully",
  "data": {
    "id": 1,
    "name": "Updated Team Name",
    "currency": "EUR"
  }
}

---

DELETE /teams/{team}

Delete a team. Only the team owner can delete a team. All associated data (bills, categories, transactions) will be removed.

Response 200:

{
  "success": true,
  "message": "Team deleted successfully"
}

Response 403 — non-owner attempts to delete:

{
  "message": "This action is unauthorized."
}

---

POST /teams/{team}/members

Add a registered user to the team. Duplicate members are rejected.

Request:

{
  "user_id": 2
}

Field	Type	Required	Description
user_id	integer	Yes	ID of the user to add

Response 201:

{
  "success": true,
  "message": "Member added successfully",
  "data": {
    "id": 2,
    "name": "Jane Doe",
    "email": "jane@example.com"
  }
}

---

DELETE /teams/{team}/members/{user}

Remove a member from the team. The team owner cannot be removed.

Response 200:

{
  "success": true,
  "message": "Member removed successfully"
}

Response 422 — attempting to remove the owner:

{
  "success": false,
  "message": "Cannot remove the team owner."
}

---

POST /teams/{team}/switch

Switch the authenticated user's active team context. After switching, all subsequent team-scoped requests operate within the new team.

Response 200:

{
  "success": true,
  "message": "Active team switched successfully"
}

---

cURL Examples

TOKEN="YOUR_TOKEN"
BASE="https://bills.msar.me/api/v1"

# List teams
curl "$BASE/teams" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

# Create a team
curl -X POST "$BASE/teams" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Work Bills","currency":"USD","currency_symbol":"$"}'

# Switch active team
curl -X POST "$BASE/teams/1/switch" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

# Add a member
curl -X POST "$BASE/teams/1/members" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id":5}'

# Remove a member
curl -X DELETE "$BASE/teams/1/members/5" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"