> ## 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.

# Create Booking

> Create a new booking at your venue from your POS or external system

<ParamField header="X-API-KEY" type="string" required>
  Your partner API key.
</ParamField>

## Request Body

<ParamField body="time" type="string">
  Booking datetime in the **venue's local timezone**. Format: `yyyy-MM-dd HH:mm`

  Example: `"2024-06-15 19:00"`

  **At least one of `time` or `bookingTimeAsUtc` is required.** Ignored if `bookingTimeAsUtc` is also provided.
</ParamField>

<ParamField body="bookingTimeAsUtc" type="string">
  Booking datetime in **UTC**. Format: `yyyy-MM-ddTHH:mm:ssZ`

  Example: `"2024-06-15T09:00:00Z"`

  **At least one of `time` or `bookingTimeAsUtc` is required.** When provided, this takes precedence over `time`.
</ParamField>

<ParamField body="numOfPeople" type="integer" required>
  Number of guests in the party.
</ParamField>

<ParamField body="serviceId" type="string">
  NowBookIt Service ID to assign this booking to (e.g., `"Dinner"` service). Fetch available services from your NowBookIt venue configuration.
</ParamField>

<ParamField body="sectionId" type="string">
  NowBookIt Section ID (area of the venue, e.g., main floor, terrace).
</ParamField>

<ParamField body="bookingId" type="string">
  Your POS's external booking identifier. Stored in NowBookIt for cross-reference.
</ParamField>

<ParamField body="notes" type="string">
  Free-text booking notes (e.g., dietary requirements, special requests).
</ParamField>

<ParamField body="status" type="string">
  Initial booking status from your POS. See [GET /Resources/booking-statuses](/resources/booking-statuses) for valid values.
</ParamField>

<ParamField body="duration" type="integer">
  Duration of the booking in minutes.
</ParamField>

<ParamField body="staffId" type="string">
  ID of the staff member managing the booking.
</ParamField>

<ParamField body="staffName" type="string">
  Name of the staff member managing the booking.
</ParamField>

<ParamField body="tables" type="array">
  List of NowBookIt Table IDs to assign to this booking. Fetch available table IDs using [GET /Bookings/tables](/bookings/tables).

  Example: `["tbl_001", "tbl_002"]`
</ParamField>

<ParamField body="customer" type="object">
  Guest/customer details.

  <Expandable title="Customer Fields">
    <ParamField body="id" type="string">NowBookIt customer ID (if known).</ParamField>
    <ParamField body="firstName" type="string">Customer first name.</ParamField>
    <ParamField body="lastName" type="string">Customer last name.</ParamField>
    <ParamField body="company" type="string">Company name.</ParamField>
    <ParamField body="email" type="string">Customer email address.</ParamField>
    <ParamField body="phone" type="string">Customer phone number.</ParamField>
    <ParamField body="address" type="string">Customer address.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="links" type="array">
  Optional external links to associate with the booking (e.g., order URLs, reservation links).

  <Expandable title="Link Object">
    <ParamField body="linkName" type="string">Display name for the link.</ParamField>
    <ParamField body="linkURL" type="string">URL.</ParamField>
  </Expandable>
</ParamField>

<Note>
  Either `time` or `bookingTimeAsUtc` is required. If both are provided, `bookingTimeAsUtc` takes precedence.
</Note>

***

## Response

<ResponseField name="bookingId" type="string">
  The NowBookIt-assigned booking ID for the newly created booking.
</ResponseField>

<ResponseField name="time" type="string">
  Confirmed booking time in venue local timezone.
</ResponseField>

<ResponseField name="numOfPeople" type="integer">
  Confirmed party size.
</ResponseField>

<ResponseField name="bookingStatus" type="string">
  Status of the booking after creation.
</ResponseField>

<ResponseField name="duration" type="integer">
  Confirmed duration in minutes.
</ResponseField>

<ResponseField name="tableNames" type="array">
  Names of tables assigned to this booking.
</ResponseField>

<ResponseField name="serviceId" type="string">
  NowBookIt service ID assigned to this booking.
</ResponseField>

<ResponseField name="serviceName" type="string">
  Human-readable service name.
</ResponseField>

<ResponseField name="sectionId" type="string">
  NowBookIt section ID assigned to this booking.
</ResponseField>

<ResponseField name="isSuccess" type="boolean">
  `true` if the booking was created successfully.
</ResponseField>

<ResponseField name="errorMessage" type="string">
  Error detail when `isSuccess` is `false`. `null` on success.
</ResponseField>

***

## Examples

<CodeGroup>
  ```bash Basic booking theme={null}
  curl -X POST https://{base_url}/Bookings \
    -H "X-API-KEY: your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "bookingTimeAsUtc": "2024-06-15T09:00:00Z",
      "numOfPeople": 4,
      "serviceId": "svc_dinner",
      "notes": "Birthday celebration",
      "customer": {
        "firstName": "Jane",
        "lastName": "Smith",
        "email": "jane.smith@example.com",
        "phone": "+61412345678"
      }
    }'
  ```

  ```bash With table assignment theme={null}
  curl -X POST https://{base_url}/Bookings \
    -H "X-API-KEY: your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "bookingTimeAsUtc": "2024-06-15T09:00:00Z",
      "numOfPeople": 2,
      "duration": 90,
      "tables": ["tbl_001"],
      "customer": {
        "firstName": "Tom",
        "lastName": "Jones",
        "email": "tom@example.com"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://{base_url}/Bookings", {
    method: "POST",
    headers: {
      "X-API-KEY": "your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      bookingTimeAsUtc: "2024-06-15T09:00:00Z",
      numOfPeople: 4,
      serviceId: "svc_dinner",
      customer: {
        firstName: "Jane",
        lastName: "Smith",
        email: "jane.smith@example.com",
      },
    }),
  });
  const booking = await response.json();
  console.log("Created booking:", booking.bookingId);
  ```
</CodeGroup>

### Example Response (201)

```json theme={null}
{
  "bookingId": "bk_new123",
  "time": "2024-06-15 19:00",
  "numOfPeople": 4,
  "bookingStatus": "confirmed",
  "duration": 90,
  "tableNames": ["Table 5"],
  "serviceId": "svc_dinner",
  "serviceName": "Dinner",
  "sectionId": null,
  "isSuccess": true,
  "errorMessage": null
}
```

***

## Status Codes

| Code  | Description                                                                    |
| ----- | ------------------------------------------------------------------------------ |
| `201` | Booking created successfully                                                   |
| `400` | Validation error — check `errorMessage` in response or missing required fields |
| `401` | Invalid or missing `X-API-KEY`                                                 |
| `500` | Internal server error                                                          |


## OpenAPI

````yaml POST /Bookings
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:
  /Bookings:
    post:
      tags:
        - Bookings
      summary: Create Booking
      operationId: createBooking
      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 Booking 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 booking.
          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

````