Skip to main content

​
Base URL

The Minimo API is served from two base URLs, depending on the endpoint:
ServerBase URLEndpoints
New APIhttps://api.minimo.itContacts, WhatsApp, Custom Fields
Legacy APIhttps://app.minimo.itEmail templates, Messages, Campaigns
Example Endpoints: 
POST https://api.minimo.it/v1/contacts
GET  https://api.minimo.it/v1/templates/whatsapp
GET  https://app.minimo.it/api/templates/email
All requests must use HTTPS. HTTP requests will be rejected.
New endpoints are being progressively migrated to api.minimo.it. Each endpoint’s documentation page specifies the correct base URL.

​
Request Format

​
Content Type

All POST, PUT, and PATCH requests must include the Content-Type header: 
Content-Type: application/json

​
Request Body

Request bodies should be valid JSON: 
{
  "email": "[email protected]",
  "firstName": "Jane",
  "customFields": {
    "company": "Acme Corp",
    "plan": "enterprise"
  }
}

​
Response Format

​
Success Response

Successful requests return appropriate HTTP status codes and JSON responses: Example (200 OK): 
{
  "id": "cnt_abc123",
  "email": "[email protected]",
  "firstName": "Jane",
  "lastName": "Doe",
  "createdAt": "2025-11-13T10:30:00Z",
  "updatedAt": "2025-11-13T10:30:00Z"
}

​
Error Response

Errors return a consistent structure: 
{
  "error": {
    "code": "validation_error",
    "message": "Invalid email address format",
    "details": {
      "field": "email",
      "value": "invalid-email"
    }
  }
}
Error Object Fields:
  • code: Machine-readable error identifier
  • message: Human-readable error description
  • details: Additional context (optional)

​
HTTP Status Codes

The Minimo API uses standard HTTP status codes:
CodeMeaningDescription
200OKRequest succeeded
201CreatedResource successfully created
400Bad RequestInvalid request format or parameters
401UnauthorizedMissing or invalid API key
403ForbiddenAPI key lacks required permissions
404Not FoundResource doesn’t exist
422Unprocessable EntityValidation error (invalid data)
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error (contact support)
503Service UnavailableTemporary service disruption

​
Common Error Codes

Error CodeHTTP StatusDescription
unauthorized401Invalid or missing API key
forbidden403Insufficient permissions
not_found404Resource not found
validation_error422Invalid input data
rate_limit_exceeded429Too many requests
template_not_approved422WhatsApp template not approved by Meta
invalid_phone_number422Phone number format invalid
duplicate_resource409Resource already exists

​
Pagination

List endpoints support pagination using query parameters:

​
Parameters

  • page: Page number (default: 1)
  • limit: Items per page (default: 25, max: 100)

​
Example Request

GET /v1/contacts?page=2&limit=50

​
Response Structure

{
  "data": [
    { "id": "cnt_1", "email": "[email protected]" },
    { "id": "cnt_2", "email": "[email protected]" }
  ],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 150,
    "totalPages": 3,
    "hasNext": true,
    "hasPrevious": true
  }
}
Pagination Fields:
  • page: Current page number
  • limit: Items per page
  • total: Total number of items
  • totalPages: Total number of pages
  • hasNext: Whether there’s a next page
  • hasPrevious: Whether there’s a previous page

​
Filtering & Sorting

​
Filtering (Coming Soon)

Some endpoints support filtering using query parameters: 
GET /v1/contacts?tag=vip&status=active

​
Sorting (Coming Soon)

Use the sort parameter to order results: 
GET /v1/contacts?sort=-createdAt
# - prefix for descending, + or no prefix for ascending

​
Timestamps

All timestamps are returned in ISO 8601 format (UTC): 
{
  "createdAt": "2025-11-13T10:30:00Z",
  "updatedAt": "2025-11-13T14:45:30Z"
}

​
Idempotency

Some endpoints support idempotency keys to prevent duplicate operations: 
POST /v1/contacts
Idempotency-Key: unique-key-12345
Use idempotency keys when retrying failed requests to avoid creating duplicates.

​
Rate Limiting

​
Headers

All responses include rate limit information: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699889400
  • X-RateLimit-Limit: Maximum requests per window
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp when limit resets

​
Handling Rate Limits

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response: 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "retry_after": 60
  }
}
Best Practices:
  1. Monitor X-RateLimit-Remaining header
  2. Implement exponential backoff
  3. Respect the Retry-After header value
  4. Cache responses when possible

​
Versioning

The current API version is v1.
  • New API (api.minimo.it): The version prefix /v1/ is required in all paths.
  • Legacy API (app.minimo.it): Paths use the /api/ prefix without version number.
# New API - version prefix required
POST https://api.minimo.it/v1/contacts

# Legacy API - no version prefix
GET  https://app.minimo.it/api/templates/email

​
CORS (Cross-Origin Requests)

The Minimo API supports CORS for client-side requests. However, we recommend making API calls from your server to keep API keys secure. Allowed origins are configurable per API key in your dashboard settings.

​
Webhooks (Coming Soon)

Minimo will support webhooks for real-time event notifications:
  • Message delivered
  • Message failed
  • Contact created/updated
  • Template approved/rejected
Documentation will be added when webhooks are available.

​
Testing

​
Test Mode (Coming Soon)

Use test mode to experiment without affecting production data: 
Authorization: Bearer mn-test-abc123-xyz789
Test API keys start with mn-test- prefix.

​
Need Help?

If you encounter unexpected behavior or have questions about API conventions: