Bookings

Create booking

Books the party a hold claims, synchronously, and returns the full booking. The location is the hold’s. status follows the venue’s acceptance mode (confirmed, or requested where the venue confirms by hand) and version starts at 0. A guest contact is required on this channel. Writes carry a body-level idempotency_key. Native and provider writes replay the same booking without reapplying the mutation. An uncertain provider result answers 409 operation_in_progress; retry the same key and body. If details.reason is replay_window_expired, contact support with the operation id rather than issuing a new key. Typed refusals: 409 hold_expired / hold_consumed / overlapping_booking / idempotency_key_reused; 422 guest_contact_required, payment_instrument_required, provider_rejected; 400 invalid_phone. Requires bookings:write.

Create booking

curl --request POST \
  --url https://api.maple.inc/v1/bookings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "hold_id": "<string>",
  "guest": {
    "first_name": "<string>",
    "last_name": "<string>",
    "phone": "<string>",
    "email": "<string>"
  },
  "idempotency_key": "<string>",
  "slot_token": "<string>",
  "notes": "<string>",
  "intake_answers": [
    {
      "question_ref": "<string>",
      "answer": "<string>"
    }
  ]
}
'

import requests

url = "https://api.maple.inc/v1/bookings"

payload = {
    "hold_id": "<string>",
    "guest": {
        "first_name": "<string>",
        "last_name": "<string>",
        "phone": "<string>",
        "email": "<string>"
    },
    "idempotency_key": "<string>",
    "slot_token": "<string>",
    "notes": "<string>",
    "intake_answers": [
        {
            "question_ref": "<string>",
            "answer": "<string>"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    hold_id: '<string>',
    guest: {
      first_name: '<string>',
      last_name: '<string>',
      phone: '<string>',
      email: '<string>'
    },
    idempotency_key: '<string>',
    slot_token: '<string>',
    notes: '<string>',
    intake_answers: [{question_ref: '<string>', answer: '<string>'}]
  })
};

