Skip to main content
POST
/
api
/
contacts
Python
import requests

url = 'https://app.minimo.it/api/contacts'
headers = {'Authorization': 'Bearer {{BEARER_TOKEN}}', 'Content-Type': 'application/json'}
data = {
    'email': '{{email}}',
    'customFields': {
        '{{customKey1}}': '{{customValue1}}',
        '{{customKey2}}': '{{customValue2}}',
        '{{customKey3}}': '{{customValue3}}'
    }
}
response = requests.post(url, json=data, headers=headers)
print(response.json())
[
  {
    "contactId": "<string>"
  }
]
This endpoint performs an upsert operation: if a contact with the provided email already exists, it will be updated; otherwise, a new contact will be created.

​
Use Cases

  • Lead capture: Add new leads from website forms
  • CRM sync: Keep contacts in sync with your CRM
  • User registration: Create contacts when users sign up
  • Data enrichment: Update contact information with additional data

​
Custom Fields

You can store additional contact data using the customFields object: 
{
  "email": "[email protected]",
  "firstName": "Jane",
  "customFields": {
    "company": "Acme Corp",
    "plan": "enterprise",
    "signup_date": "2025-11-13",
    "trial_ends": "2025-12-13"
  }
}
Custom fields are flexible and don’t require pre-definition. You can add any key-value pairs you need.

​
Tags

Organize contacts using tags: 
{
  "email": "[email protected]",
  "tags": ["vip", "enterprise", "onboarding"]
}

​
Phone Numbers

For WhatsApp messaging, include a phone number in E.164 format: 
{
  "email": "[email protected]",
  "phone": "+393391234567"
}
Format Requirements:
  • Include country code (e.g., +39 for Italy, +1 for US)
  • No spaces, dashes, or parentheses
  • Example: +12025551234 (US), +393391234567 (Italy)
Invalid phone numbers will cause WhatsApp message sending to fail.

​
Best Practices

The POST /contacts endpoint automatically updates existing contacts based on email. This makes it perfect for periodic syncs without worrying about duplicates.
For importing many contacts, call the endpoint in batches rather than one at a time. Consider rate limits (100 req/min standard plan).
Always validate email addresses before submitting to avoid rejected requests.
Use consistent key names for custom fields across your application (e.g., signup_date vs signupDate).

​
Client-Side Usage

You can call this API from client-side applications (e.g., website forms), but we recommend using a dedicated API key with limited permissions (create contacts only).
Create a separate API key for client-side usage:
  1. Go to API Keys
  2. Create new key with only “Create/Update Contact” permission
  3. Set a short expiration (e.g., 3-6 months)
  4. Monitor usage regularly

​
Example: Website Form Integration

// Add to your form submission handler
async function handleFormSubmit(event) {
  event.preventDefault();

  const formData = new FormData(event.target);

  const response = await fetch('https://app.minimo.it/api/contacts', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_CLIENT_SIDE_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email: formData.get('email'),
      firstName: formData.get('firstName'),
      lastName: formData.get('lastName'),
      phone: formData.get('phone'),
      customFields: {
        source: 'website_form',
        page: window.location.pathname,
      },
      tags: ['lead', 'website'],
    }),
  });

  if (response.ok) {
    // Success - redirect to thank you page
    window.location.href = '/thank-you';
  } else {
    // Handle error
    const error = await response.json();
    console.error('Failed to create contact:', error);
  }
}

​
Common Errors

ErrorCauseSolution
validation_errorInvalid email formatCheck email address format
invalid_phone_numberPhone not in E.164 formatAdd country code, remove spaces
rate_limit_exceededToo many requestsImplement rate limiting, use batching
unauthorizedInvalid API keyVerify API key in Authorization header
  • GET /contacts (Coming Soon): List all contacts
  • GET /contacts/ (Coming Soon): Get a single contact
  • DELETE /contacts/ (Coming Soon): Delete a contact

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

​
email
string
required

Email address of the contact

​
phone
string

Phone number of the contact

​
customFields
object

Custom fields specific to the contact

Response

Successful response

​
contactId
string