Appointments Endpoints

Manage appointments: creation, consultation, and cancellation.

Credits

Creating an appointment consumes 1 credit. Cancelling an appointment refunds 1 credit.

POST /appointments

Create a new appointment. Automatically consumes 1 credit from your organization.

Optional Fields

• externalUserId: Your system's identifier to match with your users
• workerId: Staff member/professional ID. Required only if the department has showAdminsInBooking=true

Request

curl -X POST https://mc-prd.duckdns.org/api/v1/appointments -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{
  "departmentId": 5,
  "dateTime": "2026-02-15T10:00:00",
  "name": "Amadou Diallo",
  "workerId": 42,
  "externalUserId": "customer_12345"
}'

Java

import com.moncreneau.ApiClient;
import com.moncreneau.model.Appointment;
import com.moncreneau.model.CreateAppointmentRequest;
import java.time.LocalDateTime;

ApiClient client = new ApiClient("your_api_key");

CreateAppointmentRequest request = new CreateAppointmentRequest()
    .departmentId(5L)
    .dateTime(LocalDateTime.parse("2026-02-15T10:00:00"))
    .name("Amadou Diallo")
    .workerId(42L)
    .externalUserId("customer_12345");

try {
    Appointment appointment = client.appointments().create(request);
    System.out.println("Appointment created with ID: " + appointment.getId());
    System.out.println("QR Code: " + appointment.getQrCode());
} catch (InsufficientCreditsException e) {
    System.err.println("Insufficient credits: " + e.getMessage());
}

Node.js

const { MoncreneauClient } = require('moncreneau');

const client = new MoncreneauClient('your_api_key');

try {
  const appointment = await client.appointments.create({
    departmentId: 5,
    dateTime: '2026-02-15T10:00:00',
    name: 'Amadou Diallo',
    workerId: 42,
    externalUserId: 'customer_12345'
  });
  
  console.log(`Appointment created with ID: ${appointment.id}`);
  console.log(`QR Code: ${appointment.qrCode}`);
} catch (error) {
  if (error.code === 'INSUFFICIENT_CREDITS') {
    console.error('Insufficient credits:', error.message);
  }
}

PHP

<?php
use Moncreneau\Client;
use Moncreneau\Exception\InsufficientCreditsException;

$client = new Client('your_api_key');

try {
    $appointment = $client->appointments->create([
        'departmentId' => 5,
        'dateTime' => '2026-02-15T10:00:00',
        'name' => 'Amadou Diallo',
        'externalUserId' => 'customer_12345'
    ]);
    
    echo "Appointment created with ID: {$appointment->id}" . PHP_EOL;
    echo "QR Code: {$appointment->qrCode}" . PHP_EOL;
} catch (InsufficientCreditsException $e) {
    echo "Insufficient credits: {$e->getMessage()}" . PHP_EOL;
}

Python

from moncreneau import MoncreneauClient
from moncreneau.exceptions import InsufficientCreditsError

client = MoncreneauClient('your_api_key')

try:
    appointment = client.appointments.create(
        department_id=5,
        date_time='2026-02-15T10:00:00',
        name='Amadou Diallo',
        worker_id=42,
        external_user_id='customer_12345'
    )
    
    print(f"Appointment created with ID: {appointment.id}")
    print(f"QR Code: {appointment.qr_code}")
except InsufficientCreditsError as e:
    print(f"Insufficient credits: {e}")

Response 201 - Success

{
  "id": 123,
  "dateTime": "2026-02-15T10:00:00",
  "status": "CONFIRMED",
  "name": "Amadou Diallo",
  "qrCode": "QR-MONC-123-ABC",
  "departmentId": 5,
  "departmentName": "General Consultation",
  "externalUserId": "customer_12345",
  "createdAt": "2026-01-21T09:30:00"
}

Response 402 - Insufficient Credits

{
  "code": "INSUFFICIENT_CREDITS",
  "message": "Insufficient credits to create appointment. Current: 0, Required: 1",
  "timestamp": "2026-01-21T10:00:00"
}

Response 400 - Bad Request

{
  "code": "INVALID_REQUEST",
  "message": "DateTime must be in the future",
  "timestamp": "2026-01-21T10:00:00"
}

---

GET /appointments/{id}

Retrieve appointment details by ID.

Request

