Skip to main content

​
Appointments & Bookings API

Manage legal consultation bookings and appointments in upLegal.

​
Create Booking

Endpoint: POST /api/bookings/create Authentication: Not required (public endpoint for guest bookings) Creates a new booking and generates a MercadoPago payment link.

​
Request Body

​
lawyer_id
string
required
Lawyer’s user ID
​
user_email
string
required
Client’s email address
​
user_name
string
required
Client’s full name
​
scheduled_date
string
required
Appointment date (YYYY-MM-DD format)
​
scheduled_time
string
required
Appointment time (HH:MM format, 24-hour)
​
duration
number
required
Duration in minutes (30, 60, 90, or 120)
​
price
number
required
Price in CLP (minimum 1000)

​
Example Request

{
  "lawyer_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_email": "[email protected]",
  "user_name": "Carlos Rodríguez",
  "scheduled_date": "2026-03-15",
  "scheduled_time": "14:30",
  "duration": 60,
  "price": 30000
}

​
Response

​
success
boolean
Operation success status
​
booking_id
string
Created booking ID (UUID)
​
payment_link
string
MercadoPago checkout URL
​
message
string
Success message

​
Example Response

200 - Success
{
  "success": true,
  "booking_id": "abc123def-4567-89ab-cdef-0123456789ab",
  "payment_link": "https://www.mercadopago.cl/checkout/v1/redirect?pref_id=123456789-abc123",
  "message": "Booking created successfully"
}

​
Error Responses

400 - Missing Fields
{
  "error": "Missing required fields",
  "required": [
    "lawyer_id",
    "user_email",
    "user_name",
    "scheduled_date",
    "scheduled_time",
    "duration",
    "price"
  ]
}
400 - Invalid Duration
{
  "error": "Duration must be 30, 60, 90 or 120 minutes"
}
400 - Invalid Email
{
  "error": "Invalid email format"
}
404 - Lawyer Not Found
{
  "error": "Lawyer not found"
}
409 - Time Slot Taken
{
  "error": "Time slot not available",
  "message": "Este horario ya está reservado. Por favor elige otro."
}

​
Get Booking

Endpoint: GET /api/bookings/:bookingId Authentication: Not required (public endpoint) Retrieve booking details by ID.

​
Path Parameters

​
bookingId
string
required
Booking ID (UUID)

​
Response

​
booking
object
Booking details
​
id
string
Booking ID
​
lawyer_id
string
Lawyer’s user ID
​
user_id
string | null
Client’s user ID (null for guest bookings until payment)
​
user_email
string
Client email
​
user_name
string
Client name
​
scheduled_date
string
Appointment date (YYYY-MM-DD)
​
scheduled_time
string
Appointment time (HH:MM)
​
duration
number
Duration in minutes
​
price
number
Price in CLP
​
status
string
Booking status: pending, confirmed, or cancelled
​
payment_id
string | null
MercadoPago payment ID
​
mercadopago_preference_id
string | null
MercadoPago preference ID
​
confirmed_at
string | null
Confirmation timestamp (ISO 8601)
​
cancelled_at
string | null
Cancellation timestamp (ISO 8601)
​
created_at
string
Creation timestamp (ISO 8601)
​
updated_at
string
Last update timestamp (ISO 8601)
​
lawyer
object
Lawyer information
​
user_id
string
Lawyer’s user ID
​
first_name
string
First name
​
last_name
string
Last name
​
specialties
array
Array of specialties
​
profile_picture_url
string | null
Profile picture URL

​
Example Response

200 - Success
{
  "booking": {
    "id": "abc123def-4567-89ab-cdef-0123456789ab",
    "lawyer_id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": null,
    "user_email": "[email protected]",
    "user_name": "Carlos Rodríguez",
    "scheduled_date": "2026-03-15",
    "scheduled_time": "14:30",
    "duration": 60,
    "price": 30000,
    "status": "pending",
    "payment_id": null,
    "mercadopago_preference_id": "123456789-abc123",
    "confirmed_at": null,
    "cancelled_at": null,
    "created_at": "2026-03-04T10:00:00.000Z",
    "updated_at": "2026-03-04T10:00:00.000Z",
    "lawyer": {
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "first_name": "María",
      "last_name": "González",
      "specialties": ["Derecho Civil", "Derecho de Familia"],
      "profile_picture_url": "https://example.com/avatar.jpg"
    }
  }
}
404 - Not Found
{
  "error": "Booking not found"
}

​
Booking Workflow

  1. Client creates booking via POST /api/bookings/create
  2. System checks availability and prevents double-booking
  3. MercadoPago preference created with payment details
  4. Client redirected to payment using the payment_link
  5. Payment processed by MercadoPago
  6. Webhook notification confirms payment (see Payments API)
  7. Booking confirmed and appointment created
  8. Email notifications sent to both client and lawyer
  9. User account created for guest bookings (if not exists)

​
Booking States

StatusDescription
pendingCreated, awaiting payment
confirmedPayment successful, appointment scheduled
cancelledBooking cancelled

​
Double-Booking Prevention

The system automatically checks for overlapping bookings:
  • Same lawyer
  • Same date
  • Overlapping time slots
  • Only checks pending and confirmed bookings
Time slot calculation includes buffer for appointment duration.

​
Email Notifications

​
Client Confirmation Email

  • Sent to user_email after payment confirmation
  • Includes appointment details
  • Contains magic link for account access
  • Sent from: LegalUp <[email protected]>

​
Lawyer Notification Email

  • Sent to lawyer’s registered email
  • Includes client details and appointment info
  • Link to dashboard
  • Sent from: LegalUp <[email protected]>

​
Auto-Created Appointments

After successful payment, the system automatically creates an appointments record:
  • Links to the booking via booking_id
  • Status set to confirmed
  • Consultation type: paid
  • Contact method: platform
  • Visible in lawyer dashboard

​
RLS Policies

​
Bookings Table

  • SELECT: Public read for booking details by ID
  • INSERT: Service role only (via API endpoint)
  • UPDATE: Service role only (via webhook)
  • DELETE: Not allowed

Build docs developers (and LLMs) love

Get started for freeTalk to us