Home API & Integrations. API & Integrations.

API & Integrations.

Last updated on Mar 05, 2026

1) API overview
Thunaivi API allows secure integration with CRM, helpdesk, ticketing, billing, and custom backend systems for support automation workflows.

2) Base URL and auth

  • Base URL: https://app.thunaivi.io/api/v1

  • Auth header: Authorization: Bearer <API_KEY>

  • Content type: application/json

Use server-to-server only. Never expose API keys in frontend.

3) API key lifecycle

  • Generate key from client/admin portal

  • Show full secret once

  • Store only hashed secret in backend

  • Rotate keys regularly

  • Revoke immediately if compromised

4) Required key controls

  • Scope-based access

  • IP allowlist (optional but recommended)

  • Per-key rate limit

  • Expiry date support

  • Key status (active / revoked)

5) Common integration use cases

  • Create ticket from customer chat

  • Sync CRM contact/customer data

  • Push conversation updates to external systems

  • Trigger workflows from webhook events

  • Pull analytics into BI dashboards

6) CRM ticket sync flow (recommended)

  1. Customer message enters Thunaivi

  2. Intent/rule decides external sync

  3. API call creates/updates CRM ticket

  4. Ticket ID stored in conversation metadata

  5. Status updates are synced both ways

7) Webhook events
Useful events:

  • conversation.created

  • message.created

  • conversation.assigned

  • conversation.resolved

Always validate webhook signature before processing.

8) Retry + idempotency
For safe integrations:

  • Use idempotency key for create calls

  • Retry transient failures with backoff

  • Log request_id for every failed call

  • Make consumers retry-safe

9) Error handling model
Expect:

  • 401 invalid/missing token

  • 403 scope/permission denied

  • 429 rate limit exceeded

  • 422 validation error

  • 500 temporary server issue

Handle each with clear retry/escalation logic.

10) Integration security checklist

  • Keep API keys in server env/secret manager

  • Rotate keys every 60–90 days

  • Restrict by scope + IP

  • Store minimal PII

  • Audit integration logs regularly

  • Alert on abnormal usage spikes

11) Integration readiness checklist

  • Sandbox test done

  • Auth validated

  • Rate-limit handling implemented

  • Webhook signature validation done

  • Monitoring + alerts enabled

  • Rollback plan ready

12) Go-live best practices

  • Start with one integration path first

  • Monitor for 48 hours before scaling

  • Track failure ratio and latency

  • Document ownership for integration incidents