curl https://mc-prd.duckdns.org/api/v1/appointments/123 -H "X-API-Key: YOUR_API_KEY"

Java

import com.moncreneau.ApiClient;
import com.moncreneau.model.Appointment;

ApiClient client = new ApiClient("your_api_key");
Appointment appointment = client.appointments().get(123L);

System.out.println("Status: " + appointment.getStatus());
System.out.println("Date: " + appointment.getDateTime());
System.out.println("Beneficiary: " + appointment.getName());

Node.js

const { MoncreneauClient } = require('moncreneau');

const client = new MoncreneauClient('your_api_key');
const appointment = await client.appointments.get(123);

console.log(`Status: ${appointment.status}`);
console.log(`Date: ${appointment.dateTime}`);
console.log(`Beneficiary: ${appointment.name}`);

PHP

<?php
use Moncreneau\Client;

$client = new Client('your_api_key');
$appointment = $client->appointments->get(123);

echo "Status: {$appointment->status}" . PHP_EOL;
echo "Date: {$appointment->dateTime}" . PHP_EOL;
echo "Beneficiary: {$appointment->name}" . PHP_EOL;

Python

from moncreneau import MoncreneauClient

client = MoncreneauClient('your_api_key')
appointment = client.appointments.get(123)

print(f"Status: {appointment.status}")
print(f"Date: {appointment.date_time}")
print(f"Beneficiary: {appointment.name}")

Response 200

{
  "id": 123,
  "dateTime": "2026-02-15T10:00:00",
  "status": "CONFIRMED",
  "name": "Amadou Diallo",
  "qrCode": "QR-MONC-123-ABC",
  "departmentId": 5,
  "departmentName": "General Consultation",
  "createdAt": "2026-01-21T09:30:00"
}

Response 404

{
  "code": "APPOINTMENT_NOT_FOUND",
  "message": "Appointment not found with id: 123",
  "timestamp": "2026-01-21T10:00:00"
}

---

GET /appointments

List all appointments in your organization with pagination and optional filters.

Available filters

You can filter by status, departmentId, externalUserId, startDate, endDate and paginate with page and size.

Request

curl -X GET "https://mc-prd.duckdns.org/api/v1/appointments?page=0&size=20&status=SCHEDULED" \
-H "X-API-Key: YOUR_API_KEY"

Java

import com.moncreneau.ApiClient;
import com.moncreneau.model.AppointmentPage;

ApiClient client = new ApiClient("your_api_key");

// Simple list
AppointmentPage page = client.appointments().list();

// With filters
AppointmentPage filtered = client.appointments()
    .list()
    .status("SCHEDULED")
    .departmentId(5L)
    .externalUserId("customer_12345")
    .page(0)
    .size(20)
    .execute();

System.out.println("Total: " + filtered.getTotalElements());
for (Appointment apt : filtered.getAppointments()) {
    System.out.println(apt.getName() + " - " + apt.getDateTime());
}

Node.js

const { MoncreneauClient } = require('moncreneau');

const client = new MoncreneauClient('your_api_key');

// Simple list
const page = await client.appointments.list();

// With filters
const filtered = await client.appointments.list({
  page: 0,
  size: 20,
  status: 'SCHEDULED',
  departmentId: '5',
  externalUserId: 'customer_12345',
  startDate: '2026-02-01T00:00:00',
  endDate: '2026-02-28T23:59:59'
});

console.log(`Total: ${filtered.totalElements}`);
filtered.appointments.forEach(apt => {
  console.log(`${apt.name} - ${apt.dateTime}`);
});

PHP

<?php
use Moncreneau\Client;

$client = new Client('your_api_key');

// Simple list
$page = $client->appointments->list();

// With filters
$filtered = $client->appointments->list([
    'page' => 0,
    'size' => 20,
    'status' => 'SCHEDULED',
    'departmentId' => 5,
    'externalUserId' => 'customer_12345',
    'startDate' => '2026-02-01T00:00:00',
    'endDate' => '2026-02-28T23:59:59'
]);

echo "Total: {$filtered->totalElements}" . PHP_EOL;
foreach ($filtered->appointments as $apt) {
    echo "{$apt->name} - {$apt->dateTime}" . PHP_EOL;
}

Python

from moncreneau import MoncreneauClient

client = MoncreneauClient('your_api_key')

