> ## Documentation Index
> Fetch the complete documentation index at: https://docs.novacal.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Book Event

> Book a new Novacal event with the public API by sending the event type, selected time, attendee answers, timezone, and location data.

This endpoint requires a public API bearer token.

The authenticated API key identifies the caller integration. The event booker is still created from the submitted booking payload, for example `form_field_answers.name` and `form_field_answers.email`.

## When to use this endpoint

Use this endpoint when you want to create a new booking from your own product, widget, or backend workflow.

Common use cases include:

* Creating a booking after a customer selects a time in your app
* Passing attendee answers collected in a custom booking flow
* Saving the selected timezone and meeting location in the same request

## Authentication notes

This route uses a public API bearer token. The token authenticates your integration, while the attendee details still come from the booking payload you submit.


## OpenAPI

````yaml POST /v1/events
openapi: 3.1.0
info:
  title: Events API
  description: Public API for managing event types
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.novacal.io
security:
  - bearerAuth: []
paths:
  /v1/events:
    post:
      description: >-
        Books a new event. This endpoint requires public API authentication. The
        authenticated token identifies the caller, while the booker is created
        from the submitted booking payload.
      requestBody:
        description: Event booking payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPublicEventBooking'
        required: true
      responses:
        '201':
          description: Event booked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
components:
  schemas:
    NewPublicEventBooking:
      type: object
      required:
        - event_type_id
        - start
        - end
        - timezone
        - time_format
      properties:
        event_type_id:
          description: The ID of the event type being booked
          type: integer
        start:
          description: The requested event start date and time
          type: string
          format: date-time
        end:
          description: The requested event end date and time
          type: string
          format: date-time
        timezone:
          description: The booker's timezone
          type: string
        time_format:
          description: The booker's preferred time format
          type: integer
          enum:
            - 12
            - 24
        location:
          description: Optional selected location payload
          type: object
          properties:
            id:
              description: The selected event type location ID
              type: integer
        form_field_answers:
          description: Booking answers such as name, email, and any custom fields
          type: object
          additionalProperties: true
    EventResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          description: Indicates whether the request was successful
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/Event'
    Event:
      type: object
      properties:
        id:
          description: The unique identifier of the event
          type: string
          format: uuid
        start:
          description: The start date and time of the event
          type: string
          format: date-time
        end:
          description: The end date and time of the event
          type: string
          format: date-time
        canceled_at:
          description: The date and time when the event was canceled
          type:
            - string
            - 'null'
          format: date-time
        cancellation_reason:
          description: The reason the event was canceled, if provided
          type:
            - string
            - 'null'
        location:
          description: The location of the event
          type:
            - string
            - 'null'
        form_field_answers:
          description: >-
            Booking form answers keyed by field identifier. Each value contains
            only the submitted answer.
          type: object
          additionalProperties: true
          example:
            name: John Doe
            email: john@example.com
        status:
          description: The status of the event
          type: string
        name:
          description: The name of the event
          type:
            - string
            - 'null'
        organizer:
          description: The organizer attached to the event
          oneOf:
            - $ref: '#/components/schemas/EventHost'
            - type: 'null'
        hosts:
          description: Hosts attached to the event
          type: array
          items:
            $ref: '#/components/schemas/EventHost'
        booker:
          description: The user who booked the event
          oneOf:
            - $ref: '#/components/schemas/EventBooker'
            - type: 'null'
        guests:
          description: Guest email addresses attached to the event
          type: array
          items:
            type: string
            format: email
    EventHost:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        name:
          type:
            - string
            - 'null'
        email:
          type: string
          format: email
        username:
          type:
            - string
            - 'null'
        timezone:
          type:
            - string
            - 'null'
        time_format:
          type:
            - integer
            - 'null'
          enum:
            - 12
            - 24
            - null
        start_of_week:
          type:
            - integer
            - 'null'
          enum:
            - 0
            - 1
            - null
        avatar:
          type:
            - string
            - 'null'
    EventBooker:
      type: object
      properties:
        name:
          type:
            - string
            - 'null'
        email:
          type: string
          format: email
        timezone:
          type:
            - string
            - 'null'
        time_format:
          type:
            - integer
            - 'null'
          enum:
            - 12
            - 24
            - null
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````