Creates a new appointment booking with a specified host for a given meeting type and time slot.
Endpoint
| Header | Required | Description |
|---|
Authorization | Yes | Bearer <your-api-key> |
Content-Type | Yes | application/json |
Request Body
Required Fields
| Field | Type | Description |
|---|
meetingTypeId | string | The ID of the meeting type to book |
start | string | Start time in ISO 8601 format (e.g., 2024-01-15T09:00:00+01:00) |
attendee | object | Information about the person booking |
hostIds | string[] | Array of host IDs for the booking (required for one-on-one bookings) |
Attendee Object
| Field | Type | Required | Description |
|---|
email | string | Yes* | Email address of the attendee |
firstname | string | No | First name of the attendee |
lastname | string | No | Last name of the attendee |
phone | string | No | Phone number |
company | string | No | Company name |
customFields | object | No | Custom field values as key-value pairs |
phoneOnlyBooking is true and the meeting type has allowPhoneOnlyBooking enabled. In this case, phone becomes required instead. See Voice AI Bot for details.
Optional Fields
| Field | Type | Description |
|---|
queueId | string | Queue ID for round-robin meeting types |
duration | number | Duration in minutes (for meeting types with multiple options) |
channel | string | Video conferencing: google_meet, zoom, teams, whereby, phone, in_person |
location | string | Location for in-person meetings |
skipNotifications | boolean | Skip sending email notifications (default: false) |
phoneOnlyBooking | boolean | When true, attendee email is not required and phone becomes the identifier. The meeting type must have allowPhoneOnlyBooking enabled. See Voice AI Bot |
icsTitle | string | Custom calendar invite title |
icsDescription | string | Custom calendar invite description |
Examples
Basic Booking
curl -X POST "https://api.meetergo.com/v4/booking" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"meetingTypeId": "770e8400-e29b-41d4-a716-446655440002",
"start": "2024-01-15T09:00:00+01:00",
"hostIds": ["550e8400-e29b-41d4-a716-446655440000"],
"attendee": {
"email": "client@example.com",
"firstname": "Jane",
"lastname": "Smith"
}
}'
With Custom Fields and Video Conferencing
{
"meetingTypeId": "770e8400-e29b-41d4-a716-446655440002",
"start": "2024-01-15T09:00:00+01:00",
"hostIds": ["550e8400-e29b-41d4-a716-446655440000"],
"channel": "zoom",
"attendee": {
"email": "client@example.com",
"firstname": "Jane",
"lastname": "Smith",
"company": "Acme Inc",
"phone": "+1-555-123-4567",
"customFields": {
"referral_source": "Website",
"company_size": "50-200"
}
}
}
Response
Success (201 Created) - Standard Booking
{
"appointmentId": "appt-uuid-456",
"secret": "secret-token-789"
}
| Field | Description |
|---|
appointmentId | UUID of the created appointment |
secret | Secret token for managing the appointment (cancel/reschedule) |
Store the secret securely. It’s required to cancel or reschedule the appointment without authentication.
Success (201 Created) - Double Opt-In
If the meeting type requires confirmation:
{
"bookingType": "DoubleOptIn",
"provisionalBookingId": "provisional-uuid-123"
}
| Field | Description |
|---|
bookingType | DoubleOptIn or RequireHostConfirmation |
provisionalBookingId | ID of provisional booking (finalized after confirmation) |
Error Responses
400 Bad Request - Time Slot Unavailable
{
"statusCode": 400,
"message": "The selected time slot is no longer available",
"error": "Bad Request"
}
400 Bad Request - Missing Host
{
"statusCode": 400,
"message": "hostIds or queueId is required",
"error": "Bad Request"
}
400 Bad Request - Invalid Duration
{
"statusCode": 400,
"message": "Duration must match one of the allowed durations for this meeting type",
"error": "Bad Request"
}
Webhooks
When a booking is created, meetergo sends a booking_created webhook event:
{
"event": "booking_created",
"data": {
"appointmentId": "appt-uuid-456",
"meetingTypeId": "770e8400-e29b-41d4-a716-446655440002",
"start": "2024-01-15T09:00:00+01:00",
"end": "2024-01-15T09:30:00+01:00",
"attendee": {
"email": "client@example.com",
"firstname": "Jane",
"lastname": "Smith"
},
"hostIds": ["550e8400-e29b-41d4-a716-446655440000"]
}
}
Notes
- Use Get Booking Availability first to find available slots
- For round-robin meeting types, provide
queueId instead of hostIds to let the system select the next available host
- If double opt-in is enabled, the attendee must confirm via email before the appointment is finalized
