Rules and limits

Allowed websites

Each website key lists the websites allowed to use it. Browser requests from any other website are rejected with 403.

• Websites are matched by protocol and domain. thestage.com is stored as https://thestage.com.
• www.thestage.com is a different website and must be listed separately.
• Requests made from a server have no browser origin and are accepted. They are subject to the same rate limits.
• The API playground on this site (https://developers.kisum.io) is allowed on every key, so you can try a real key here without listing this website on it.

Spaces on the key

A website key covers all the venue’s spaces, or only the spaces the venue selected on it.

• GET /spaces returns only the spaces the key covers.
• Slots, availability, quotes and booking requests accept only those spaces. Any other spaceId returns 404, even when the space exists and is published.
• The key’s spaces can change at any time. Read GET /spaces instead of hard-coding IDs, or handle a 404 on a space that used to work.

Rate limits

Limits apply per website key and per visitor IP address.

Requests	Limit
GET requests	120 per minute
POST /quote	30 per minute
POST /booking-requests	5 per hour

When a limit is reached, the API returns 429 with the code RATE_LIMITED. Wait before trying again.

Date holds

When a booking request is sent, it takes a place in the queue for that date and the venue answers the queue in order.

• The first request on a date is hold 1, the next is hold 2, and so on. holdPosition in the response says which one this request is.
• A date keeps taking requests until five are waiting; GET .../availability returns free: false once it is full, and holds says how many are waiting before then.
• A date only stops taking requests when the venue commits to a booking or an event on it, or blocks it.
• If a request ahead of you is declined or withdrawn, everybody behind it moves up one place.
• The venue sets the hold period on the website key: 24 hours, 48 hours, 3 days, 7 days, 14 days, 30 days, or no time limit.
• A hold never lasts past the start of the slot.
• If the venue does not accept or decline the request within the hold period, the request stops holding the date.
• With no time limit, the request holds its place until the venue accepts or declines it, and holdExpiresAt is omitted from the response.
• The venue can reorder the queue itself, so a position can change before the venue answers.

Amounts and currency

Amounts are integers in hundredths of the currency unit, whatever the currency: divide by 100 to get the amount. For example, 150000 in USD is USD 1,500.00, and 7500000000 in IDR is IDR 75,000,000.

IDR, JPY, KRW, VND, CLP, ISK and UGX are written without decimals, so round the result: IDR 75,000,000, not IDR 75,000,000.00. Other currencies use their standard number of decimal places, for example two for USD and EUR.

Dates and times

• Dates use the format YYYY-MM-DD.
• Timestamps such as holdExpiresAt use ISO 8601 in UTC.
• Slot times (startTime, endTime) are in the venue’s time zone.

Spam protection

POST /booking-requests accepts a field named website. Add it to your form as a hidden field that visitors cannot see or fill in, and always send it empty. Automated spam tools tend to fill in every field. When website has a value, the API returns a normal success response but does not create a booking request.

Errors

Errors return success: false and an error object:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Invalid website key."
  }
}

Use code in your code. message is a readable explanation and can change.

Status	Code	Meaning
400	BAD_REQUEST	The request body is missing or is not valid JSON.
403	FORBIDDEN	The request comes from a website that is not allowed to use the website key.
404	NOT_FOUND	The website key does not exist or is disabled, the venue is not listed on the marketplace or has no published space, or the space, slot or package was not found, is not published, or is not covered by the website key.
409	CONFLICT	The selected date and slot are no longer available.
422	VALIDATION_ERROR	A field is invalid, for example a date in the wrong format or in the past, or an invalid email address.
429	RATE_LIMITED	Too many requests. See Rate limits.
500	INTERNAL_SERVER_ERROR	An unexpected error occurred. Try again later.