Reservations

Create reservation

Creates a new reservation to grant temporary access to specific channels for a person.
The start and end times must fall on the same day in the account's time zone.
Automatically creates a role and shift for the reservation period.

POST /api/3/reservations

Authentication

This endpoint requires authentication:

OAuth 2.0 Recommended

Use an OAuth 2.0 access token in the Authorization header. This is the recommended authentication method for all integrations. OAuth provides automatic token expiration, granular permission scopes, detailed usage tracking, and per-integration revocation. Learn how to obtain an access token.

Header Format:

Authorization: Bearer YOUR_ACCESS_TOKEN

Required Scopes:

account.reservation

Request Body

person_id integer
Required

ID of the person to grant temporary access (must belong to the same account)

start_time string
Required

Start time of the reservation

end_time string
Required

End time of the reservation (must be after start time and on the same day in account time zone)

channel_ids array
Optional

Array of channel IDs to grant access to (at least one required, all must be accessible to the creator)

door_controller_ids array
Optional

Alias for channel_ids

Example

{
  "person_id": 12345,
  "start_time": "2024-01-15T09:00:00.000Z",
  "end_time": "2024-01-15T17:00:00.000Z",
  "channel_ids": [
    0
  ],
  "door_controller_ids": [
    0
  ]
}

Responses

201

Reservation created successfully

Response Fields

id integer required

Unique identifier for the reservation

eg. 789
person_id integer required

ID of the person granted temporary access

eg. 12345
start_time string required

Start time of the reservation

eg. 2024-01-15T09:00:00.000Z
end_time string required

End time of the reservation (must be after start time and on the same day)

eg. 2024-01-15T17:00:00.000Z
channel_ids array<integer> required

Array of channel (door controller) IDs the person has access to during this reservation

eg. [1340, 1341]
created_at string required

Timestamp of creation

updated_at string required

Timestamp of last update

401

Unauthorized - Invalid or missing authentication

Response Fields

error string
eg. unauthorized
error_description string
eg. The access token is invalid
403

Forbidden - User does not have permission

Response Fields

error string
eg. forbidden
error_description string
eg. You are not authorized to access this resource
422

Unprocessable Entity - Validation failed

Response Fields

error string

Error message

errors object

Field-specific validation errors

Show child attributes
value array
eg. ["value is already in use on your account", "must be between 4 and 7 digits in length"]

Validation errors for the credential value

credential_type_id array
eg. ["Not found for this account"]

Validation errors for the credential type

limit_reached string
eg. You have reached your HID Mobile licence limit. Please contact DoorFlow Support.

License limit error message

500

Internal Server Error

Response Fields

error string
eg. internal_server_error
error_description string
eg. An unexpected error occurred

Mentioned in Guides

This endpoint is used in the following guides:

Visitor Management Workflow

Grant temporary access to visitors with time-limited PINs in 7 minutes

Common Workflows • 7 min • Intermediate

Contractor Temporary Access

Grant time-limited access to contractors for weeks or months in 5 minutes

Common Workflows • 5 min • Intermediate

Request

curl -X POST \
  "https://api.doorflow.com/api/3/reservations" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"person_id":12345,"start_time":"2024-01-15T09:00:00.000Z","end_time":"2024-01-15T17:00:00.000Z","channel_ids":[0],"door_controller_ids":[0]}'

Responses

Reservation created successfully

{
  "id": 789,
  "person_id": 12345,
  "start_time": "2024-01-15T09:00:00.000Z",
  "end_time": "2024-01-15T17:00:00.000Z",
  "channel_ids": [
    0
  ],
  "created_at": "string",
  "updated_at": "string"
}