Rate Limiting & Performance

Rate Limits & Performance

Recommendations for Bulk Operations

• Use Bulk API Endpoints — Endpoints such as bulkCreateEntityValues, bulkUpsertEntityValues, and bulkUpdateEntityValues accept arrays of records in a single request, dramatically reducing total API calls.
• Batch Your Records — Group records into batches of 100–500 per bulk call. Implement exponential backoff when receiving 429 responses.
• Use Upsert for Migrations — The bulkUpsertEntityValues endpoint updates existing records or creates new ones based on matching criteria, handling duplicates gracefully without manual deduplication.
• Schedule During Off-Peak Hours — Run large initial migrations during off-peak hours to avoid impacting interactive users.
• Consider CSV Import as an Alternative — For one-time data loads where programmatic API access is not required, the platform’s Import/Export subsystem supports CSV-based bulk imports directly through the UI.

Security & Authentication

OAuth2 Token Lifecycle

Automated Token Refresh

1. Queries all integrations with a non-null oauth_refresh_token.
2. Calls each integration’s authorization endpoint with the stored refresh token to obtain new access and refresh tokens.
3. Updates the stored tokens (oauth_access_token, oauth_refresh_token, oauth_expires_at) — all encrypted at rest.
4. If a refresh fails, the job nullifies the expired tokens and sends in-app notifications to tenant administrators with re-authorization instructions. 

Integration Options for Your Middleware

API Credential Scoping & Permissions

• OAuth2 Scope-Based Permissions — API clients are created with a specific permissions array. Each permission maps to a defined set of GraphQL operations. For example, an integration scoped to account:read, account:create, deal:read, and deal:create would have zero access to Tasks, Activities, or other objects.
• Role-Based Access Control (RBAC) — The platform’s AuthorizationManager enforces role-level permissions at the entity and operation level. API credentials are associated with a specific user, and that user’s roles determine which Apps and records they can access.
• Access Control Lists (ACLs) — For fine-grained record-level access, ACLs can restrict which records within an App a given user (and therefore their API credentials) can see or modify. ACLs support conditions based on field values.

Available OAuth Scopes

Data Object Mapping: ERP ↔ Servis.ai

Standard Object Mapping

Custom App Mapping (Examples)

Platform API Stability & Compatibility

• Backward Compatibility Layer — The platform maintains an explicit backwardCompatibility module that preserves legacy API behaviors when schemas evolve. For example, task-related queries and mutations are aliased to their newer unified API equivalents, ensuring older integrations continue working without modification.
• Metadata-Driven Schema — Because the API is metadata-driven (field definitions and entity configurations are stored in the database, not hardcoded), structural changes to the data model do not break the API contract. New fields are additive — they appear in responses but do not remove existing fields.
• GraphQL Schema Stability — The GraphQL schema is generated dynamically from entity configurations. Adding new types, fields, or mutations is inherently non-breaking in GraphQL. Breaking changes (removing fields, changing types) are avoided.
• Migration Safeguards — Database migrations are applied incrementally with DDL/DML scripts, and the platform maintains full migration history. Any API-breaking schema changes would require coordinated migration and advance communication.  

Integration Environments & Testing

Staging Environment

Tenant Isolation

Clone Tenants

Integration Test Modal

Outbound Webhooks for Real-Time Triggers

• Webhook Endpoints — The platform exposes a dedicated webhook system at /webhook/{teamId}/{webhookId} that can be configured to fire when record events occur. For example, when a Deal closes, an automation rule can trigger an outbound HTTP call to your external system’s endpoint.
• Execution Modes — Webhooks support two execution modes — synchronous (the caller waits for a response) and asynchronous (fire-and-forget with job queuing). For most integration scenarios, async mode is recommended.
• Custom Payload Transformation — Webhook handlers can execute custom JavaScript code, giving full control over payload transformation. You can map servis.ai record fields directly to your external system’s expected schema before the HTTP request is sent.
• Security — Webhooks support signature verification (secure_webhook flag) to validate inbound requests to your systems.
• Execution Audit Trail — Every webhook execution is tracked with its own job_run record, including the automation triggered, response body, and links to workflow history — providing a complete audit trail for troubleshooting.

Monitoring & Diagnosis

• Structured Logging — All API calls, webhook executions, integration runs, and OAuth flows are logged through the platform’s structured logging system (FALogger). Logs include contextual metadata for rapid diagnosis.
• Job Run History — Job runs (including webhook executions) are stored in the job_run table with full execution details, input/output payloads, and error information.
• Proactive Token Monitoring — The scheduled refresh_integration_job continuously monitors OAuth token health. If a token refresh fails (e.g., external credentials expire), the system automatically nullifies the expired tokens and sends in-app notifications to tenant administrators.