Public API

Getting Access

API access is available on request. Once enabled by the NextInQue team, you can generate API keys from your dashboard.

1. Log into your NextInQue dashboard
2. Go to Settings → API Access
3. Click Request API Access and briefly describe your use case
4. Once approved, click Generate Key — copy it immediately, it's shown only once

Authentication

Every request must include your API key in the header:

X-API-Key: your_api_key_here

Keep your API key secret. Do not expose it in client-side JavaScript. Use it only from your server.

Integration Flow

There are 4 steps to complete a booking — exactly the same flow staff use in the dashboard.

Step 1 — List Services

Returns all active services for your account. You need a serviceId to check availability and create reservations.

Request

GET https://nextinque.com/api/v1/public/services
X-API-Key: your_api_key_here

Response 200

{
  "services": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "General Consultation",
      "description": "30-minute general consultation",
      "durationMinutes": 30
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Follow-up Visit",
      "description": null,
      "durationMinutes": 30
    }
  ]
}

Step 2 — Check Availability

Returns available time slots for a date and service. Only show slots where available > 0 to customers.

Query Parameters

Request

GET https://nextinque.com/api/v1/public/availability?date=2025-12-15&serviceId=a1b2c3d4-e5f6-7890-abcd-ef1234567890
X-API-Key: your_api_key_here

Response 200

{
  "date": "2025-12-15",
  "service": {
    "id": "a1b2c3d4-...",
    "name": "General Consultation",
    "durationMinutes": 30
  },
  "slots": [
    { "time": "09:00", "iso": "2025-12-15T09:00:00.000+05:00", "available": 1, "total": 1 },
    { "time": "09:30", "iso": "2025-12-15T09:30:00.000+05:00", "available": 0, "total": 1 },
    { "time": "10:00", "iso": "2025-12-15T10:00:00.000+05:00", "available": 1, "total": 1 }
  ]
}

Slot Fields

Step 3 — Create a Reservation

Creates a booking. A confirmation notification is sent automatically to the customer.

Request Body

Request

POST https://nextinque.com/api/v1/public/reservations
X-API-Key: your_api_key_here
Content-Type: application/json

{
  "customerName": "John Doe",
  "phone": "+923001234567",
  "email": "john@example.com",
  "scheduledAt": "2025-12-15T09:00:00.000+05:00",
  "serviceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "notes": "First-time customer"
}

Response 201 Created

{
  "reservation": {
    "id": "c3d4e5f6-...",
    "confirmationCode": "A3F1B9C02D4E",
    "customerName": "John Doe",
    "phone": "+923001234567",
    "email": "john@example.com",
    "scheduledAt": "2025-12-15T04:00:00.000Z",
    "status": "PENDING",
    "notes": "First-time customer",
    "source": "API",
    "createdAt": "2025-12-10T14:32:00.000Z",
    "service": { "name": "General Consultation", "durationMinutes": 30 },
    "tenant": { "name": "City Service Center" }
  }
}

Step 4 — Retrieve a Reservation

Request

GET https://nextinque.com/api/v1/public/reservations/A3F1B9C02D4E
X-API-Key: your_api_key_here

Reservation Status Values

Optional — Cancel or Confirm

PATCH https://nextinque.com/api/v1/public/reservations/A3F1B9C02D4E/cancel
X-API-Key: your_api_key_here

PATCH https://nextinque.com/api/v1/public/reservations/A3F1B9C02D4E/confirm
X-API-Key: your_api_key_here

Error Reference

All errors use the same JSON shape:

{ "message": "Human-readable description of what went wrong" }

Slot Conflict (409) — Includes Alternatives

When a slot is fully booked, the response includes the next available times on the same date:

{
  "message": "\"General Consultation\" is fully booked at the selected time. Next available slots on 2025-12-15: 10:00, 10:30, 11:00.",
  "service_name": "General Consultation",
  "available_slots": ["10:00", "10:30", "11:00"],
  "date": "2025-12-15"
}

Recommended Handling

try {
  const res = await createReservation({ scheduledAt: slot.iso, ... });
  // success — show confirmation code to customer
} catch (err) {
  if (err.response?.status === 409) {
    const { message, available_slots } = err.response.data;
    showMessage(message);
    if (available_slots?.length > 0) {
      offerAlternativeSlots(available_slots); // let customer pick another
    }
  }
}

Full Working Example

Complete JavaScript example that walks through all 4 steps:

const API_BASE = "https://nextinque.com/api/v1/public";
const API_KEY  = "your_api_key_here"; // store server-side, never in client JS

const headers = {
  "Content-Type": "application/json",
  "X-API-Key": API_KEY,
};

async function bookReservation() {
  // Step 1: Get services
  const { services } = await fetch(`${API_BASE}/services`, { headers }).then(r => r.json());
  const service = services[0]; // let user pick from a dropdown
  console.log("Service:", service.name, " — ID:", service.id);

  // Step 2: Check availability
  const date = "2025-12-15";
  const { slots } = await fetch(
    `${API_BASE}/availability?date=${date}&serviceId=${service.id}`,
    { headers }
  ).then(r => r.json());

  const openSlots = slots.filter(s => s.available > 0);
  console.log("Open slots:", openSlots.map(s => s.time));

  if (openSlots.length === 0) {
    console.log("No slots available on this date.");
    return;
  }

  const chosenSlot = openSlots[0]; // user selects from UI

  // Step 3: Create reservation
  try {
    const res = await fetch(`${API_BASE}/reservations`, {
      method: "POST",
      headers,
      body: JSON.stringify({
        customerName: "John Doe",
        phone: "+923001234567",
        email: "john@example.com",
        scheduledAt: chosenSlot.iso,  // always use .iso, not .time
        serviceId: service.id,
        notes: "Referred by Dr. Smith",
      }),
    });
    const { reservation } = await res.json();
    console.log("Booked! Code:", reservation.confirmationCode);

    // Step 4: Verify
    const check = await fetch(
      `${API_BASE}/reservations/${reservation.confirmationCode}`,
      { headers }
    ).then(r => r.json());
    console.log("Status:", check.reservation.status); // PENDING

  } catch (err) {
    if (err.response?.status === 409) {
      const { message, available_slots } = err.response.data;
      console.log(message);
      if (available_slots?.length) {
        console.log("Try instead:", available_slots);
      }
    }
  }
}

bookReservation();

All Endpoints