Skip to main content
POST
/
api
/
time-blocks
Create Time Block
curl --request POST \
  --url https://api.example.com/api/time-blocks \
  --header 'Content-Type: application/json' \
  --data '
{
  "doctorId": 123,
  "startTime": "<string>",
  "endTime": "<string>"
}
'
{
  "id": 123,
  "doctorId": 123,
  "startTime": "<string>",
  "endTime": "<string>",
  "date": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>"
}
Create a new time block to define doctor availability.

​
Authentication

Requires JWT authentication via Bearer token. Required Header: 
Authorization: Bearer <token>

​
Authorization

Allowed roles:
  • doctor - Can create time blocks for themselves (doctorId auto-assigned)
  • admin - Can create time blocks for any doctor (must specify doctorId)

​
Request Body

​
doctorId
integer
required
The ID of the doctor for this time block.
  • Required for ADMIN role - Must be a positive integer
  • Forbidden for DOCTOR role - Automatically set to authenticated doctor’s ID
​
startTime
string
required
Start time of the availability block in ISO 8601 format.Format: YYYY-MM-DDTHH:mm:ss.sssZExample: 2026-03-15T09:00:00.000Z
​
endTime
string
required
End time of the availability block in ISO 8601 format.Format: YYYY-MM-DDTHH:mm:ss.sssZValidation: Must be greater than startTimeExample: 2026-03-15T10:00:00.000Z

​
Response

​
id
integer
Unique identifier for the time block
​
doctorId
integer
ID of the doctor who owns this time block
​
startTime
string
Start time in ISO 8601 format
​
endTime
string
End time in ISO 8601 format
​
date
string
Creation date/timestamp
​
createdAt
string
Record creation timestamp
​
updatedAt
string
Last update timestamp

​
Error Responses

​
400 Bad Request

Validation errors: 
{
  "error": "Validation failed",
  "details": [
    "startTime must be a valid ISO 8601 date",
    "endTime must be greater than startTime"
  ]
}

​
401 Unauthorized

Missing or invalid authentication token: 
{
  "error": "Unauthorized"
}

​
403 Forbidden

Insufficient permissions (not doctor or admin): 
{
  "error": "Forbidden"
}

​
409 Conflict

Duplicate time block (same doctorId, startTime, and endTime): 
{
  "error": "Time block already exists"
}

​
Example Request

​
As Doctor

curl -X POST https://api.example.com/api/time-blocks \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": "2026-03-15T09:00:00.000Z",
    "endTime": "2026-03-15T10:00:00.000Z"
  }'

​
As Admin

curl -X POST https://api.example.com/api/time-blocks \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "doctorId": 5,
    "startTime": "2026-03-15T09:00:00.000Z",
    "endTime": "2026-03-15T10:00:00.000Z"
  }'

​
Example Response

{
  "id": 42,
  "doctorId": 5,
  "startTime": "2026-03-15T09:00:00.000Z",
  "endTime": "2026-03-15T10:00:00.000Z",
  "date": "2026-03-03T10:30:00.000Z",
  "createdAt": "2026-03-03T10:30:00.000Z",
  "updatedAt": "2026-03-03T10:30:00.000Z"
}

​
Notes

  • The database enforces a unique constraint on the combination of doctorId, startTime, and endTime
  • Time blocks with the same doctor and exact same time range cannot be created
  • Doctors can only create time blocks for themselves; admins can create for any doctor
  • All times must be in ISO 8601 format with timezone information

Build docs developers (and LLMs) love

Get started for freeTalk to us