> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.nowbookit.com/llms.txt
> Use this file to discover all available pages before exploring further.
# POST /Reservations
> Create a schedule-validated reservation in NowBookIt from an external system such as a POS.
Create a reservation in NowBookIt from your POS or external system. Use this endpoint when a customer has made a pre-booked reservation — it validates against NowBookIt's live schedule and the booking appears in the diary exactly as it would if the customer had booked online.
For walk-ins, use `POST /Bookings` instead — that endpoint seats guests immediately without enforcing availability rules.
Call `GET /Bookings/schedule` first to retrieve available services for the desired time and pax. The `serviceId` from that response is required here.
**Booking vs Reservation**
| | POST /Bookings | POST /Reservations |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| NBI backend path | `bookings/new` (walk-in) | `bookings` (online booking) |
| Treated as | Walk-in | Online reservation |
| Schedule/availability enforcement | No — service is resolved if `serviceId` is provided but availability and capacity rules are not enforced. Booking is created regardless. | Yes — service must exist and have open availability for the requested time and pax |
| `serviceId` | Optional | Required |
| `sectionId` | Optional | Required |
| Customer | Optional (defaults to "Walkins") | Required (firstName, lastName, phone) |
| Use case | POS walk-ins | Pre-booked reservations |
Your API key
Must be `application/json`
Number of guests (minimum 1)
NowBookIt service ID. Retrieve from `GET /Bookings/schedule` for the target date and pax.
NowBookIt section ID
Customer details. `firstName`, `lastName`, and `phone` are required.
UTC datetime. Takes precedence over `time`. Format: `yyyy-MM-ddTHH:mm:ssZ`
Venue local datetime. Ignored if `bookingTimeAsUtc` is present. Format: `yyyy-MM-dd HH:mm`
Booking status. Must be a valid status from `GET /resources/booking-statuses`. Defaults to `Unconfirmed`.
External booking ID from your system
Booking notes visible in NowBookIt
Duration in minutes. Overrides the service default.
Staff member ID
Staff member name
NowBookIt table IDs. Retrieve from `GET /Bookings/tables`.
Additional links: `[{ linkName, linkURL }]`
```shell curl theme={null}
curl --location '[BASE_URL]/Reservations' \
--header 'X-API-KEY: your_api_key_here' \
--header 'Content-Type: application/json' \
--data '{
"bookingTimeAsUtc": "2024-03-20T19:00:00Z",
"numOfPeople": 4,
"serviceId": "svc-101",
"sectionId": "sec-1",
"customer": {
"firstName": "Jane",
"lastName": "Smith",
"phone": "+61412345678",
"email": "jane.smith@example.com"
},
"notes": "Anniversary dinner, window table preferred",
"duration": 90
}'
```
| Status | Description |
| ------ | --------------------------------------------------------------------------------------------------- |
| `201` | Reservation created |
| `400` | `No Venue Subscribed to your App.` |
| `400` | `Invalid booking status {status}` — query `GET /resources/booking-statuses` for valid values |
| `400` | `No service available for booking time '{bookingTime}' and Pax '{numOfPeople}'` — no schedule match |
| `400` | `Invalid Service '{serviceId}'` — serviceId not in available schedule |
| `400` | `Invalid Booking Time passed in the payload.` |
| `400` | `A reservation request must contain 'ServiceId'` |
| `400` | `A reservation request must contain 'SectionId'` |
| `400` | `Customer FirstName, LastName and Phone are required.` |
| `401` | X-API-KEY missing or invalid |
| `500` | `An error occurred. Unable to create new reservation.` |
## OpenAPI
````yaml POST /Reservations
openapi: 3.0.4
info:
title: NowBookIt IPOS Partner API
description: >-
REST API for integrating your POS or external system with NowBookIt's
reservation, sales, and gift card platform.
version: v1
contact:
email: platform.integrations@nowbookit.com
servers:
- url: https://ipos.dev.nowbookit.com
description: Development
- url: https://ipos.nowbookit.com
description: Production
security:
- ApiKeyAuth: []
paths:
/Reservations:
post:
tags:
- Reservations
summary: Create Reservation
operationId: createReservation
parameters:
- name: X-API-KEY
in: header
description: API Key authentication header
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBookingRequest'
responses:
'201':
description: Create new Reservation from API
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBookingResponse'
'400':
description: Incorrect request Payload
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationProblemDetails'
'500':
description: An error occurred when creating a new reservation.
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
security:
- ApiKeyAuth: []
components:
schemas:
CreateBookingRequest:
required:
- numOfPeople
type: object
properties:
time:
type: string
description: >-
Booking Date and time in Venue's Timezone. Valid Format: 'yyyy-MM-dd
HH:mm'
nullable: true
bookingTimeAsUtc:
type: string
description: >-
Booking Date and time in UTC Timezone. Valid Format:
'yyyy-MM-ddTHH:mm:ssZ'
nullable: true
numOfPeople:
maximum: 2147483647
minimum: 1
type: integer
description: The number of guests on booking.
format: int32
bookingId:
type: string
nullable: true
serviceId:
type: string
nullable: true
sectionId:
type: string
nullable: true
customer:
$ref: '#/components/schemas/Customer'
notes:
type: string
nullable: true
tables:
type: array
items:
type: string
description: Nominate NBI Table Ids for this Booking.
nullable: true
links:
type: array
items:
$ref: '#/components/schemas/Data'
nullable: true
status:
type: string
nullable: true
duration:
type: integer
description: The Booking duration in Minutes.
format: int32
nullable: true
staffId:
type: string
nullable: true
staffName:
type: string
nullable: true
additionalProperties: false
CreateBookingResponse:
type: object
properties:
bookingId:
type: string
description: The new NBI Booking Id.
nullable: true
time:
type: string
description: The Booking Date and Time.
format: date-time
numOfPeople:
type: integer
format: int32
bookingStatus:
type: string
nullable: true
duration:
type: integer
format: int32
tableNames:
type: array
items:
type: string
nullable: true
serviceId:
type: string
nullable: true
serviceName:
type: string
nullable: true
sectionId:
type: string
nullable: true
isSuccess:
type: boolean
errorMessage:
type: string
nullable: true
additionalProperties: false
ValidationProblemDetails:
type: object
properties:
type:
type: string
nullable: true
title:
type: string
nullable: true
status:
type: integer
format: int32
nullable: true
detail:
type: string
nullable: true
instance:
type: string
nullable: true
errors:
type: object
additionalProperties:
type: array
items:
type: string
nullable: true
additionalProperties: {}
ProblemDetails:
type: object
properties:
type:
type: string
nullable: true
title:
type: string
nullable: true
status:
type: integer
format: int32
nullable: true
detail:
type: string
nullable: true
instance:
type: string
nullable: true
additionalProperties: {}
Customer:
type: object
properties:
id:
type: string
description: The NBI Customer unique Id.
nullable: true
firstName:
type: string
nullable: true
lastName:
type: string
nullable: true
company:
type: string
nullable: true
email:
type: string
nullable: true
phone:
type: string
description: Phone including international code.
nullable: true
address:
$ref: '#/components/schemas/Address'
additionalProperties: false
Data:
type: object
properties:
linkName:
type: string
nullable: true
linkURL:
type: string
nullable: true
additionalProperties: false
Address:
type: object
properties:
line1:
type: string
nullable: true
line2:
type: string
nullable: true
city:
type: string
nullable: true
state:
type: string
nullable: true
postalCode:
type: string
nullable: true
country:
type: string
nullable: true
additionalProperties: false
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
````