Skip to main content
API docs by Redocly

TakeMe Inbound API (2024-09)

This API documentation outlines the process for creating reservations directly within the TakeMe Inbound system. Below is an overview of the key steps and general notes for working with the API:

Key Steps:

  • Fetch an eligible shop
  • Fetch the shop courses
  • Fetch shop availability to get block unit time (optional as most shops are 30 mins in block time, but recommended to check just in case)
  • Using IDs and other relevant information from previous fetch APIs, call the create reservation API

General Notes:

  • All of the below APIs will require an API key. Please contact TakeMe to obtain an API key. We will also provide you with the "platform" path variable, required for all APIs.
  • All dates and times are in UTC (Universal Time Coordinated) unless otherwise specified.
  • IDs are generally 16-digit UUIDs (Universally Unique Identifiers) unless otherwise specified.
  • "Shop" and "Restaurant" are used interchangeably in this documentation.
  • For status codes such as "reservationStatus," you may encounter unknown codes not mentioned in the API docs, especially from the staging environment. These codes are generally for other purposes and can be ignored.
  • TakeMe Inbound has two environments: Staging and Production.
  • If you would like us to create webhook APIs, please contact us to discuss implementation details.

Reservation APIs

Fetch a list of shops

This API fetch a list of shops eligible for reservations to be created directly into TakeMe Admin.

path Parameters
platform
required
string
query Parameters
limit
integer <int32> <= 50

The maximum amount of shops to fetch at once with a default of 10

offset
integer <int32>

The offset of the list of shops to fetch with a default of 0

shopIds
Array of strings [ 0 .. 30 ] items
Example: shopIds=8d494383-8841-11ee-8147-0ac66e9ce373&shopIds=97c1d19b-8841-11ee-8147-0ac66e9ce373

A list of shop ids to fetch. If this parameter is specified, limit and offset parameters will be ignored. A maximum of 30 shop ids can be specified at once.

shopNameQuery
string
Example: shopNameQuery=Awesome Sushi

Find a list of shops with name similar to the parameter shop_name_query

showRealTimeOnly
boolean
Example: showRealTimeOnly=true

If true, only show shops that are bookable in real time. If false, show all shops.

header Parameters
Authorization
required
string

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ],
  • "count": 0
}

Fetch an individual shop.

This API fetches the details of one shop only.

path Parameters
platform
required
string
shopId
required
string

The shop id to fetch

header Parameters
Authorization
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "number": "string",
  • "nameJa": "string",
  • "nameEn": "string",
  • "addressState": "東京都",
  • "addressCity": "渋谷区",
  • "addressTown": "道玄坂",
  • "addressLine1": "1-18-6",
  • "addressLine2": "Shibuya Mark City 4F",
  • "minGuests": 1,
  • "maxGuests": 10,
  • "cancellationPolicyDays": 3,
  • "shopBusinessHours": {
    },
  • "realTimeBookable": true
}

Get shop's availability.

Get the shop's availability for a given date. This API should be called first to ensure a reservation is available before proceeding to create a reservation. Times returned will in be in JST.

path Parameters
platform
required
string
shopId
required
string

The shop id to fetch availability for

query Parameters
requestDate
string
Example: requestDate=2024-09-25

Date to get restaurant's availability If omitted, the current date will be used. Format expected is yyyy-MM-dd

pax
string
Default: "2"
Example: pax=2

Number of guests

header Parameters
Authorization
required
string

Responses

Response samples

Content type
application/json
{
  • "requestedDate": "2019-08-24",
  • "requestedPax": 2,
  • "availableTimes": [
    ],
  • "realTime": true
}

Get a list of courses for a specific shop.

Get a list of courses for a specified shop id.

path Parameters
platform
required
string
shopId
required
string

The shop id to fetch courses for

query Parameters
limit
integer <int32> <= 50
Example: limit=10

The number of courses to return with a maximum of 50

offset
integer <int32>

The offset to start from. Default is 0

courseNameQuery
string
Example: courseNameQuery=Sushi Course

If provided, the courses will be filtered by this name

header Parameters
Authorization
required
string

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ],
  • "count": 0
}

Create a reservation.

Create a reservation for a specific shop. Shops that are real time bookable will be directly created with 'success' status. Otherwise, they are created with 'pending' status. Shops will be send an email notification upon creation. Please note that each reservation should only one one course id or its child variants.

path Parameters
platform
required
string
shopId
required
string

The shop id to create a reservation for

header Parameters
Authorization
required
string
Request Body schema: application/json
required
reservationStartTime
required
string <date-time>

The local date time of the reservation start time in ISO 8601 format. e.g 2024-01-01T17:00:00. Please pass this parameter after converting the time to JST. Please do not pass in a UTC time here.

guestFirstName
required
string <= 255 characters

The first name of the user who is making this reservation

guestLastName
required
string <= 255 characters

The last name of the user who is making this reservation

guestPhoneNumber
string [ 0 .. 20 ] characters

The phone number of the user who is making this reservation. The format on the phone number should be 'xxx-xxxx-xxxx'

numberOfGuests
integer <int32> >= 1

The number of guests for this reservation

remark
string

Any additional remarks for this reservation such as allergies. If remarks are passed, remarkStatus will automatically be set to 0 (unread), otherwise it will be null.

required
Array of objects (ReservedCourseInboundRequest) non-empty [ items non-empty ]

The list of course ids to be requested for this reservation.

originPlatformReservationNumber
required
string <= 100 characters

