Base URL & Authentication
Hosted production: https://api.jinaconnect.com · Sandbox: https://api.jinaconnect-dev.jinacode.systems
Every request requires a Bearer token. For service-to-service traffic, use an API key issued from your tenant settings. For interactive sessions, exchange credentials for a JWT pair.
POST/token/Exchange email + password for access & refresh JWT
POST/refresh/Refresh access token
API keys are scoped per tenant + per role. Live keys:
jc_live_...; sandbox: jc_test_...Tenants (multi-tenant workspaces)
Every customer workspace is a tenant. Agencies run 5–50 tenants on one deployment.
GET/tenants/onboarding-options/List available onboarding flows
GET/tenants/branding/Get tenant branding settings
PATCH/tenants/branding/Update custom domain, logo, email sender
GET/tenants/users/List tenant members
POST/tenants/members/invite/Invite a teammate
GET/tenants/roles/RBAC role list
GET/tenants/host-wallet/Get per-tenant wallet balance
GET/tenants/waba-info/WhatsApp Business Account metadata
GET/tenants/tenant-tags/Custom tenant tags for org-level filtering
Contacts
Unified contact directory across channels. Each contact carries phone, channel IDs, segments, custom attributes.
GET/contacts/List contacts (paginated, filterable)
POST/contacts/Create a contact
GET/contacts/{id}/Retrieve a contact
PATCH/contacts/{id}/Update contact attributes / segments
POST/contacts/bulk-import/CSV upload for bulk import
Broadcast (WhatsApp)
Schedule, send, and track WhatsApp template broadcasts.
GET/broadcast/List broadcasts
POST/broadcast/Create & queue a broadcast
GET/broadcast/{id}/Get broadcast detail
GET/broadcast/messages/List individual messages within broadcasts
GET/broadcast/url-tracking/Click events on shortened URLs
GET/broadcast/dashboard/Aggregate analytics (delivery, read, reply rates)
POST/wa/v1/messages/Send a template / session message
GET/wa/v1/messages/List sent & received messages
POST/wa/v1/templates/Submit a template for Meta approval
GET/wa/v1/templates/List templates and approval status
POST/wa/v1/webhooks/{tenant_id}/Meta-compliant inbound webhook
Voice (5 HTTP providers + 12 SIP trunks)
GET/voice/api/provider-configs/List configured voice providers
POST/voice/api/calls/Place an outbound call
GET/voice/api/calls/List calls with status & duration
GET/voice/api/calls/{id}/Retrieve call detail (CDR + transcription)
GET/voice/api/call-events/DTMF / answer / hangup / transfer events
GET/voice/api/recordings/S3-backed recordings index
POST/voice/api/templates/Create an IVR template (compiled to TwiML / NCCO / Plivo XML / etc.)
GET/voice/api/rate-cards/Per-destination call rates
POST/voice/api/recording-consents/Log recording consent for TCPA compliance
GET/voice/api/ari-health/Asterisk/ARI SIP infra health check
SMS
GET/sms/v1/apps/List configured SMS apps (Twilio / MSG91 / Fast2SMS)
POST/sms/v1/messages/Send an SMS
GET/sms/v1/templates/List DLT-registered templates
POST/sms/v1/broadcast/Bulk SMS broadcast
POST/sms/v1/webhooks/{app_id}/inbound/Inbound SMS webhook
POST/sms/v1/webhooks/{app_id}/dlr/DLR (delivery report) webhook
Telegram
GET/telegram/v1/bots/List Telegram bot apps
POST/telegram/v1/messages/Send a Telegram message
POST/telegram/v1/broadcast/Broadcast on Telegram
POST/telegram/v1/webhooks/{bot_app_id}/Inbound webhook from Telegram Bot API
RCS
GET/rcs/v1/apps/List RCS apps (Google RBM / Meta RCS)
POST/rcs/v1/messages/Send an RCS rich card / suggested-replies message
POST/rcs/v1/broadcast/RCS broadcast
Team Inbox
GET/team-inbox/api/messages/Unified inbox across all channels
GET/team-inbox/api/stats/Inbox metrics (response time, open conversations)
POST/team-inbox/api/export-pdf/Export a conversation as PDF
Errors & Rate Limits
Standard HTTP status codes. Body for non-2xx is always { "detail": "...", "code": "..." }.
| Status | Meaning | What to do |
|---|---|---|
| 200 | OK | — |
| 201 | Created | — |
| 400 | Validation error | Inspect detail for field-level errors |
| 401 | Unauthorized | Refresh JWT or check API key |
| 403 | Forbidden | RBAC role doesn't permit this action |
| 404 | Not found | Verify ID and tenant scope |
| 429 | Rate limited | Back off — see Retry-After header |
| 5xx | Server error | Retry with exponential backoff; check status page |
Rate limits (hosted)
Per-tenant defaults — raise on Enterprise plans:
- Broadcast send: 500 msgs/sec per tenant (subject to Meta MPS quota)
- Voice outbound: 50 calls/sec per provider
- Read endpoints: 100 req/sec per API key
- Webhooks delivered to your endpoint: up to 200 req/sec with retries