API Conventions

Base URL

The Minimo API is served from two base URLs, depending on the endpoint:

Server	Base URL	Endpoints
New API	`https://api.minimo.it`	Contacts, WhatsApp, Custom Fields, Email Templates
Legacy API	`https://app.minimo.it`	Messages, Campaigns

Example Endpoints:

POST https://api.minimo.it/public/v1/contacts
GET  https://api.minimo.it/public/v1/templates/whatsapp
GET  https://api.minimo.it/public/v1/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": "customer@example.com",
  "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": "customer@example.com",
  "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:

Code	Meaning	Description
`200`	OK	Request succeeded
`201`	Created	Resource successfully created
`400`	Bad Request	Invalid request format or parameters
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	API key lacks required permissions
`404`	Not Found	Resource doesn’t exist
`422`	Unprocessable Entity	Validation error (invalid data)
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error (contact support)
`503`	Service Unavailable	Temporary service disruption

Common Error Codes

Error Code	HTTP Status	Description
`unauthorized`	401	Invalid or missing API key
`forbidden`	403	Insufficient permissions
`not_found`	404	Resource not found
`validation_error`	422	Invalid input data
`rate_limit_exceeded`	429	Too many requests
`template_not_approved`	422	WhatsApp template not approved by Meta
`invalid_phone_number`	422	Phone number format invalid
`duplicate_resource`	409	Resource 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": "user1@example.com" },
    { "id": "cnt_2", "email": "user2@example.com" }
  ],
  "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:

Monitor X-RateLimit-Remaining header
Implement exponential backoff
Respect the Retry-After header value
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/public/v1/contacts

# Legacy API - no version prefix
POST https://app.minimo.it/api/transactionals

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:

Email: info@minimo.it
Check API Status for known issues

Overview

Core Data

Messaging Channels

Legacy (Deprecated)

Base URL

Request Format

Content Type

Request Body

Response Format

Success Response

Error Response

HTTP Status Codes

Common Error Codes

Parameters

Example Request

Response Structure

Filtering & Sorting

Filtering (Coming Soon)

Sorting (Coming Soon)

Timestamps

Idempotency

Rate Limiting

Headers

Handling Rate Limits

Versioning

CORS (Cross-Origin Requests)

Webhooks (Coming Soon)

Testing

Test Mode (Coming Soon)

Need Help?

​Base URL

​Request Format

​Content Type

​Request Body

​Response Format

​Success Response

​Error Response

​HTTP Status Codes

​Common Error Codes

​Pagination

​Parameters

​Example Request

​Response Structure

​Filtering & Sorting

​Filtering (Coming Soon)

​Sorting (Coming Soon)

​Timestamps

​Idempotency

​Rate Limiting

​Headers

​Handling Rate Limits

​Versioning

​CORS (Cross-Origin Requests)

​Webhooks (Coming Soon)

​Testing

​Test Mode (Coming Soon)

​Need Help?

Base URL

Request Format

Content Type

Request Body

Response Format

Success Response

Error Response

HTTP Status Codes

Common Error Codes

Pagination

Parameters

Example Request

Response Structure

Filtering & Sorting

Filtering (Coming Soon)

Sorting (Coming Soon)

Timestamps

Idempotency

Rate Limiting

Headers

Handling Rate Limits

Versioning

CORS (Cross-Origin Requests)

Webhooks (Coming Soon)

Testing

Test Mode (Coming Soon)

Need Help?