The MegatronLead API: a technical introduction

The MegatronLead REST API is the programmatic surface that mirrors the operational surface in the UI. Anything you can do as a user, you can do as a scoped service account through the API. The access model is identical: the API does not bypass the security boundaries; it inherits them.

This is a technical introduction for engineers integrating with MegatronLead.

Authentication and scoped tokens

Authentication is via API keys. Each key is scoped:

• Operation scope. Read-only, write specific resources, full access. Keys are issued with the minimum scope they need.
• Market scope. A key for the India team has India market authorization. The same key cannot read United States data.
• Team scope. Optionally narrower than market: a specific team within a market.

A request authenticates by sending the API key in the Authorization header. The server validates, attaches the key's scope to the request session, and proceeds. From that point, every database query is automatically filtered by the scope.

This is the same enforcement model as user sessions. A scoped service account is, structurally, a non-human user with the access rules its scope defines.

The implication: an integration that needs cross-market read access requires a service account explicitly authorized for that scope, audited separately, with documented purpose. There is no "admin override" that bypasses the model.

Endpoint structure

The API follows REST conventions:

• GET /api/v1/leads to list with filters.
• GET /api/v1/leads/:id for a single lead.
• POST /api/v1/leads to create.
• PATCH /api/v1/leads/:id to update.
• POST /api/v1/leads/:id/state to transition state.

Resource paths under /api/v1 are versioned. Backward-incompatible changes get a new major version; deprecation cycles are documented in the contract.

Pagination

List endpoints return cursor-based pages, not offset-based. The response includes:

• An array of records up to the page size.
• A cursor for the next page, if more records exist.

Cursor pagination handles the case where records are inserted or deleted between page fetches without producing duplicates or gaps. Offset pagination, common in older APIs, does not handle this cleanly.

Default page size is 50 records. Maximum is 200. Clients fetching large result sets should iterate using the cursor, not request larger pages.

Error semantics

Errors return a structured response:

The HTTP status code indicates the category:

• 400 for malformed request (bad JSON, missing required fields, invalid filter).
• 401 for missing or invalid authentication.
• 403 for authenticated but unauthorized (the request would access data outside the key's scope).
• 404 for resource not found within the key's scope (note: a record outside the scope returns 404, not 403, to avoid leaking existence information).
• 422 for validation errors (the request is shape-correct but the data violates a rule).
• 429 for rate-limit exceeded.
• 500 for unexpected server errors.

The body includes a stable error code (a short slug like "validation_failed") plus a human-readable message and (for validation errors) a per-field error breakdown.

Stable error codes let integrations branch on them without parsing message text.

Rate limits

Rate limits are documented per endpoint:

• Read endpoints: typically 600 requests per minute per key.
• Write endpoints: typically 120 requests per minute per key.
• Bulk endpoints (CSV import, batch dedupe): lower limits with specific quotas.

Rate limit responses include headers for current usage and time to reset. A well-behaved client respects these and applies backoff when approaching limits.

For workloads that exceed default limits, contact sales for enterprise-tier quotas.

Idempotency

Write endpoints accept an Idempotency-Key header. Two requests with the same key are deduplicated at the server: the second one returns the same response as the first without re-processing.

This is critical for integrations that may retry on transient errors. Without idempotency keys, retries can create duplicate leads or duplicate state transitions.

The idempotency key is opaque to the server; the client generates it (a UUID or a deterministic hash of the request content).

Webhook signatures

For outbound webhooks (events MegatronLead sends to your systems), payloads are HMAC-signed. Your endpoint verifies the signature before trusting the payload.

The signature is computed over the request body using a shared secret. Your endpoint computes the same hash and compares.

This prevents both replay attacks (with timestamp validation) and forged payloads (without the secret, an attacker cannot produce a valid signature).

Sample verification logic is documented; libraries for common languages handle the mechanics.

Common integration patterns

Three patterns recur:

Pattern 1: lead ingestion. Your custom system creates leads via POST /api/v1/leads with the lead's attributes and source. MegatronLead canonicalizes, deduplicates, routes, and returns the canonical lead ID.

Pattern 2: event-driven response. MegatronLead fires outbound webhooks when state changes, assignments happen, SLAs breach. Your system subscribes to relevant event types and handles each.

Pattern 3: read-only sync. Your data warehouse or BI tool pulls lead data periodically via GET endpoints. The data warehouse maintains a copy of the canonical lead model for analytics.

Each pattern has documented best practices and reference implementations.

What to test

When integrating with the API, the integration test suite should cover:

• Authentication failures return 401 cleanly.
• Out-of-scope requests return 404 (not 403, not data).
• Rate limit headers are respected.
• Idempotency keys deduplicate correctly.
• Webhook signature verification is enforced.
• Pagination iterates correctly to completion.

A well-tested integration is the difference between a stable production integration and one that produces incidents.

For broader information on programmatic surfaces, see integrations.