Please pass in the unique reservation number (generally for the guests' reference) used in your DB.

guestEmail
string

The email of the user who is making this reservation. No automated notifications will be sent to this email.

Responses

Request samples

Content type
application/json
{
  • "reservationStartTime": "2019-08-24T14:15:22Z",
  • "guestFirstName": "John",
  • "guestLastName": "Doe",
  • "guestPhoneNumber": "123-4567-8910",
  • "numberOfGuests": 4,
  • "remark": "Allergic to nuts",
  • "requestedCourses": [
    ],
  • "originPlatformReservationNumber": "RES12345678",
  • "guestEmail": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "shopId": "string",
  • "originPlatformReservationNumber": "string",
  • "reservationStartTime": "2019-08-24T14:15:22Z",
  • "numberOfGuests": 2,
  • "guestFirstName": "string",
  • "guestLastName": "string",
  • "guestPhoneNumber": "string",
  • "guestEmail": "string",
  • "remark": "string",
  • "remarkStatus": 0,
  • "priceTotal": 0,
  • "originPlatform": "string",
  • "courses": [
    ],
  • "status": "PENDING"
}

Update a specific reservation..

Update a specific reservation. Currently, all of the below request fields must be passed in regardless if it will be updated. If reservationStartTime is different from previous value, the '3 days in advanced' validation will be enforced again. Email notifications are sent to restaurant on most updates.

path Parameters
platform
required
string
reservationIdOrOriginNumber
required
string

The reservation id or origin platform reservation number to fetch

header Parameters
Authorization
required
string
Request Body schema: application/json
required
reservationStartTime
required
string <date-time>

The local date time of the reservation start time in ISO 8601 format. e.g 2024-01-01T17:00:00. Please pass this parameter after converting the time to JST. Please do not pass in a UTC time here.

guestFirstName
required
string <= 255 characters

The first name of the user who is making this reservation

guestLastName
required
string <= 255 characters

The last name of the user who is making this reservation

guestPhoneNumber
string [ 0 .. 20 ] characters

The phone number of the user who is making this reservation. The format on the phone number should be 'xxx-xxxx-xxxx'

numberOfGuests
integer <int32> >= 1

The number of guests for this reservation

remark
string

Any additional remarks for this reservation such as allergies. If remarks are passed, remarkStatus will automatically be set to 0 (unread), otherwise it will be null.

required
Array of objects (ReservedCourseInboundRequest) non-empty [ items non-empty ]

The list of course ids to be requested for this reservation.

Responses

Request samples

Content type
application/json
{
  • "reservationStartTime": "2019-08-24T14:15:22Z",
  • "guestFirstName": "John",
  • "guestLastName": "Doe",
  • "guestPhoneNumber": "123-4567-8910",
  • "numberOfGuests": 4,
  • "remark": "Allergic to nuts",
  • "requestedCourses": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "shopId": "string",
  • "originPlatformReservationNumber": "string",
  • "reservationStartTime": "2019-08-24T14:15:22Z",
  • "numberOfGuests": 2,
  • "guestFirstName": "string",
  • "guestLastName": "string",
  • "guestPhoneNumber": "string",
  • "guestEmail": "string",
  • "remark": "string",
  • "remarkStatus": 0,
  • "priceTotal": 0,
  • "originPlatform": "string",
  • "courses": [
    ],
  • "status": "PENDING"
}

Cancel a specific reservation.

Cancel a specific reservation. The reservation status will be updated based on whether a refund is provided to the guest.

path Parameters
platform
required
string
reservationIdOrOriginNumber
required
string

The reservation id or origin platform reservation number to fetch

header Parameters
Authorization
required
string
Request Body schema: application/json
required
refunded
boolean
Default: false

Whether a refund is granted to the user for this cancellation..

remark
string

Any additional remarks for this cancellation such as reasons for the cancellation.

Responses

Request samples

Content type
application/json
{
  • "refunded": false,
  • "remark": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "shopId": "string",
  • "originPlatformReservationNumber": "string",
  • "reservationStartTime": "2019-08-24T14:15:22Z",
  • "numberOfGuests": 2,
  • "guestFirstName": "string",
  • "guestLastName": "string",
  • "guestPhoneNumber": "string",
  • "guestEmail": "string",
  • "remark": "string",
  • "remarkStatus": 0,
  • "priceTotal": 0,
  • "originPlatform": "string",
  • "courses": [
    ],
  • "status": "PENDING"
}

Fetch a list of reservations.

This API fetches the list of reservations associated with the caller.

path Parameters
platform
required
string
query Parameters
limit
integer <int32> <= 30
Example: limit=10

The number of reservations to be returned in the response. Default is 10 with a max of 30.

offset
integer <int32>

The offset of the list of shops to fetch.

reservationNumbers
Array of strings [ 0 .. 30 ] items
Example: reservationNumbers=8d494383-8841-11ee-8147-0ac66e9ce373&reservationNumbers=97c1d19b-8841-11ee-8147-0ac66e9ce373

A list of reservation ids or origin platform reservation numbers to fetch. If this parameter is specified, the limit and offset parameters will be ignored. A maximum of 30 shop ids can be specified at once.

header Parameters
Authorization
required
string

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ],
  • "count": 0
}

Fetch an individual reservation.

This API fetches the list of reservations associated with the caller.

path Parameters
platform
required
string
reservationNumber
required
string

The reservation id or origin platform reservation number to fetch

header Parameters
Authorization
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "shopId": "string",
  • "originPlatformReservationNumber": "string",
  • "reservationStartTime": "2019-08-24T14:15:22Z",
  • "numberOfGuests": 2,
  • "guestFirstName": "string",
  • "guestLastName": "string",
  • "guestPhoneNumber": "string",
  • "guestEmail": "string",
  • "remark": "string",
  • "remarkStatus": 0,
  • "priceTotal": 0,
  • "originPlatform": "string",
  • "courses": [
    ],
  • "status": "PENDING"
}