RentSpree Screening Integration

Overview

RentSpree is a third-party tenant screening service. DoorStax PMs can generate RentSpree ApplyLinks and send branded screening invitations directly from the dashboard. All screening emails come from DoorStax via Resend — not RentSpree — using the ApplyLink embedded in the email body.

Authentication

RentSpree uses a 2-step JWT-bearer OAuth flow:

1. Sign a JWT assertion locally with your RSA private key
2. Exchange the assertion for a 15-minute access token at https://user.rentspree.com/oidc/token
3. Use the access token to call https://api.rentspree.com/partners/v2/*

DoorStax caches the access token in memory with a 60-second safety buffer and automatically refreshes before expiry.

Required Environment Variables

RENTSPREE_CLIENT_ID=your_partner_client_id
RENTSPREE_CLIENT_SECRET=your_partner_secret
RENTSPREE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n..."
RENTSPREE_PARTNER_USER_ID=your_partner_user_id
RENTSPREE_PARTNER_EMAIL=partner@example.com

Screening Configuration Cascade

Screening options (credit report, criminal, eviction, application, payer type) are resolved per-unit using a cascade:

1. Unit-level overrides (if set)
2. PM defaults (stored on User record)
3. System defaults (all enabled, landlord pays)

Validation Rules

• Criminal background check requires credit report to be enabled
• Eviction history check requires credit report to be enabled
• If credit report is disabled, application must be enabled
• Criminal check not available in NJ or IL (state-based restriction)
• Eviction check not available in NY (state-based restriction)

Screening Invitation Flow

// POST /api/rentspree/send-invitation
{
  unitId: "...",
  emails: ["applicant1@example.com", "applicant2@example.com"]
}

// Server:
// 1. Resolves screening config via cascade
// 2. Calls RentSpree API to generate ApplyLink
// 3. Stores applyLink, applyLinkFull, screeningOptionId on unit
// 4. Loops through emails, sends branded DoorStax email via Resend
//    with the ApplyLink as the CTA button
// 5. Creates a ScreeningInvitation record for each sent email

API Endpoints

• POST /api/rentspree/generate-link — Generate ApplyLink for a unit
• POST /api/rentspree/send-invitation — Send branded invitations to applicants
• GET/PUT /api/rentspree/screening-defaults — Manage PM-level defaults
• GET /api/rentspree/invitations/[unitId] — Invitation history for a unit

Mock Mode

When RentSpree environment variables are not set, the API falls back to mock mode: it generates fake apply links for testing and returnsmock: true in the response. This lets you build and test UI flows without real RentSpree credentials.

Auto-Generation on Unit Available

When a unit status changes to AVAILABLE (e.g., after a tenant is removed), an ApplyLink is automatically generated in the background if RentSpree is configured. This is non-blocking and never fails the primary status change.