LeyApp for Developers

Overview

The API exposes the same verified-lawyer data as leyapp.es: search, public profiles, reviews, availability, and booking intents. Anonymous access works at low rate limits; an API key raises limits and unlocks keyed endpoints and usage analytics.

Quickstart

From zero to a (test) booking intent in four requests. Create a free test key in Dashboard → Developer first.

# 1. Get a test key at leyapp.es/dashboard/developer
export LEYAPP_API_KEY="leyk_test_..."

# 2. Find a lawyer
curl "https://leyapp.es/api/v1/lawyers/search?city=Barcelona&practice_area=immigration" \
  -H "Authorization: Bearer $LEYAPP_API_KEY"

# 3. Check availability (id from step 2)
curl "https://leyapp.es/api/v1/lawyers/<lawyer_id>/availability" \
  -H "Authorization: Bearer $LEYAPP_API_KEY"

# 4. Create a (test) booking intent
curl -X POST "https://leyapp.es/api/v1/bookings/initiate" \
  -H "Authorization: Bearer $LEYAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-1" \
  -d '{"lawyer_id":"<lawyer_id>","date":"<date>","start_time":"09:00:00","end_time":"10:00:00"}'

Authentication

Send your key as a Bearer token on every request:

Authorization: Bearer leyk_...

• Keys come in live (leyk_) and test (leyk_test_) variants and are shown exactly once at creation — store them in a secret manager.
• Never ship a key in client-side code or a public repository. Rotate by creating a new key, deploying it, then revoking the old one (zero downtime).
• Revocation is instant. Lost keys can't be recovered — only replaced.
• MCP tokens (ley_...) authenticate AI assistants on /api/mcp and are not valid on the REST API.

Rate limits

Keyed requests get tier limits (dual window: per-minute burst + per-day quota) with X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. On 429, honor Retry-After and retry with jittered exponential backoff.

New keys start on the free tier. Partner tiers are granted by the LeyApp team — contact us through the support form if your integration needs more headroom. Anonymous requests use separate, lower per-IP limits.

Test mode

Test keys (leyk_test_) behave exactly like live keys — same endpoints, same validation, same response shapes — but nothing real happens: no booking intent is stored, no lawyer is notified, nothing can be confirmed or paid.

Test traffic appears in your dashboard's request log (flagged) but is excluded from daily aggregates. Swap the key for a live one when you ship — no other change needed.

Endpoints

curl "https://leyapp.es/api/v1/lawyers/search?city=Barcelona&practice_area=immigration&language=en" \
  -H "Authorization: Bearer $LEYAPP_API_KEY"

curl "https://leyapp.es/api/v1/lawyers/<lawyerId>" \
  -H "Authorization: Bearer $LEYAPP_API_KEY"

curl "https://leyapp.es/api/v1/lawyers/<lawyerId>/availability" \
  -H "Authorization: Bearer $LEYAPP_API_KEY"

curl "https://leyapp.es/api/v1/lawyers/<lawyerId>/reviews" \
  -H "Authorization: Bearer $LEYAPP_API_KEY"

curl "https://leyapp.es/api/v1/practice-areas" \
  -H "Authorization: Bearer $LEYAPP_API_KEY"

curl "https://leyapp.es/api/v1/cities" \
  -H "Authorization: Bearer $LEYAPP_API_KEY"

{
  "lawyer_id": "<lawyer_id from search>",
  "date": "2026-09-01",
  "start_time": "09:00:00",
  "end_time": "10:00:00",
  "source": "api",
  "agent_name": "MyIntegration"
}

curl -X POST "https://leyapp.es/api/v1/bookings/initiate" \
  -H "Authorization: Bearer $LEYAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lawyer_id":"<lawyer_id from search>","date":"2026-09-01","start_time":"09:00:00","end_time":"10:00:00","source":"api","agent_name":"MyIntegration"}'

curl "https://leyapp.es/api/v1/booking-intents/<intentId>" \
  -H "Authorization: Bearer $LEYAPP_API_KEY"

Webhooks

Subscribe an HTTPS endpoint (Dashboard → Developer → Webhooks) to events for booking intents created with your key. Deliveries follow the Standard Webhooks spec and are retried automatically.

• Events: booking_intent.confirmed / booking_intent.expired (the intent stage), plus the full booking lifecycle for API-originated bookings — booking.approved, booking.cancelled, booking.completed.
• Verify every delivery with the whsec_ signing secret shown once at endpoint creation — the official standardwebhooks libraries do this in one call. Reject timestamps older than ±5 minutes.
• Delivery is at-least-once: dedup by the webhook-id header (also the payload id). Payloads contain IDs and statuses only — fetch details from the API if you need them.

# Delivery headers (Standard Webhooks — standardwebhooks.com):
#   webhook-id:        unique delivery id (dedup key — at-least-once delivery)
#   webhook-timestamp: unix seconds (reject if older than ±5 minutes)
#   webhook-signature: v1,<base64 HMAC-SHA256 of "{id}.{timestamp}.{body}">
#
# Payload: { "id": "...", "type": "booking_intent.confirmed",
#            "created_at": "...", "data": { "booking_intent_id": "...", "status": "..." } }
# Events: booking_intent.confirmed | booking_intent.expired
# Retries: 1m / 5m / 30m / 2h / 12h, then dead. Endpoint auto-disabled
# after 20 consecutive failures.

MCP & AI agents

Prefer talking instead of coding? LeyApp ships an MCP server with 15 tools — search, availability, booking, and (with your consent) your own bookings — for Claude, ChatGPT, Cursor and any MCP-capable client. OAuth consent with granular permission levels; revoke anytime from Dashboard → Developer.

Settings → Connectors → Add custom connector
Name: LeyApp
URL:  https://leyapp.es/api/mcp/mcp

Claude opens the LeyApp consent screen — sign in, pick a
permission level, and you're connected.

Changelog

The v1 API is additive-only: fields are added, never renamed or removed. Breaking changes would ship as a new version with a 90-day deprecation window announced here and via Deprecation/Sunset headers.