fetch('https://api.maple.inc/v1/bookings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.maple.inc/v1/bookings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'hold_id' => '<string>',
    'guest' => [
        'first_name' => '<string>',
        'last_name' => '<string>',
        'phone' => '<string>',
        'email' => '<string>'
    ],
    'idempotency_key' => '<string>',
    'slot_token' => '<string>',
    'notes' => '<string>',
    'intake_answers' => [
        [
                'question_ref' => '<string>',
                'answer' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.maple.inc/v1/bookings"

	payload := strings.NewReader("{\n  \"hold_id\": \"<string>\",\n  \"guest\": {\n    \"first_name\": \"<string>\",\n    \"last_name\": \"<string>\",\n    \"phone\": \"<string>\",\n    \"email\": \"<string>\"\n  },\n  \"idempotency_key\": \"<string>\",\n  \"slot_token\": \"<string>\",\n  \"notes\": \"<string>\",\n  \"intake_answers\": [\n    {\n      \"question_ref\": \"<string>\",\n      \"answer\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.maple.inc/v1/bookings")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"hold_id\": \"<string>\",\n  \"guest\": {\n    \"first_name\": \"<string>\",\n    \"last_name\": \"<string>\",\n    \"phone\": \"<string>\",\n    \"email\": \"<string>\"\n  },\n  \"idempotency_key\": \"<string>\",\n  \"slot_token\": \"<string>\",\n  \"notes\": \"<string>\",\n  \"intake_answers\": [\n    {\n      \"question_ref\": \"<string>\",\n      \"answer\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.maple.inc/v1/bookings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"hold_id\": \"<string>\",\n  \"guest\": {\n    \"first_name\": \"<string>\",\n    \"last_name\": \"<string>\",\n    \"phone\": \"<string>\",\n    \"email\": \"<string>\"\n  },\n  \"idempotency_key\": \"<string>\",\n  \"slot_token\": \"<string>\",\n  \"notes\": \"<string>\",\n  \"intake_answers\": [\n    {\n      \"question_ref\": \"<string>\",\n      \"answer\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "object": "booking",
  "id": "<string>",
  "livemode": true,
  "created": 123,
  "version": 123,
  "location_id": "<string>",
  "status": "requested",
  "service_state": "expected",
  "confirmation_code": "<string>",
  "starts_at": "<string>",
  "starts_at_local": "<string>",
  "service_date": "<string>",
  "duration_minutes": 123,
  "party_size": 123,
  "guest": {
    "first_name": "<string>",
    "last_name": "<string>",
    "phone": "<string>",
    "phone_last_four": "<string>",
    "email": "<string>"
  },
  "notes": "<string>",
  "channel": "<string>",
  "provider": "maple",
  "cancellation_policy": {
    "type": "<string>",
    "currency": "<string>",
    "policy_text": "<string>",
    "tiers": [
      {
        "within_hours_before_start": 123,
        "basis": "<string>",
        "amount_cents": 123,
        "percent_bps": 123
      }
    ],
    "deposit": {
      "amount_cents": 123,
      "currency": "<string>",
      "basis": "<string>"
    }
  },
  "updated_at": "<string>"
}

{
  "_tag": "DeveloperApiBadRequest",
  "message": "<string>",
  "code": "<string>"
}

{
  "_tag": "DeveloperApiUnauthorized",
  "message": "<string>"
}

{
  "_tag": "DeveloperApiForbidden",
  "code": "insufficient_scope",
  "message": "<string>"
}

{
  "_tag": "DeveloperApiNotFound",
  "message": "<string>"
}

{
  "_tag": "DeveloperApiConflict",
  "message": "<string>",
  "code": "<string>",
  "details": {}
}

{
  "_tag": "DeveloperApiUnprocessable",
  "code": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "_tag": "DeveloperApiRateLimited",
  "message": "<string>",
  "retry_after": 123
}

Authorizations

Authorization

string

header

required

API key — mpk_test_… for the sandbox, mpk_live_… for production. Issued by Maple during partner onboarding.

Body

application/json

hold_id

string

required

The hold to book from (POST /booking_holds).

guest

object

required

Show child attributes

idempotency_key

string

required

Your unique key for this write (body-level, scoped to your app). Retrying with the same key and the same request replays the same booking; the same key with a different request answers 409 idempotency_key_reused.

Required string length: 1 - 255

slot_token

string | null

Optional for existing integrations. The persisted hold supplies the authoritative quote for native and provider-managed locations.

notes

string | null

The guest’s note to the venue.

intake_answers

object[] | null

Structured intake for native bookings. OpenTable does not support these answers and returns 422 capability_unsupported instead of dropping them.

Show child attributes

Response

Success

object

enum<string>

required

Available options:

booking

string

required

Opaque, prefixed bkg_….

livemode

boolean

required

created

required

version

required

location_id

string

required

status

enum<string>

required

Available options:

requested,

confirmed,

seated,

completed,

declined_by_venue,

cancelled_by_guest,

cancelled_by_venue,

cancelled_unattributed,

no_show

service_state

enum<string> | null

required

Available options:

expected,

arrived,

partially_seated,

fully_seated,

left

confirmation_code

string

required

starts_at

string

required

ISO-8601 UTC instant.

starts_at_local

string

required

Venue wall-clock, YYYY-MM-DDTHH:MM.

service_date

string

required

The venue service day the booking belongs to, YYYY-MM-DD.

duration_minutes

required

Turn duration; null on provider-managed bookings, where Maple never invents one.

party_size

required

guest

object

required

Show child attributes

notes

string | null

required

The guest-facing note; venue-internal notes are never exposed.

channel

string

required

The channel the booking originated on, e.g. api_partner, voice_ai, internal.

provider

enum<string>

required

Available options:

maple,

opentable,

resy,

sevenrooms

cancellation_policy

object | null

required

Show child attributes

updated_at

string

required

ISO-8601 UTC instant.

⌘I

Create booking

curl --request POST \
  --url https://api.maple.inc/v1/bookings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "hold_id": "<string>",
  "guest": {
    "first_name": "<string>",
    "last_name": "<string>",
    "phone": "<string>",
    "email": "<string>"
  },
  "idempotency_key": "<string>",
  "slot_token": "<string>",
  "notes": "<string>",
  "intake_answers": [
    {
      "question_ref": "<string>",
      "answer": "<string>"
    }
  ]
}
'

import requests

url = "https://api.maple.inc/v1/bookings"

payload = {
    "hold_id": "<string>",
    "guest": {
        "first_name": "<string>",
        "last_name": "<string>",
        "phone": "<string>",
        "email": "<string>"
    },
    "idempotency_key": "<string>",
    "slot_token": "<string>",
    "notes": "<string>",
    "intake_answers": [
        {
            "question_ref": "<string>",
            "answer": "<string>"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    hold_id: '<string>',
    guest: {
      first_name: '<string>',
      last_name: '<string>',
      phone: '<string>',
      email: '<string>'
    },
    idempotency_key: '<string>',
    slot_token: '<string>',
    notes: '<string>',
    intake_answers: [{question_ref: '<string>', answer: '<string>'}]
  })
};

fetch('https://api.maple.inc/v1/bookings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.maple.inc/v1/bookings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'hold_id' => '<string>',
    'guest' => [
        'first_name' => '<string>',
        'last_name' => '<string>',
        'phone' => '<string>',
        'email' => '<string>'
    ],
    'idempotency_key' => '<string>',
    'slot_token' => '<string>',
    'notes' => '<string>',
    'intake_answers' => [
        [
                'question_ref' => '<string>',
                'answer' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.maple.inc/v1/bookings"

	payload := strings.NewReader("{\n  \"hold_id\": \"<string>\",\n  \"guest\": {\n    \"first_name\": \"<string>\",\n    \"last_name\": \"<string>\",\n    \"phone\": \"<string>\",\n    \"email\": \"<string>\"\n  },\n  \"idempotency_key\": \"<string>\",\n  \"slot_token\": \"<string>\",\n  \"notes\": \"<string>\",\n  \"intake_answers\": [\n    {\n      \"question_ref\": \"<string>\",\n      \"answer\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.maple.inc/v1/bookings")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"hold_id\": \"<string>\",\n  \"guest\": {\n    \"first_name\": \"<string>\",\n    \"last_name\": \"<string>\",\n    \"phone\": \"<string>\",\n    \"email\": \"<string>\"\n  },\n  \"idempotency_key\": \"<string>\",\n  \"slot_token\": \"<string>\",\n  \"notes\": \"<string>\",\n  \"intake_answers\": [\n    {\n      \"question_ref\": \"<string>\",\n      \"answer\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.maple.inc/v1/bookings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"hold_id\": \"<string>\",\n  \"guest\": {\n    \"first_name\": \"<string>\",\n    \"last_name\": \"<string>\",\n    \"phone\": \"<string>\",\n    \"email\": \"<string>\"\n  },\n  \"idempotency_key\": \"<string>\",\n  \"slot_token\": \"<string>\",\n  \"notes\": \"<string>\",\n  \"intake_answers\": [\n    {\n      \"question_ref\": \"<string>\",\n      \"answer\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "object": "booking",
  "id": "<string>",
  "livemode": true,
  "created": 123,
  "version": 123,
  "location_id": "<string>",
  "status": "requested",
  "service_state": "expected",
  "confirmation_code": "<string>",
  "starts_at": "<string>",
  "starts_at_local": "<string>",
  "service_date": "<string>",
  "duration_minutes": 123,
  "party_size": 123,
  "guest": {
    "first_name": "<string>",
    "last_name": "<string>",
    "phone": "<string>",
    "phone_last_four": "<string>",
    "email": "<string>"
  },
  "notes": "<string>",
  "channel": "<string>",
  "provider": "maple",
  "cancellation_policy": {
    "type": "<string>",
    "currency": "<string>",
    "policy_text": "<string>",
    "tiers": [
      {
        "within_hours_before_start": 123,
        "basis": "<string>",
        "amount_cents": 123,
        "percent_bps": 123
      }
    ],
    "deposit": {
      "amount_cents": 123,
      "currency": "<string>",
      "basis": "<string>"
    }
  },
  "updated_at": "<string>"
}

{
  "_tag": "DeveloperApiBadRequest",
  "message": "<string>",
  "code": "<string>"
}

{
  "_tag": "DeveloperApiUnauthorized",
  "message": "<string>"
}

{
  "_tag": "DeveloperApiForbidden",
  "code": "insufficient_scope",
  "message": "<string>"
}

{
  "_tag": "DeveloperApiNotFound",
  "message": "<string>"
}

{
  "_tag": "DeveloperApiConflict",
  "message": "<string>",
  "code": "<string>",
  "details": {}
}

{
  "_tag": "DeveloperApiUnprocessable",
  "code": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "_tag": "DeveloperApiRateLimited",
  "message": "<string>",
  "retry_after": 123
}

Get started

Orders

Menus

Delivery

Bookings

Core concepts

Tutorials

API reference

Endpoints

Resources

Create booking

Authorizations

Body

Response