Find Mutual Availability

Find time slots where all attendees are available

POST /v1/availability

Find Mutual Availability

cURL

curl --request POST \
  --url https://api.example.com/v1/availability \
  --header 'Content-Type: application/json' \
  --data '
{
  "attendees": [
    "<string>"
  ],
  "duration_minutes": 123,
  "date_range": {
    "start_date": "<string>",
    "end_date": "<string>"
  },
  "context": "<string>"
}
'

200

{
  "slots": [
    {
      "start_time": "<string>",
      "end_time": "<string>",
      "score": 123,
      "timezone": "<string>",
      "reason": "<string>"
    }
  ],
  "total_found": 123,
  "search_window": {
    "start": "<string>",
    "end": "<string>",
    "days": 123
  }
}

Endpoint

POST https://api.syncline.run/v1/availability

Request Body

attendees · string[] · required

Array of email addresses. Must be exactly 2 for MVP.

["[e-mail]", "[e-mail]"]

duration_minutes · integer · default: 30

Meeting duration in minutes. Min: 15, Max: 120.

date_range · object

Optional custom date range. Defaults to user’s availability_window_days preference (14 days).

Show properties

start_date · string

ISO 8601 date: 2025-11-20

end_date · string

ISO 8601 date: 2025-12-04

context · string

Optional meeting context for better title generation.

Example: "Introduction call after LinkedIn connection"

Response

slots · TimeSlot[]

Array of 5 time slots, ranked by quality (best first).

Show TimeSlot properties

start_time · string

ISO 8601 datetime with timezone

end_time · string

ISO 8601 datetime with timezone

score · number

Quality score (0-1). Higher = better match.

timezone · string

Requester’s timezone (e.g., America/Los_Angeles)

reason · string

Human-readable explanation of why this slot scored well

total_found · integer

Total number of slots found (always 5 or less)

search_window · object

Date range searched

Show properties

start · string

Start date in ISO 8601 format

end · string

End date in ISO 8601 format

days · integer

Number of days in window

Example Request

cURL

curl -X POST https://api.syncline.run/v1/availability \
  -H "X-API-Key: sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "attendees": ["[e-mail]", "[e-mail]"],
    "duration_minutes": 30,
    "context": "Introductory call"
  }'

Example Response

{
  "slots": [
    {
      "start_time": "2025-11-20T10:00:00-08:00",
      "end_time": "2025-11-20T10:30:00-08:00",
      "score": 0.95,
      "timezone": "America/Los_Angeles",
      "reason": "Mid-morning, optimal timezone for both attendees"
    },
    {
      "start_time": "2025-11-21T10:30:00-08:00",
      "end_time": "2025-11-21T11:00:00-08:00",
      "score": 0.93,
      "timezone": "America/Los_Angeles",
      "reason": "Mid-morning, excellent availability"
    },
    {
      "start_time": "2025-11-20T14:00:00-08:00",
      "end_time": "2025-11-20T14:30:00-08:00",
      "score": 0.82,
      "timezone": "America/Los_Angeles",
      "reason": "Early afternoon, good match"
    },
    {
      "start_time": "2025-11-22T11:00:00-08:00",
      "end_time": "2025-11-22T11:30:00-08:00",
      "score": 0.80,
      "timezone": "America/Los_Angeles",
      "reason": "Late morning, acceptable for both"
    },
    {
      "start_time": "2025-11-20T16:00:00-08:00",
      "end_time": "2025-11-20T16:30:00-08:00",
      "score": 0.75,
      "timezone": "America/Los_Angeles",
      "reason": "Late afternoon, available but not ideal"
    }
  ],
  "total_found": 5,
  "search_window": {
    "start": "2025-11-15",
    "end": "2025-11-29",
    "days": 14
  }
}

Error Responses

Invalid Attendees

{
  "error": {
    "code": "invalid_attendees",
    "message": "Attendee list must contain exactly 2 email addresses",
    "field": "attendees"
  }
}

Status: 400 Bad Request

User Not Found

{
  "error": {
    "code": "user_not_found",
    "message": "User [e-mail] has not connected their calendar",
    "field": "attendees",
    "email": "[e-mail]"
  }
}

Status: 404 Not Found

Solution: User must complete OAuth flow at syncline.run

No Availability Found

{
  "slots": [],
  "total_found": 0,
  "search_window": {
    "start": "2025-11-15",
    "end": "2025-11-29",
    "days": 14
  },
  "message": "No mutual availability found in 14-day window"
}

Status: 200 OK

Note: This is not an error. Try expanding the date range or adjusting preferences.

How Slots Are Ranked

Syncline uses a smart ranking algorithm with 5 factors:

1. Timezone Fairness

Avoids times outside 8am-6pm for either person.

Score impact: 0.5x penalty for awkward hours

2. Mid-Morning Bonus

10am is the ideal meeting time for most professionals.

Score impact: 1.2x boost for 10am slots

3. Friday Afternoon Penalty

People protect Friday afternoons for focus work.

Score impact: 0.7x penalty after 2pm on Fridays

4. Lunch Hour Penalty

Noon-1pm is typically reserved for lunch.

Score impact: 0.8x penalty for 12pm-1pm

5. Recency Bonus

Sooner is better—momentum matters for intros.

Score impact: 1.1x boost for slots within 3 days

Final score = Base (1.0) × All factors

Learn more: Smart Ranking Explained

Best Practices

Always use the first slot. It’s ranked highest for a reason. Only offer alternatives if user explicitly requests them.

Cache results for 5 minutes. Availability doesn’t change that fast. Reduces API calls.

Show timezone to user. Even though Syncline handles conversion, transparency builds trust.

Next Steps

Schedule Meeting

Book one of the available slots

Smart Ranking

Deep dive into the ranking algorithm