Usage Guidelines & Best Practices
| Version | Date |
|---|---|
| 1.0 | May 01, 2025 |
iMIS provides a secure and scalable API to support partner integration. While access is currently free of charge, all use must be efficient and respectful to ensure stable performance for all consumers.
To support long-term reliability and scalability, we are introducing the following strategies:
- Rate Limiting: Safeguards to prevent abuse and ensure fair access across users.
- Usage Tiers: A future tiered model will accommodate various usage needs—from testing to high-volume production.
- Transparency Tools: Partners will have visibility into their usage and limits to prevent disruptions.
Until these controls are live, partners are expected to:
- Use the API in a production-appropriate, efficient manner.
- Avoid excessive polling or bulk operations without coordination.
- Notify us proactively of expected surges in traffic.
General Usage Expectations
- Treat the API as a shared, metered resource.
- Understand that usage affects system performance for all clients.
- API access is a privilege and may be throttled or revoked if abused.
Prohibited Practices
| Prohibited Practice | Description |
|---|---|
| Full-object polling | Never request entire datasets (e.g., all contacts). Use UpdatedOn filters. |
| Multi-threaded data pulls | Sync jobs must be single-threaded per client—no parallel data pulls. |
| Synchronized multi-client syncs | Do not sync multiple clients simultaneously. Stagger jobs to reduce load. |
| Excessive polling | Limit API polling to once per hour per client. |
| Full directory scans | Avoid recurring large unfiltered queries. |
| Bulk downloading expensive objects | Do not bulk download contacts or similar entities. |
Required Best Practices
| Best Practice | Description |
|---|---|
| Incremental Syncing | Use filters like UpdatedOn to fetch only new or modified records. Avoid full dataset access. |
| Optimized Custom Queries | Design queries to be efficient. Use indexes and avoid high-cost joins or wildcards. |
| Event-Driven Architecture | Migrate to Event Grid or webhooks for real-time updates instead of polling. |
| Use the Staging Environment | Validate performance, accuracy, and impact in staging before moving to production. |
| Low-Impact Background Jobs | Ensure background syncs do not degrade performance for live user sessions. |
Discouraged but Tolerated
The following practice is discouraged and should only be used when necessary:
- Pulling a full list for mailings when no recent copy exists - Instead, use filtered fetches and cache list states when possible. Pull lists on-demand only when necessary.
Data Hygiene and Governance
| Practice | Description |
|---|---|
| Minimum Necessary Access | Only retrieve and store data essential to your integration. |
| Data Retention & Purging | Regularly purge stale or unused data. Avoid hoarding customer information. |
| Privacy Compliance | Adhere to GDPR, CCPA, and honor deletion and export requests. |
| Secure Storage | Encrypt all stored and transmitted data, with limited access to essential systems. |
Monitoring, Observability & Integration Control
| Practice | Description |
|---|---|
| API Usage Logging | Partners must log all API calls, responses, and failures for diagnostics. |
| Error Monitoring | Implement alerting for retries, 5xx/429 errors, and unusual behavior. |
| Kill Switch Capability | Integrations must have a way to disable API activity during emergencies. |
Enforcement & Future Considerations
We reserve the right to monitor API usage and contact partners about violations. Severe or repeated abuse may lead to throttling or suspension. If these behaviors persist, usage-based pricing may be enforced to ensure fair access for all users.
Throttling
To maintain a stable environment, we will introduce soft throttling mechanisms based on the following principles:
- Default soft limit: ~5,000 requests/hour per client (subject to revision).
- Bursting: Short bursts above limits may be allowed if overall usage remains reasonable.
- Fairness: Throttling will prioritize stability and fairness across all partners.
- Notification: Partners will receive alerts when nearing or exceeding thresholds.
Usage-Based Pricing
To support continued investment and scalability, we plan to introduce usage-based pricing with the following considerations:
- Free Tier: Generous limits suitable for development and low-volume use.
- Paid Tiers: Options for higher volume and commercial-grade support.
- Transparent Metering: Partners will have access to usage dashboards and alerts.
- Grace Periods: Transition plans will include grace periods and partner support.
Final Guidance
Pulling large datasets frequently, using inefficient sync strategies, or running unoptimized queries threatens platform stability and customer trust. All partners must prioritize efficient, incremental data access and build with long-term performance in mind.
Updated about 2 hours ago