# Simple list
page = client.appointments.list()

# With filters
filtered = client.appointments.list(
    page=0,
    size=20,
    status='SCHEDULED',
    department_id='5',
    external_user_id='customer_12345',
    start_date='2026-02-01T00:00:00',
    end_date='2026-02-28T23:59:59'
)

print(f"Total: {filtered['totalElements']}")
for apt in filtered['appointments']:
    print(f"{apt['name']} - {apt['dateTime']}")

Query Parameters

Parameter	Type	Default	Description
page	integer	0	Page number (starts at 0)
size	integer	20	Items per page (max 100)
status	string	-	Filter by status (SCHEDULED, COMPLETED, CANCELLED, MISSED)
departmentId	integer	-	Filter by department ID
externalUserId	string	-	Filter by your external user ID
startDate	string (ISO 8601)	-	Appointments after this date
endDate	string (ISO 8601)	-	Appointments before this date

Response 200

{
  "appointments": [
    {
      "id": 123,
      "dateTime": "2026-02-15T10:00:00",
      "status": "SCHEDULED",
      "name": "Amadou Diallo",
      "qrCode": "QR-MONC-123-ABC",
      "departmentId": 5,
      "departmentName": "General Consultation",
      "externalUserId": "customer_12345",
      "createdAt": "2026-01-21T09:30:00"
    },
    {
      "id": 124,
      "dateTime": "2026-02-15T14:00:00",
      "status": "SCHEDULED",
      "name": "Fatoumata Camara",
      "qrCode": "QR-MONC-124-DEF",
      "departmentId": 5,
      "departmentName": "General Consultation",
      "createdAt": "2026-01-21T10:15:00"
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 45,
  "totalPages": 3,
  "isLast": false
}

---

DELETE /appointments/{id}

Cancel an appointment and automatically refund 1 credit to your organization.

Request

curl -X DELETE https://mc-prd.duckdns.org/api/v1/appointments/123 -H "X-API-Key: YOUR_API_KEY"

Java

import com.moncreneau.ApiClient;
import com.moncreneau.model.Appointment;

ApiClient client = new ApiClient("your_api_key");
Appointment cancelled = client.appointments().cancel(123L);

System.out.println("Appointment cancelled");
System.out.println("New status: " + cancelled.getStatus());
System.out.println("1 credit refunded");

Node.js

const { MoncreneauClient } = require('moncreneau');

const client = new MoncreneauClient('your_api_key');
const cancelled = await client.appointments.cancel(123);

console.log('Appointment cancelled');
console.log(`New status: ${cancelled.status}`);
console.log('1 credit refunded');

PHP

<?php
use Moncreneau\Client;

$client = new Client('your_api_key');
$cancelled = $client->appointments->cancel(123);

echo "Appointment cancelled" . PHP_EOL;
echo "New status: {$cancelled->status}" . PHP_EOL;
echo "1 credit refunded" . PHP_EOL;

Python

from moncreneau import MoncreneauClient

client = MoncreneauClient('your_api_key')
cancelled = client.appointments.cancel(123)

print('Appointment cancelled')
print(f'New status: {cancelled.status}')
print('1 credit refunded')

Response 200

{
  "id": 123,
  "dateTime": "2026-02-15T10:00:00",
  "status": "CANCELLED",
  "name": "Amadou Diallo",
  "qrCode": "QR-MONC-123-ABC",
  "departmentId": 5,
  "departmentName": "General Consultation",
  "createdAt": "2026-01-21T09:30:00"
}

Response 404

{
  "code": "APPOINTMENT_NOT_FOUND",
  "message": "Appointment not found with id: 123",
  "timestamp": "2026-01-21T10:00:00"
}

---

Error Handling

All errors return a standardized object:

{
  code: string;      // Error code (e.g., INSUFFICIENT_CREDITS)
  message: string;   // Human-readable message
  timestamp: string; // Error date/time
}

Common Error Codes

Code	HTTP	Description
INSUFFICIENT_CREDITS	402	Not enough credits to create an appointment
APPOINTMENT_NOT_FOUND	404	Appointment not found
INVALID_REQUEST	400	Invalid request (validation failed)
UNAUTHORIZED	401	Invalid or missing API Key
FORBIDDEN	403	Resource does not belong to your organization
INTERNAL_ERROR	500	Internal server error