> ## Documentation Index > Fetch the complete documentation index at: https://developer.meetergo.com/llms.txt > Use this file to discover all available pages before exploring further. # Create appointment booking > Books an appointment with a specified host for a given meeting type and time slot. Returns appointment confirmation details. Availability, working hours and conflicts are validated by default. Authenticate as a member of the meeting type's company (API key plus `x-meetergo-api-user-id`) and set `ignoreAvailability: true` to book outside available hours; anonymous callers cannot use the flag. ## OpenAPI ````yaml /openapi.json post /v4/booking openapi: 3.0.0 info: title: meetergo Platform API description: >- Scheduling, CRM and invoicing in one API: create users, manage availability and bookings, connect calendars, keep contacts and deals in sync, and take an offer through to a paid invoice. version: 3.274.0 contact: {} termsOfService: https://www.meetergo.com/tos/ servers: [] security: [] tags: - name: User V4 description: Create and manage users in your workspace - name: Meeting Type V4 description: Configure meeting templates with durations, buffers, and conferencing - name: availability description: Manage weekly schedules and availability settings - name: Booking V4 description: Create new bookings - name: Booking Availability V4 description: Query available time slots for booking - name: Appointment V4 description: Manage existing appointments - name: Attendee V4 description: Manage attendee details and notes - name: Calendar Connections V4 description: Connect and sync external calendars - name: Signatures V4 description: >- Send PDFs for e-signature and download the signed, eIDAS-grade document (DocuSeal-compatible) - name: WhatsApp V4 description: >- Send and receive WhatsApp messages by phone number and read conversation history - name: One Time Booking Link V4 description: Create single-use booking links - name: availability-exception description: Override availability for specific dates - name: Booking Link V4 description: Configure various booking page types - name: Personal Page V4 description: Manage user profile pages - name: Handoff V4 description: Reassign meetings to other hosts - name: Calendar Auth V4 description: OAuth callbacks for calendar providers - name: CRM Contacts description: >- Create, find, and update the people in your CRM, including their custom data fields - name: CRM Deals description: >- Create, update, and track deals through pipeline stages (incl. per-deal activity history) - name: CRM Pipelines description: Manage pipelines and their stages - name: CRM Tasks description: Tasks on contacts, deals and companies - name: CRM Notes description: Notes on contacts, deals and companies - name: CRM Attachments description: Files attached to contacts, deals and companies - name: CRM Communications description: Logged calls, messages and meetings on contacts, deals and companies - name: CRM Email Sync description: Read the email history synced from connected mailboxes (read-only) - name: Data Fields description: >- Define the custom fields a contact can carry; their `name` is the key used in a contact's additionalData - name: Invoicing Documents description: >- Offers and invoices: create a draft, finalize it into a numbered e-invoice, send it, record payments, and run Mahnwesen - name: Invoicing Products description: Reusable products for invoice line items - name: Invoicing Settings description: Seller details, tax treatment, bank accounts, and number ranges - name: Invoicing Recurring description: >- Recurring schedules, billing runs over completed meetings, buyer prefill, and DATEV export - name: Queue V4 description: Round-robin and queue-based routing (Beta) - name: Queue User Group V4 description: Manage queue user groups (Beta) - name: Meeting Type Template V4 description: Reusable meeting type configurations (Beta) - name: Attendee Pending V4 description: Manage pending attendee approvals (Beta) - name: Provisional Booking V4 description: Manage provisional/unconfirmed bookings (Beta) paths: /v4/booking: post: tags: - Booking V4 summary: Create appointment booking description: >- Books an appointment with a specified host for a given meeting type and time slot. Returns appointment confirmation details. Availability, working hours and conflicts are validated by default. Authenticate as a member of the meeting type's company (API key plus `x-meetergo-api-user-id`) and set `ignoreAvailability: true` to book outside available hours; anonymous callers cannot use the flag. operationId: bookAppointment parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BookingDto' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/BookingResponseDto' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' default: description: '' content: application/json: schema: $ref: '#/components/schemas/BookingResponseDto' security: - ApiUserHeader: [] - JWT: [] - ApiKey: [] components: schemas: BookingDto: type: object properties: attendee: $ref: '#/components/schemas/CreateAttendeeDto' meetingTypeId: type: string description: ID of the meeting type to book. hostIds: description: >- Host IDs for the booking. Required for one-on-one bookings (specific host selection). Optional for round-robin/queue bookings where queueId is provided instead. When sent TOGETHER with `queueId`, these IDs scope the round-robin to a subset of the queue: the backend rotates only among these hosts (used by `?hosts=` subset links). Empty/omitted with `queueId` = the whole queue. type: array items: type: string start: type: string appointmentId: type: string location: type: string locationSelectionContextId: type: string description: Opaque Finder context exchanged immediately before entering booking. maxLength: 128 pattern: /^[A-Za-z0-9_-]+$/ queueId: type: string description: >- required when meeting type has a queue (round-robin / co-host) must be undefined for non-queue meetings (one-to-one / group) if host selection is true, queue id is required if fastest host selection is chosen if hosts selection is true, queue id must be undefined if a specific host is chosen to round-robin within a SUBSET of the queue, send queueId together with the subset `hostIds` (the backend rotates only among those hosts) bookingTargetToken: type: string description: Opaque booking-block audience context from booking info. maxLength: 64 pattern: /^[A-Za-z0-9_-]+$/ channel: allOf: - $ref: '#/components/schemas/MeetingTypeChannel' duration: type: number description: >- Duration in minutes for the booking. Optional. If not provided, uses the meeting type's default duration. If provided, must match either the default duration or one of the allowed durations configured for the meeting type. Primarily needed when meeting type has multiple duration options (allowedDurations). routingFormId: type: string utm: $ref: '#/components/schemas/UtmDto' referrerUrl: type: string maxLength: 2048 sourceChannel: type: string enum: - booking_page - embed - web_widget - whatsapp_agent - phone_agent - form - gbp - manual - business_card ignoreAvailability: type: boolean description: >- Skips availability, working-hours, conflict and group-capacity checks (instant booker, Platform API). Only honored when the caller is authenticated as a member of the meeting type's company, by JWT or by API key plus `x-meetergo-api-user-id`; anonymous bookings have it normalized to false server-side. isTest: type: boolean description: >- Marks the booking as a rehearsal the host made for themselves, so it is excluded from the activation milestone (`firstBookingAt` must only ever come from a real third party). The appointment itself is real: the calendar entry and the confirmation mail are produced exactly as they would be for an invitee, which is the point of the onboarding self-test. Same trust model as `ignoreAvailability`: only honored for authenticated callers from the meeting type's own company, so a public attendee cannot suppress a host's activation by sending the flag. attendeePendingId: type: number description: >- ID of pending attendee that will be deleted after successful booking. This is only needed when "collect during form entry" feature is used. If not provided, a successful booking may show up in pending contacts. paymentId: type: string paymentProvider: description: >- Selected payment provider for this booking. Required when the meeting type has multiple payment providers enabled. If not provided, falls back to the first enabled provider. allOf: - $ref: '#/components/schemas/PaymentProvider' couponCode: type: string description: >- Coupon code for a discount on paid bookings. Validated during payment order creation and re-validated at booking time. maxLength: 32 resourceChannelIds: description: Ids of the resource channel entity type: array items: type: string oneTimeLinkId: type: string description: >- Id of the one time booking link. Required in order to invalidate the booking link, once booking is done bookingProposalId: type: string description: >- The booking proposal the invitee arrived through. Lets the booking pass the proposal's own hold on the chosen slot and consumes the proposal once the booking is made. format: uuid skipNotifications: type: boolean description: Skip sending email notifications to the attendee for this booking phoneOnlyBooking: type: boolean description: >- When true, attendee email is not required and phone becomes the identifier. Requires the meeting type to have `allowPhoneOnlyBooking` enabled in its options. Designed for voice agent / phone scheduling use cases where collecting email from the caller is not viable. icsTitle: type: string description: >- Custom ICS calendar invite title. If provided, overrides the configured meeting type ICS title for this specific booking. Useful for AI-generated titles based on conversation context (e.g., from calgent). maxLength: 200 icsDescription: type: string description: >- Custom ICS calendar invite description. If provided, overrides the configured meeting type ICS description for this specific booking. Useful for AI-generated descriptions based on conversation context (e.g., from calgent). maxLength: 2000 rwgToken: type: string description: |- Google Actions Center token for conversion tracking. This token is passed via the rwg_token URL parameter when users click through from Google Maps/Search. maxLength: 500 rwgMerchantId: type: string description: |- Merchant ID associated with the rwg_token for Google Actions Center. Used to determine if merchant changed during booking flow. bookingPassword: type: string description: |- Password for accessing a password-protected booking page. Required when the meeting type has password protection enabled. referralCode: type: string description: |- Advocate referral code (from the /r/ referred-person landing). In `auto_booking` qualification mode the booking creates a pending referral recommendation for that advocate; otherwise it is ignored. maxLength: 32 formRecipientToken: type: string description: >- Token of the personal form link that routed here (the `?fr=` URL param a routing form appends when it sends a recipient to a booking page). Links the appointment to the recipient, so a returning recipient is shown the booking they hold instead of an empty calendar, and a second booking through the same link is refused. Identifies only: an unknown token is ignored rather than failing the booking. maxLength: 64 waitlistToken: type: string description: >- Waitlist unsubscribe token. When provided (from the ?wl= URL param on the booking link), the corresponding waitlist entry is removed after successful booking and the attendee is tagged as originating from the waitlist. required: - attendee - meetingTypeId - start BookingResponseDto: type: object properties: appointmentId: type: string description: ID of appointment. Undefined if DOI flow and not confirmed yet. secret: type: string attendeeEmail: type: string bookingType: description: >- Only defined if DOI flow is enabled. If undefined, its a normal booking enum: - doubleOptIn - requireHostConfirmation type: string provisionalBookingId: type: string description: ID of provsionalBooking. Undefined if its a normal booking. redirectUrl: type: string description: >- Redirect URL to navigate to after booking (with any variables replaced). Only set if meeting type has redirect enabled and a URL is configured. This is the single source of truth for redirects. recurringSeriesId: type: string description: |- ID of the recurring series if this is a recurring booking. Undefined for non-recurring bookings. recurringOccurrences: type: number description: |- Total number of occurrences booked if this is a recurring booking. Undefined for non-recurring bookings. appointmentIds: description: |- IDs of all appointments created in this recurring booking. Undefined for non-recurring bookings. type: array items: type: string bundleId: type: string description: |- ID of the bundle if this is a bundle booking. Undefined for non-bundle bookings. isBundleBooking: type: boolean description: Whether this is a bundle booking. CreateAttendeeDto: type: object properties: email: type: string description: |- Attendee email address. Required for all standard bookings. Optional only when `BookingDto.phoneOnlyBooking` is true. Validated as email format when provided. format: email firstname: type: string description: Either fullname or firstname/lastname is required maxLength: 150 lastname: type: string description: Either fullname or firstname/lastname is required maxLength: 150 fullname: type: string description: Either fullname or firstname/lastname is required maxLength: 150 receiveReminders: type: boolean bringalongEmails: description: Additional attendee emails (max 5) maxItems: 5 type: array items: type: string format: email notes: type: object description: An object containing attendee form entries. additionalProperties: type: string billingDetails: nullable: true description: >- Billing details from the booking page's billing block, shown when the meeting type sets `meetingPaymentInfo.collectBillingDetails`. allOf: - $ref: '#/components/schemas/BookingBillingDetailsDto' phone: type: string language: allOf: - $ref: '#/components/schemas/Language' timezone: type: string dataPolicyAccepted: type: boolean required: - receiveReminders - notes MeetingTypeChannel: type: string enum: - local - local-attendee - google - zoom - phone - phone-incoming - whatsapp - connect - webex - skypeForConsumer - skypeForBusiness - teamsForBusiness - teamsForBusiness2 - teamsForExchange - teams2ForExchange - custom - resource - whereby - kmeet - zava - jitsi - nextcloudTalk - openTalk - alfaview description: Meeting channel/location type UtmDto: type: object properties: utm_source: type: string maxLength: 255 utm_medium: type: string maxLength: 255 utm_campaign: type: string maxLength: 255 utm_content: type: string maxLength: 255 utm_term: type: string maxLength: 255 PaymentProvider: type: string enum: - paypal - stripe - mollie - none description: |- Selected payment provider for this booking. Required when the meeting type has multiple payment providers enabled. If not provided, falls back to the first enabled provider. ApiError: type: object required: - statusCode - message properties: statusCode: type: integer example: 400 message: oneOf: - type: string - type: array items: type: string description: >- A sentence, or the list of field constraints that failed. Validation errors name the offending property. example: - limit must not be greater than 100 error: type: string example: BadRequestException BookingBillingDetailsDto: type: object properties: company: type: string maxLength: 255 addressLine1: type: string maxLength: 255 addressLine2: type: string maxLength: 255 postalCode: type: string maxLength: 16 city: type: string maxLength: 120 countryCode: type: string description: ISO 3166-1 alpha-2 maxLength: 2 vatId: type: string description: USt-IdNr. maxLength: 32 Language: type: string enum: - en - de - fr - es - 'no' - nl - it - pl - se - tr - da responses: BadRequest: description: >- The request did not validate. `message` lists the constraints that failed. content: application/json: schema: $ref: '#/components/schemas/ApiError' Unauthorized: description: Missing, malformed, or expired credentials. content: application/json: schema: $ref: '#/components/schemas/ApiError' Forbidden: description: >- Authenticated, but not allowed: the plan does not include this feature, or the token is scoped away from it. content: application/json: schema: $ref: '#/components/schemas/ApiError' TooManyRequests: description: Rate limited. Back off and retry. content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: ApiUserHeader: type: apiKey in: header name: x-meetergo-api-user-id description: >- User ID to act on behalf of. Platform API Keys only (required with an API Key unless the endpoint states otherwise). Requests authenticated with a Personal Access Token are rejected if this header names another user. JWT: scheme: bearer bearerFormat: JWT type: http description: JWT Bearer token for standard user authentication ApiKey: scheme: bearer bearerFormat: API Key type: http description: >- Bearer token: a Platform API Key (format: ak_live::) or a Personal Access Token (format: rgo-...). PATs always act as the token owner. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.