API Documentation

Complete reference for integrating NoQue's appointment booking platform into your applications.

Getting Started

Welcome to the NoQue API. This RESTful API allows you to integrate appointment booking into your applications.

Base URL

https://www.noqueue.co.za/api

Authentication

NoQue uses two authentication methods:

  • Admin Token: For administrative operations (header: x-admin-token)
  • JWT Bearer: For citizen operations (header: Authorization: Bearer {token})

Quick Example

curl -X GET "https://www.noqueue.co.za/api/locations" \ -H "Accept: application/json"

Authentication

POST /api/auth/send-otp

Send OTP to phone number for citizen authentication.

Request Body
{ "phone_number": "+27821234567" }
Response
{ "message": "OTP sent successfully", "otp_id": "550e8400-e29b-41d4-a716-446655440000" }
Example
curl -X POST "https://www.noqueue.co.za/api/auth/send-otp" \ -H "Content-Type: application/json" \ -d '{"phone_number": "+27821234567"}'
POST /api/auth/verify-otp

Verify OTP code and receive JWT access token.

Request Body
{ "otp_id": "550e8400-e29b-41d4-a716-446655440000", "otp_code": "123456" }
Response
{ "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "identity_id": "660e8400-e29b-41d4-a716-446655440000" }

Locations

GET /api/locations

Get list of all service locations.

Response
[ { "id": "770e8400-e29b-41d4-a716-446655440000", "partner_id": "880e8400-e29b-41d4-a716-446655440000", "name": "Cape Town Home Affairs", "address": "56 Barrack Street", "city": "Cape Town", "province": "Western Cape", "postal_code": "8000", "created_at": "2025-01-01T10:00:00Z" } ]
Example
curl -X GET "https://www.noqueue.co.za/api/locations" \ -H "Accept: application/json"

Services

GET /api/services

Get list of available services, optionally filtered by location.

Query Parameters
  • location_id (optional): Filter by location UUID
Response
[ { "id": "990e8400-e29b-41d4-a716-446655440000", "location_id": "770e8400-e29b-41d4-a716-446655440000", "name": "ID Application", "description": "Apply for a new South African ID document", "duration_minutes": 30, "created_at": "2025-01-01T10:00:00Z" } ]
Example
curl -X GET "https://www.noqueue.co.za/api/services?location_id=770e8400-e29b-41d4-a716-446655440000" \ -H "Accept: application/json"

Slots

GET /api/slots

Get available time slots for a service on a specific date.

Query Parameters
  • service_id (required): Service UUID
  • date (required): Date in YYYY-MM-DD format
  • available_only (optional): Show only available slots (default: true)
Response
[ { "id": "aa0e8400-e29b-41d4-a716-446655440000", "service_id": "990e8400-e29b-41d4-a716-446655440000", "start_time": "2025-03-10T09:00:00+02:00", "end_time": "2025-03-10T09:30:00+02:00", "capacity": 5, "bookings_count": 2, "available": true } ]
Example
curl -X GET "https://www.noqueue.co.za/api/slots?service_id=990e8400-e29b-41d4-a716-446655440000&date=2025-03-10" \ -H "Accept: application/json"

Bookings

POST /api/bookings

Create a new booking for a time slot.

Request Body
{ "slot_id": "aa0e8400-e29b-41d4-a716-446655440000", "identity_id": "660e8400-e29b-41d4-a716-446655440000", "notes": "Need assistance with forms" }
Response
{ "id": "bb0e8400-e29b-41d4-a716-446655440000", "reference_number": "NQ-20250310-A8B2", "status": "booked", "slot": { "id": "aa0e8400-e29b-41d4-a716-446655440000", "start_time": "2025-03-10T09:00:00+02:00", "end_time": "2025-03-10T09:30:00+02:00" }, "created_at": "2025-03-05T14:30:00Z" }
Example
curl -X POST "https://www.noqueue.co.za/api/bookings" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -d '{"slot_id": "aa0e8400-e29b-41d4-a716-446655440000", "identity_id": "660e8400-e29b-41d4-a716-446655440000"}'
GET /api/bookings/by-ref/{reference}

Get booking details by reference number.

Response
{ "id": "bb0e8400-e29b-41d4-a716-446655440000", "reference_number": "NQ-20250310-A8B2", "status": "booked", "slot": {...}, "identity": {...}, "created_at": "2025-03-05T14:30:00Z" }
Example
curl -X GET "https://www.noqueue.co.za/api/bookings/by-ref/NQ-20250310-A8B2" \ -H "Accept: application/json"

Error Handling

The API uses conventional HTTP response codes:

Code Meaning
200 OK - Request succeeded
201 Created - Resource created successfully
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid authentication
404 Not Found - Resource doesn't exist
409 Conflict - Slot already fully booked
500 Server Error - Something went wrong
Error Response Format
{ "error": "Slot is fully booked", "code": "SLOT_FULL", "details": { "slot_id": "aa0e8400-e29b-41d4-a716-446655440000", "capacity": 5, "current_bookings": 5 } }

Rate Limits

To ensure fair usage, the API has the following rate limits:

  • Public endpoints: 100 requests per minute
  • Authenticated users: 300 requests per minute
  • Admin token: 1000 requests per minute

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1709650800

Need Help Getting Started?

Our team is here to help you integrate NoQue into your applications.

Contact Support Try Widget Demo