Add Block Time¶

Block a time slot for a doctor at a specific clinic, preventing appointments from being scheduled during that window. Supports one-off and recurring blocks.

Endpoint¶

POST /v1/doctor-block

Request Body¶

Parameter	Type	Required	Description
`doctor_id`	integer	Yes	Doctor to block
`clinic_id`	integer	Yes	Clinic at which the block applies
`starts_at`	string (datetime)	Yes	Block start as ISO-8601 UTC datetime (`2025-07-24T09:00:00`)
`ends_at`	string (datetime)	Yes	Block end as ISO-8601 UTC datetime (`2025-07-24T10:00:00`)
`block_reason`	string	No	Reason for the block (see Block Reason Values)
`block_date`	string (date)	No	Specific date for a non-recurring block (`YYYY-MM-DD`)
`slot_start_time`	string	No	Slot start time in `HH:mm` format (e.g., `09:00`)
`slot_end_time`	string	No	Slot end time in `HH:mm` format (e.g., `10:00`)
`recurrence_frequency`	string	No	Recurrence pattern (see Recurrence Values); defaults to `NON_RECURRENT`
`days_of_occurrence`	array	No	Day integers for recurring blocks (1=Monday … 7=Sunday); required for `WEEKLY`, `BIWEEKLY`, and `MONTHLY`
`interval_count`	integer	No	How many recurrence units between occurrences (default: `1`)
`comments`	string	No	Free-text note about the block
`doctor_ids`	array	No	Additional doctor IDs to apply the same block to

Request¶

curl --location '{base_url}/v1/doctor-block' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "doctor_id": 485195,
    "clinic_id": 44,
    "starts_at": "2025-07-24T09:00:00",
    "ends_at": "2025-07-24T10:00:00",
    "block_reason": "LUNCH",
    "comments": "Team lunch"
  }'

Request Examples¶

One-Off Block¶

{
  "doctor_id": 485195,
  "clinic_id": 44,
  "starts_at": "2025-07-24T09:00:00",
  "ends_at": "2025-07-24T10:00:00",
  "block_reason": "LUNCH",
  "comments": "Team lunch"
}

Weekly Recurring Block (every Monday and Wednesday)¶

{
  "doctor_id": 485195,
  "clinic_id": 44,
  "starts_at": "2025-07-28T12:00:00",
  "ends_at": "2026-07-28T13:00:00",
  "block_reason": "STAFF_MEETING",
  "recurrence_frequency": "WEEKLY",
  "days_of_occurrence": [1, 3],
  "interval_count": 1,
  "comments": "Weekly Monday and Wednesday staff meeting"
}

Response¶

Success Response¶

Code: 200 OK

Returns a list of all blocks created (one per occurrence for recurring blocks).

{
  "code": 2000,
  "data": [
    {
      "doctor_blocking_schedule_id": 10045,
      "doctor_id": 485195,
      "clinic_id": 44,
      "block_reason": "LUNCH",
      "starts_at": "2025-07-24T09:00:00",
      "ends_at": "2025-07-24T10:00:00",
      "block_date": "2025-07-24",
      "slot_start_time": "09:00",
      "slot_end_time": "10:00",
      "recurrence_frequency": "NON_RECURRENT",
      "days_of_occurrence": null,
      "interval_count": 1,
      "block_identifier": "uuid-abc-123",
      "block_status": "ACTIVE",
      "comments": "Team lunch",
      "created_at": "2025-05-19T08:00:00"
    }
  ],
  "message": "Success"
}

Response Fields¶

Field	Type	Description
`doctor_blocking_schedule_id`	integer	Unique ID of this block entry
`doctor_id`	integer	Doctor the block applies to
`clinic_id`	integer	Clinic the block applies to
`block_reason`	string	Reason code for the block
`starts_at`	string (datetime)	Block start datetime (UTC)
`ends_at`	string (datetime)	Block end datetime (UTC)
`block_date`	string (date)	Calendar date of this block occurrence
`slot_start_time`	string	Slot start time (`HH:mm`)
`slot_end_time`	string	Slot end time (`HH:mm`)
`recurrence_frequency`	string	Recurrence pattern
`days_of_occurrence`	array	Days of the week for recurring blocks
`interval_count`	integer	Interval between occurrences
`block_identifier`	string	Shared UUID linking all occurrences of a recurring block
`block_status`	string	Current status (`ACTIVE`, `DELETED`)
`comments`	string	Free-text note
`created_at`	string (datetime)	When the block was created

Error Response¶

Code: 400 Bad Request

{
  "code": 4000,
  "message": "Doctor not found",
  "data": null
}

Block Reason Values¶

Value	Description
`VACATION`	Vacation
`LUNCH`	Lunch break
`MEAL_BREAK`	Meal break
`REST_BREAK`	Rest break
`OUT_OF_OFFICE`	Out of office
`STAFF_MEETING`	Staff meeting
`MEETING`	General meeting
`PUBLIC_HOLIDAY`	Public holiday
`HOLIDAY`	Holiday
`SICK_LEAVE`	Sick leave
`CONTINUING_EDUCATION`	Continuing education
`TRAINING`	Training
`ADMIN`	Administrative tasks
`TRAVEL`	Travel
`CALL_OUT`	Called out
`CONSULTING`	Consulting
`WORKSHOP`	Workshop
`VTO`	Voluntary time off
`OTHER`	Other reason

Recurrence Values¶

Value	Description
`NON_RECURRENT`	Single occurrence (default)
`DAILY`	Repeats every N days
`WEEKLY`	Repeats on specified days of the week every N weeks
`BIWEEKLY`	Repeats on specified days every 2 weeks
`MONTHLY`	Repeats on specified days of the month every N months

Notes¶

For WEEKLY and BIWEEKLY recurrence, days_of_occurrence integers map to ISO weekday numbers: 1 = Monday, 7 = Sunday.
All recurring occurrences share the same block_identifier, which is used for bulk modification and bulk deletion.
Use interval_count > 1 to skip intervals (e.g., interval_count: 2 with WEEKLY = every other week).