Skip to main content

​
Overview

The Household API enables you to manage household membership, including initialization, inviting members, accepting/declining invitations, and managing member roles.

​
Endpoints

​
Initialize Household

​
GET /api/household/init
endpoint
Gets or creates a household for the authenticated user.
Authentication: Required Response
​
householdId
string
The ID of the user’s household (created if it doesn’t exist)
curl -X GET https://your-domain.com/api/household/init \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN"
Example Response 
{
  "householdId": "clx456def"
}
This endpoint calls getOrCreateHousehold(userId, email) which automatically creates a household if the user doesn’t have one.

​
Get Household Members

​
GET /api/household/members
endpoint
Retrieves all members of the user’s household, including pending invitations.
Authentication: Required Response
​
members
array
Array of household member objects
​
trueOwnerId
string
User ID of the household owner (first owner by ID)
​
trueOwnerEmail
string
Email address of the household owner
curl -X GET https://your-domain.com/api/household/members \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN"
Example Response 
{
  "members": [
    {
      "id": "clxmem1",
      "householdId": "clx456def",
      "userId": "user_abc123",
      "invitedEmail": null,
      "role": "owner",
      "status": "accepted",
      "name": "John Doe",
      "createdAt": "2024-03-01T10:00:00Z"
    },
    {
      "id": "clxmem2",
      "householdId": "clx456def",
      "userId": "user_xyz789",
      "invitedEmail": null,
      "role": "member",
      "status": "accepted",
      "name": "Sarah Smith",
      "createdAt": "2024-03-05T14:30:00Z"
    },
    {
      "id": "clxmem3",
      "householdId": "clx456def",
      "userId": null,
      "invitedEmail": "[email protected]",
      "role": "member",
      "status": "pending",
      "name": "[email protected]",
      "createdAt": "2024-03-10T09:00:00Z"
    }
  ],
  "trueOwnerId": "user_abc123",
  "trueOwnerEmail": "[email protected]"
}

​
Manage Household Members

​
POST /api/household/members
endpoint
Multi-purpose endpoint for inviting members, updating roles, and removing members.
Authentication: Required Request Body (Invite Member) Request Body (Update Role) Request Body (Remove Member) Request Body (Self-Removal) 
curl -X POST https://your-domain.com/api/household/members \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'
Response (Invite) 
{
  "id": "clxmem4",
  "householdId": "clx456def",
  "invitedEmail": "[email protected]",
  "role": "member",
  "status": "pending",
  "createdAt": "2024-03-15T12:00:00Z"
}
If already invited: 
{
  "message": "Already invited"
}
Response (Update Role) 
{
  "message": "Role updated"
}
Response (Remove) 
{
  "message": "Member removed"
}
Response (Self-Removal) 
{
  "message": "You have exited the household"
}

​
Check Invite Status

​
GET /api/household/invite-status
endpoint
Checks if the authenticated user has any pending household invitations.
Authentication: Required Response
​
hasInvite
boolean
Whether the user has a pending invitation
​
householdId
string
ID of the household (if invited)
​
inviteId
string
ID of the invitation record (if invited)
​
householdName
string
Name of the household (if invited)
curl -X GET https://your-domain.com/api/household/invite-status \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN"
Example Response (No Invite) 
{
  "hasInvite": false
}
Example Response (Has Invite) 
{
  "hasInvite": true,
  "householdId": "clx456def",
  "inviteId": "clxmem5",
  "householdName": "Smith Family"
}

​
Accept Invitation

​
POST /api/household/accept
endpoint
Accepts a pending household invitation.
Authentication: Required Request Body 
curl -X POST https://your-domain.com/api/household/accept \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inviteId": "clxmem5"}'
Response 
{
  "success": true
}
When accepting an invitation, the member record is updated with the user’s userId and the status is changed to “accepted”.

​
Decline Invitation

​
POST /api/household/decline
endpoint
Declines and deletes a pending household invitation.
Authentication: Required Request Body 
curl -X POST https://your-domain.com/api/household/decline \
  -H "Authorization: Bearer YOUR_CLERK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inviteId": "clxmem5"}'
Response 
{
  "success": true
}

​
Error Responses

​
401 Unauthorized
User is not authenticated
Unauthorized
​
400 Bad Request
Missing or invalid parameters
Missing or invalid invite ID
or 
Invalid role
or 
Invalid request
​
404 Not Found
Household not found
No household found
​
500 Internal Server Error
Unexpected server error
Internal Server Error
or 
Failed to verify user

​
Member Roles

The API supports three member roles:
  • owner: Full access, can manage members and settings
  • member: Standard access, can view and edit household data
  • guest: Limited access (implementation-dependent)

​
Source Code Reference

  • Initialize: ~/workspace/source/src/app/api/household/init/route.ts:4
  • Members: ~/workspace/source/src/app/api/household/members/route.ts:12
  • Invite status: ~/workspace/source/src/app/api/household/invite-status/route.ts:5
  • Accept: ~/workspace/source/src/app/api/household/accept/route.ts:5
  • Decline: ~/workspace/source/src/app/api/household/decline/route.ts:5

Build docs developers (and LLMs) love

Get started for freeTalk to us