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: appointments:read, appointments:create)
  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",
    "description": "Passport issuance",
    "organization": {
      "id": 1,
      "name": "Ministry of Interior"
    }
  },
  {
    "id": 8,
    "name": "ID Card Service",
    "description": "National ID card issuance",
    "organization": {
      "id": 1,
      "name": "Ministry of Interior"
    }
  }
]

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": "https://moncreneau.gn/qr/12345",
  "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"
Credits

1 credit will be refunded upon cancellation.

Use an SDK​

Prefer using an SDK? Here are the same operations with the 4 official SDKs:

Java​

// Installation: Maven
// <dependency>
//   <groupId>com.moncreneau</groupId>
//   <artifactId>moncreneau-java</artifactId>
//   <version>1.0.0</version>
// </dependency>

import com.moncreneau.Moncreneau;
import java.util.HashMap;
import java.util.Map;

public class Example {
    public static void main(String[] args) {
        Moncreneau client = new Moncreneau("YOUR_API_KEY");
        
        // Create an appointment
        Map<String, Object> data = new HashMap<>();
        data.put("departmentId", 5);
        data.put("dateTime", "2026-01-25T14:30:00");
        data.put("name", "Jean Dupont");
        
        Map<String, Object> appointment = client.appointments.create(data);
        System.out.println("Appointment created: " + appointment.get("id"));
    }
}

Node.js​

// Installation: npm install @moncreneau/api
const Moncreneau = require('@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);

PHP​

<?php
// Installation: composer require moncreneau/moncreneau-php
require 'vendor/autoload.php';

$client = new \Moncreneau\Moncreneau('YOUR_API_KEY');

// Create an appointment
$appointment = $client->appointments->create([
    'departmentId' => 5,
    'dateTime' => '2026-01-25T14:30:00',
    'name' => 'Jean Dupont',
    'workerId' => 42, // Optional (required if showAdminsInBooking=true)
]);

echo "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',
    user_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