Skip to main content

Quick Start Guide

Create your first appointment with the moncreneau API in less than 5 minutes! ⚡

Prerequisites​

Step 1: Get your API key​

  1. Log in to your moncreneau dashboard
  2. Navigate to Settings → API
  3. Click Create an API key
  4. Choose the required scopes (minimum: READ_APPOINTMENTS, WRITE_APPOINTMENTS)
  5. Copy your API key
Important

Keep your API key secure! It will only be displayed once. Never commit it to your source code.

Step 2: Test the connection​

Verify that your API key works by listing available departments:

Terminal
curl -X GET https://mc-prd.duckdns.org/api/v1/departments -H "X-API-Key: YOUR_API_KEY"

Expected response:

[
  {
    "id": 5,
    "name": "Passport Service",
    "address": "123 Rue de la Santé, Conakry",
    "phoneNumber": "+224 123 456 789",
    "slotInterval": 30,
    "workingHours": "Mon-Fri: 08:00-17:00"
  },
  {
    "id": 8,
    "name": "ID Card Service",
    "address": "456 Avenue de la République",
    "phoneNumber": "+224 987 654 321",
    "slotInterval": 15,
    "workingHours": "Mon-Fri: 08:00-17:00"
  }
]

Step 3: Create an appointment​

Now, create your first appointment:

Terminal
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-01-25T14:30:00",
  "name": "Jean Dupont"
}'

Response:

{
  "id": 12345,
  "departmentId": 5,
  "dateTime": "2026-01-25T14:30:00",
  "status": "SCHEDULED",
  "name": "Jean Dupont",
  "qrCode": "a1b2c3d4-...",
  "createdAt": "2026-01-21T10:30:00"
}

🎉 Congratulations! You've created your first appointment!

Step 4: Retrieve an appointment​

Get the details of an appointment:

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

Step 5: Cancel an appointment​

If necessary, cancel an appointment:

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

This call archives the appointment (its status does not change) and returns a 200 with no body. It does not automatically refund a credit today — see Appointments Endpoints.

Use an SDK​

Prefer using an SDK? Only Node.js and Python are published today (PHP and Java exist as source code but are not yet published — see PHP SDK and Java SDK).

Node.js​

// Installation: npm install @moncreneau/api
import Moncreneau from '@moncreneau/api';

const client = new Moncreneau('YOUR_API_KEY');

// Create an appointment
const appointment = await client.appointments.create({
  departmentId: 5,
  dateTime: '2026-01-25T14:30:00',
  name: 'Jean Dupont',
  workerId: 42, // Optional (required if showAdminsInBooking=true)
});

console.log('Appointment created:', appointment.id);

Python​

# Installation: pip install moncreneau
from moncreneau import Moncreneau

client = Moncreneau('YOUR_API_KEY')

# Create an appointment
appointment = client.appointments.create(
    department_id=5,
    date_time='2026-01-25T14:30:00',
    name='Jean Dupont',
    worker_id=42  # Optional (required if showAdminsInBooking=true)
)

print(f"Appointment created: {appointment['id']}")

Understanding rate limits​

Each API response includes rate limiting headers:

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1642435200
  • X-RateLimit-Limit: Maximum number of requests per hour
  • X-RateLimit-Remaining: Remaining requests
  • X-RateLimit-Reset: Unix timestamp of reset
Limit reached

If you exceed the limit, you'll receive a 429 Too Many Requests error with a Retry-After header.

Handling errors​

The API returns standard HTTP codes and structured error messages:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your organization has 0 credits remaining"
  }
}

Common error codes:

  • 401: Invalid or missing API key
  • 402: Insufficient credits
  • 404: Resource not found
  • 429: Rate limit exceeded

Next steps​

Now that you've made your first API call, explore:

Need help?​

Last updated on