Authentication & Setup

Authentication methods

NowBookIt IPOS supports two authentication methods depending on the integration pattern you are using.

X-API-KEY (REST API)
HMAC Signature (Partner Inbound)

All standard REST API endpoints authenticate using an X-API-KEY header.

curl https://{base_url}/Bookings \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json"

How to obtain your API key:Contact your NowBookIt partner manager at [email protected]. API keys are issued per partner per environment and are scoped to the venues linked to your app.

Keep your API key secure. Do not expose it in client-side code, public repositories, or logs. If a key is compromised, contact [email protected] immediately for rotation.

Partner inbound webhook endpoints use HMAC signature authentication. Instead of an API key, you send a signature computed over the request body and URL using a shared secret.Signature header: A custom header agreed during onboarding (e.g., X-Partner-Signature)How to compute the signature:

const crypto = require("crypto");

function computeSignature(sharedSecret, requestBody, requestUrl) {
  const payload = requestBody + requestUrl;
  return crypto
    .createHmac("sha256", sharedSecret)
    .update(payload)
    .digest("hex");
}

import hmac
import hashlib

def compute_signature(shared_secret: str, request_body: str, request_url: str) -> str:
    payload = (request_body + request_url).encode("utf-8")
    return hmac.new(
        shared_secret.encode("utf-8"),
        payload,
        hashlib.sha256
    ).hexdigest()

Your partner manager will provide:

The exact header name to use (e.g., X-Partner-Signature)
The shared HMAC secret
Your partnerName slug used in inbound endpoint paths

Rate limiting

The API enforces rate limits per endpoint. When you exceed the limit, you will receive a 429 Too Many Requests response. Response body (429):

{
  "message": "You may only perform this action 10 times every 1000 milliseconds"
}

The message indicates the exact limit and window for that endpoint. Implement exponential backoff when you receive a 429:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;

    const delay = Math.pow(2, attempt) * 500; // 500ms, 1s, 2s
    await new Promise((r) => setTimeout(r, delay));
  }
  throw new Error("Rate limit exceeded after retries");
}

Error responses

All endpoints use standard HTTP status codes. Error responses follow a consistent JSON structure.

Status codes

Code	Meaning	Common causes
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`400`	Bad Request	Missing required fields, invalid date format, venue not linked to your app
`401`	Unauthorized	Missing or invalid `X-API-KEY`
`404`	Not Found	Resource with the given ID does not exist
`409`	Conflict	Duplicate ID within the deduplication window (e.g., sale already submitted)
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server error

400 Bad Request — common messages

Venue not linked

{ "message": "No Venue Subscribed to your App." }

Your API key is valid, but the venue you are trying to access has not been linked to your partner app. Contact your NowBookIt partner manager to confirm the location mapping.

loggedInAppId error

{ "message": "loggedInAppId is required" }

The API key provided does not resolve to a known partner app. Verify you are sending the correct key in the X-API-KEY header.

Missing required fields

{ "message": "numOfPeople is required" }

A required request field is missing or null. Check the endpoint documentation for required fields.

Date filter validation

When filtering bookings by date, you must provide either StartDate + EndDate or UpdatedFromDate + UpdatedToDate. Mixing date types or omitting both will return no results without an error — check the GET /Bookings docs for details.

401 Unauthorized

{
  "message": "Unauthorized"
}

Returned when the X-API-KEY header is missing or the key is invalid. Ensure the header is present on every request.

Content type

For all POST, PUT, and PATCH requests, include the Content-Type header:

Content-Type: application/json

Environments

NowBookIt IPOS operates in separate environments. Your partner manager will confirm which base URL to use for development vs. production.

Environment	Notes
Development	Safe for testing — use the `.dev.` subdomain URL provided during onboarding
Production	Live venue data — use with care

Getting Started

Bookings

Reservations

Customers

Gift Cards

Resources

Sales

Webhooks Reference

Outbound Webhooks

Partner Inbound Webhooks

Authentication methods

Rate limiting

Error responses

Status codes

400 Bad Request — common messages

401 Unauthorized

Content type

Environments

​Authentication methods

​Rate limiting

​Error responses

​Status codes

​400 Bad Request — common messages

​401 Unauthorized

​Content type

​Environments

Authentication methods

Rate limiting

Error responses

Status codes

400 Bad Request — common messages

401 Unauthorized

Content type

Environments