Skip to main content

​
Matching Algorithm API Reference

The FindU matching API provides personalized college recommendations and manages student-school interactions.

​
Base URL

Production: https://findu-matching-production.up.railway.app
Development: https://findu-matching-development.up.railway.app

​
Authentication

All endpoints require a valid Supabase JWT token: 
Authorization: Bearer YOUR_JWT_TOKEN

​
Endpoints

​
Get Recommendations

Retrieve personalized college recommendations for a student. 
curl -X POST https://api.findu.app/recommendations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "student_id": "123e4567-e89b-12d3-a456-426614174000",
    "limit": 20,
    "offset": 0
  }'

​
Request Body

ParameterTypeRequiredDescription
student_idstringYesUUID of the student
limitintegerNoNumber of recommendations (default: 20)
offsetintegerNoPagination offset (default: 0)

​
Response

{
  "recommendations": [
    {
      "school_id": "456e7890-e89b-12d3-a456-426614174000",
      "name": "Example University",
      "match_score": 0.875,
      "match_grade": "A",
      "match_reasons": [
        "Strong academic fit",
        "Within your budget",
        "Preferred location"
      ],
      "components": {
        "academic": 0.92,
        "financial": 0.85,
        "campus": 0.88,
        "outcomes": 0.82
      }
    }
  ],
  "metadata": {
    "total_count": 150,
    "learning_phase": "refinement",
    "algorithm_version": "2.1.0"
  }
}

​
Record Swipe

Record a student’s interaction with a school recommendation. 
curl -X POST https://api.findu.app/swipe \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "student_id": "123e4567-e89b-12d3-a456-426614174000",
    "school_id": "456e7890-e89b-12d3-a456-426614174000",
    "direction": "right",
    "interaction_type": "swipe",
    "time_spent": 5.2
  }'

​
Request Body

ParameterTypeRequiredDescription
student_idstringYesUUID of the student
school_idstringYesUUID of the school
directionstringYes”left” (dislike) or “right” (like)
interaction_typestringNoType of interaction (default: “swipe”)
time_spentfloatNoSeconds spent viewing

​
Response

{
  "success": true,
  "swipe_count": 25,
  "learning_phase": "refinement",
  "ui_message": "Getting better at finding your matches!"
}

​
Get Match Details

Get detailed match information between a student and school. 
curl -X GET "https://api.findu.app/match/123e4567-e89b-12d3-a456-426614174000/456e7890-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Response

{
  "overall_score": 0.875,
  "grade": "A",
  "components": {
    "academic": {
      "score": 0.92,
      "factors": {
        "sat_match": 0.95,
        "selectivity_fit": 0.88,
        "program_strength": 0.93
      }
    },
    "financial": {
      "score": 0.85,
      "factors": {
        "affordability": 0.82,
        "aid_availability": 0.90,
        "value_score": 0.83
      }
    }
  },
  "explanation": "This school is an excellent match based on your academic profile and preferences. The strong engineering program aligns with your interests, and the financial aid package makes it affordable."
}

​
Mobile-Optimized Endpoints

​
Compressed Recommendations

Get recommendations with compressed field names for mobile. 
GET /m/recommendations/{student_id}

​
Response

{
  "r": [
    {
      "i": "456e7890-e89b-12d3-a456-426614174000",
      "n": "Example University",
      "s": 87.5,
      "g": "A",
      "c": "Example City",
      "st": "CA"
    }
  ]
}
Field mappings:
  • i = id
  • n = name
  • s = score
  • g = grade
  • c = city
  • st = state

​
Batch School Fetch

Fetch multiple schools in one request. 
POST /m/batch/schools

​
Request Body

{
  "school_ids": [
    "456e7890-e89b-12d3-a456-426614174000",
    "789a1234-e89b-12d3-a456-426614174000"
  ]
}

​
Minimal Onboarding API

​
Create Minimal Profile

Create a student profile with minimal information. 
POST /v2/onboarding/minimal

​
Request Body

{
  "name": "John Doe",
  "email": "[email protected]",
  "graduation_year": "2024",
  "gpa": 3.8,
  "test_scores": {
    "sat": 1400
  }
}

​
Get Category Schools

Get the 6 archetype schools for preference discovery. 
GET /v2/onboarding/category-schools

​
Response

{
  "categories": [
    {
      "id": "ivy-plus",
      "name": "Ivy Plus",
      "description": "Highly selective research universities",
      "example_school": {
        "name": "Harvard University",
        "image_url": "https://..."
      }
    }
  ]
}

​
Error Handling

​
Error Response Format

{
  "error": {
    "code": "INVALID_STUDENT_ID",
    "message": "Student not found",
    "details": {
      "student_id": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}

​
Common Error Codes

CodeDescription
INVALID_STUDENT_IDStudent ID not found
INVALID_SCHOOL_IDSchool ID not found
MISSING_PROFILEStudent profile incomplete
RATE_LIMITEDToo many requests
INTERNAL_ERRORServer error

​
Rate Limiting

  • Recommendations: 60 requests per minute
  • Swipes: 300 requests per minute
  • Batch operations: 20 requests per minute
Headers: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200

​
Webhooks

​
Swipe Events

Configure webhooks to receive swipe events: 
{
  "event": "swipe.recorded",
  "data": {
    "student_id": "123e4567-e89b-12d3-a456-426614174000",
    "school_id": "456e7890-e89b-12d3-a456-426614174000",
    "direction": "right",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

​
SDK Examples

​
Python

from findu import MatchingClient

client = MatchingClient(api_key="YOUR_API_KEY")

# Get recommendations
recs = client.get_recommendations(
    student_id="123e4567-e89b-12d3-a456-426614174000",
    limit=20
)

# Record swipe
client.record_swipe(
    student_id="123e4567-e89b-12d3-a456-426614174000",
    school_id="456e7890-e89b-12d3-a456-426614174000",
    direction="right"
)

​
TypeScript

import { FindUClient } from '@findu/sdk';

const client = new FindUClient({ apiKey: 'YOUR_API_KEY' });

// Get recommendations
const recs = await client.recommendations.get({
  studentId: '123e4567-e89b-12d3-a456-426614174000',
  limit: 20
});

// Record swipe
await client.swipes.record({
  studentId: '123e4567-e89b-12d3-a456-426614174000',
  schoolId: '456e7890-e89b-12d3-a456-426614174000',
  direction: 'right'
});