Skip to content
HomeStar Docs

Favorites API

The Favorites API enables cross-device favorites synchronization using passwordless magic link authentication. For architectural details, see the Favorites Architecture explanation.

Endpoints

Section titled “Endpoints”
Section titled “Request Magic Link”

POST /api/v1/favorites/magic-link

Sends a magic link email to the specified address.

{
  "email": "user@example.com"
}

Headers:

  • Content-Type: application/json
  • X-Session-ID: {session_id} (optional, for session linking)

Rate Limiting: Maximum 3 pending magic links per email within 15 minutes.

Section titled “Verify Magic Link”

GET /api/v1/favorites/verify/{token}

Verifies a magic link token and returns authentication credentials.

{
  "success": true,
  "client_id": 123,
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "favorites": ["98970014", "98970015", "98970171"],
  "email": "user@example.com"
}

Token Behavior:

  • Expires after 15 minutes
  • Can only be used once
  • Links anonymous session to client if X-Session-ID was provided

Get Favorites

Section titled “Get Favorites”

GET /api/v1/favorites

Returns the authenticated user’s synced favorites.

Headers:

Authorization: Bearer {auth_token}

Sync Favorites

Section titled “Sync Favorites”

POST /api/v1/favorites/sync

Syncs localStorage favorites to the server using a union merge strategy.

Headers:

Authorization: Bearer {auth_token}
Content-Type: application/json

Body:

{
  "favorites": ["98970014", "98970015", "98970171", "98970200"]
}

Remove Favorite

Section titled “Remove Favorite”

DELETE /api/v1/favorites/{listing_id}

Removes a specific favorite from the user’s synced list.

Headers:

Authorization: Bearer {auth_token}

Auth Token Structure

Section titled “Auth Token Structure”

The auth_token is a signed JWT with the following claims:

{
  "client_id": 123,
  "brokerage_id": 1,
  "email": "user@example.com",
  "exp": 1735689600,
  "iat": 1727913600,
  "type": "favorites_auth"
}
ClaimDescription
client_idInternal client/lead ID
brokerage_idAssociated brokerage
emailVerified email address
expExpiration (90 days from issue)
iatIssued at timestamp
typeAlways "favorites_auth"

Data Models

Section titled “Data Models”
Section titled “MagicLink”
ColumnTypeDescription
idSERIALPrimary key
brokerage_idINTEGERAssociated brokerage (FK)
emailVARCHAR(255)Recipient email
tokenVARCHAR(64)Unique secure token
session_idVARCHAR(36)Optional session to link
expires_atTIMESTAMPTZToken expiration time
used_atTIMESTAMPTZWhen token was used (null if unused)
client_idINTEGERClient created on verification (FK)

ClientFavorite

Section titled “ClientFavorite”
ColumnTypeDescription
idSERIALPrimary key
client_idINTEGERAssociated client (FK)
listing_idVARCHAR(50)MLS listing ID
created_atTIMESTAMPTZWhen favorite was added

Unique Constraint: (client_id, listing_id) — prevents duplicates.

Section titled “Related”