> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syncline.run/llms.txt
> Use this file to discover all available pages before exploring further.
# Smart Ranking
> How Syncline ranks time slots by quality
## The Problem
Most scheduling tools just show "available times" chronologically. The first free slot might be:
* 6am for someone in a different timezone
* During lunch hour
* Friday at 5pm
* Technically free, but terrible
**Syncline solves this.** We rank slots by **quality**, not chronology.
## How It Works
Every time slot gets a **score** from 0 to 1, where higher scores indicate better matches for all attendees. Our algorithm considers multiple factors to find times that work well for everyone.
### Key Factors
#### Timezone Fairness
**Goal**: No one should have awkward meeting times.
We ensure meeting times fall within reasonable working hours for all attendees. If a time would be too early or too late for anyone, it gets significantly penalized.
**Example**:
* Alice (PST): 10am = ✓ Good
* Bob (EST): 1pm = ✓ Good
* **Result**: High score
**Bad Example**:
* Alice (PST): 7am = ❌ Too early
* Bob (EST): 10am = ✓ Good
* **Result**: Low score
Timezone fairness is our most important factor. We prioritize times that work for everyone.
#### Time-of-Day Preferences
**Goal**: Schedule at times when people are most receptive.
Research and data show certain times of day work better for most professionals. We boost scores for these optimal windows while penalizing less ideal times.
**Why this matters**: Morning meetings typically have higher acceptance rates than late afternoon meetings.
#### Day-of-Week Patterns
**Goal**: Respect common work patterns.
People tend to protect certain days or times for focused work. Our algorithm recognizes these patterns and adjusts scores accordingly.
**Example**: Many professionals prefer to keep Friday afternoons meeting-free for wrapping up the week.
#### Meeting Urgency
**Goal**: Balance urgency with quality.
For time-sensitive meetings, we boost scores for nearer-term slots. For less urgent meetings, we prioritize optimal times even if they're further out.
**Why this matters**: Momentum matters for introductions and urgent discussions.
## Putting It Together
### Example Comparison
| Time | Score | Why |
| -------- | --------- | --------------------------------------------- |
| Tue 10am | Excellent | Ideal time, mid-week, good for both timezones |
| Wed 2pm | Good | Solid afternoon slot, this week |
| Fri 3pm | Fair | Friday afternoon, less ideal |
| Mon 12pm | Fair | Lunch hour, some inconvenience |
| Sat 10am | Poor | Weekend (if not enabled) |
## User Preferences
The base algorithm applies to everyone, but individual preferences take priority:
If you set "9am-5pm Mon-Fri," we only suggest times within that window.
This completely overrides our default recommendations.
If you set a 15-minute buffer, we exclude slots that would create back-to-back meetings.
Prevents scheduling fatigue.
If you set "max 5 meetings/day," we stop suggesting slots once that limit is reached.
Protects against meeting overload.
## Why This Matters
**Without smart ranking:**
* 40% of suggested times get rejected
* Requires multiple back-and-forth rounds
* Wastes time and frustrates users
**With smart ranking:**
* 85% of first suggestions accepted
* One-shot scheduling
* Happy users, efficient workflows
## Integration
### Using the API
The algorithm runs automatically when you request availability:
```bash theme={null}
curl -X POST https://api.syncline.run/v1/availability \
-H "X-API-Key: sk_live_..." \
-d '{
"attendees": ["alice@example.com", "bob@example.com"],
"duration_minutes": 30
}'
```
**Response includes**:
* `score`: Quality rating for each slot (0-1)
* `reason`: Human-readable explanation
* Slots automatically sorted by score (best first)
### Understanding Scores
* **0.9-1.0**: Excellent match, highly recommended
* **0.7-0.9**: Good match, solid choice
* **0.5-0.7**: Fair match, acceptable
* **0.3-0.5**: Poor match, avoid if possible
* **0.0-0.3**: Very poor match, last resort
### Best Practices
**1. Trust the Rankings**
```javascript theme={null}
// Use the first slot - it's ranked best for a reason
const bestSlot = availability.slots[0];
await syncline.schedule({
attendees: [...],
start_time: bestSlot.time
});
```
**2. Provide Context**
```javascript theme={null}
// Help us understand the meeting type
await syncline.findAvailability({
attendees: [...],
meeting_context: 'investor_pitch', // Affects ranking
duration_minutes: 60
});
```
**3. Set User Preferences**
```javascript theme={null}
// Let users control their scheduling preferences
await syncline.updatePreferences({
work_hours: { start: 9, end: 17 },
buffer_minutes: 15,
max_meetings_per_day: 6
});
```
## Continuous Improvement
Our algorithm gets smarter over time by learning from:
* Meeting acceptance rates
* Reschedule patterns
* User feedback
* Seasonal trends
The more your users interact with Syncline, the better the recommendations become.
## Testing the Algorithm
Try it yourself and see the scoring in action:
```bash theme={null}
curl -X POST https://api.syncline.run/v1/availability \
-H "X-API-Key: sk_live_..." \
-d '{
"attendees": ["alice@example.com", "bob@example.com"],
"duration_minutes": 30,
"search_window_days": 7
}'
```
Look at the `score` field in each slot. The algorithm automatically sorts slots with highest scores first.
## Next Steps
See the algorithm in action
Full endpoint documentation
Customize scoring behavior
How we improve over time