Authentication and API Key Management

Use one API key per environment (e.g., development, staging, production) to isolate access and prevent accidental data leaks or unwanted side effects.

• Use separate API keys for each developer or service to enable fine-grained access control and auditability.
• Rotate API keys regularly and immediately revoke compromised keys.

Error Handling & Rate Limiting

• Implement exponential backoff with jitter when retrying requests after receiving 429 (Too Many Requests) or 5xx responses.
• Respect Callr’s rate limits, and avoid aggressive retry loops that could lead to throttling or bans.
• Log and monitor response codes to identify patterns in failed requests.

Environment Isolation

• Use sandbox/test credentials in non-production environments to avoid polluting live data or incurring charges during development.
• We do NOT provide a sandbox environment/API, but you can create a separate sandbox account (in build mode, or in production).
• Keep test numbers, call flows, and configurations separate from production setups.

Webhooks & Callbacks

• Verify incoming requests using the HMAC signature to prevent spoofing.
• Make webhook handlers idempotent and resilient — they may be called multiple times or out of order. We always provide a unique event_id.
• Respond quickly (under 5 seconds) to avoid timeouts and retries from Callr.

Versioning & Schema Awareness

• Always check for breaking changes or deprecations.
• When using OpenAPI tooling, validate requests and responses to ensure conformance with the latest schema.

Dynamic Phone Numbers

We strongly recommend avoiding an "on-demand" buy/release process via the API. In our experience, this approach introduces unnecessary complexity, increases the risk of bugs, and can lead to billing misunderstandings. Moreover, releasing numbers too quickly places them in mandatory quarantine, temporarily removing them from circulation and reducing overall number availability.

In some cases, particularly in specific countries or regions, regulators require manual approval for number orders. As a result, API-based requests may be placed in backorder, meaning the numbers won’t be available immediately.

Instead, we suggest purchasing a pool of numbers via our web interface and managing them on your side. This simplifies your integration, reduces operational overhead, and allows you to focus on leveraging the call data we provide. It’s also more cost-effective, as each phone number purchase includes a one-time, non-recurring charge (NRC).