Guidelines for integrating with the FAV3 Check API.

Authentication & Session Management

Token Lifecycle

Access tokens are valid for 24 hours. Check API integrations should cache tokens and reuse them.

1. Cache tokens: Don't request a new token for every check. Cache it until expiry.
2. Handle expiry: If you receive 403 Forbidden, automatically re-authenticate and retry.
3. Secure credentials: Store API credentials in environment variables, not in code.

# Example: Token caching
if token_expired():
    token = get_new_token()
    cache_token(token)

Phone Number Formatting

Always Use Request Format

All phone numbers must use the format: +<countrycode>-<number>

Performance Tips

Use Check Endpoint Efficiently

The /v1/favorites/check endpoint is optimized for high-volume lookups (e.g., call routing).

• Real-time capable: Designed for low latency.
• Combined Validation: Automatically validates subscriber status and plan in one call.
• Status Codes: Returns 200 OK even if the number is not a favorite (check is_favorite boolean), preventing exception handling overhead for normal business logic.

Error Handling

Implement Retry Logic

For 502 and 504 errors (upstream API issues), implement exponential backoff.

Handle Authentication Errors

For 403 errors, the token is invalid or expired. Re-authenticate immediately.

Integration Checklist

• Token caching implemented (24-hour expiry)
• Session expiry handling (retry on 403)
• Phone number formatting validated client-side
• Retry logic for upstream errors (502, 504)
• Rate limiting handled (429 responses)
• Secure credential storage