API Integration Best Practices

Secrets and taxpayer-data boundaries

• Call authenticated B2B APIs only from an authorised server, never from the browser.
• Use an environment secret manager, scoped access and redacted operational logs.
• Validate the legal basis and explicit consent for portal passwords, PAN and Aadhaar processing.
• Restrict taxpayer record access, define retention periods and encrypt stored sensitive fields.

Tracking and correlation

The source recommends deterministic external_correlation_id values for audit traceability. Keep your internal transaction reference linked to the Tax Genius tracking_id.

• Generate a unique partner correlation reference for each intended business operation.
• Record operation type, request timestamp, tracking ID and the last verified status.
• Do not claim server-side idempotency unless the backend verifies it.

Webhook-first with bounded polling fallback

The reference implementation uses signed webhooks as the primary status mechanism and suggests polling GET /applications/{tracking_id}/status every four to five seconds while a case is active.

• Stop polling on processed, completed or rejected.
• Reduce or suspend polling while the client is hidden or the network is offline.
• Apply rate limits and backoff before rollout; the backend has not supplied a formal public quota.

Document handling

The endpoint guide states a maximum upload size of 10 MB for PDF, JPEG and PNG. The reference implementation independently recommends compressing files to below 5 MB to improve compatibility.

10 MB is documented as an endpoint limit; 5 MB is an implementation recommendation, not a conflicting enforced server limit.

Go-live checklist

• Validate the live FastAPI OpenAPI schema and endpoint responses.
• Verify service enablement, payment mode and webhook registration.
• Test positive, negative and duplicate-event paths.
• Verify sensitive-data and security controls with the authorised operations team.
• Use separate production credentials from any development fixtures.