Quick Start Guide

Get up and running with Vobiz in 4 simple steps. You'll login, provision a SIP trunk, and make your first call in under 10 minutes.

Prerequisites: Contact the Vobiz team to set up your account and receive your email and password credentials before starting this guide.

Step 1: Login

Authenticate with your Vobiz credentials to obtain JWT access and refresh tokens for API access.

Understanding Token Lifecycle

The login endpoint authenticates you with email and password, returning JWT access and refresh tokens. Your access token remains valid for 30 minutes of continuous API access. When it expires, you can use the refresh token endpoint for passwordless renewal. The refresh token itself lasts 7 days, enabling week-long sessions without credential re-entry.

What You'll Receive

access_token: JWT token for API authentication (valid for 30 minutes)
refresh_token: Token for obtaining new access tokens (valid for 7 days)
account_id: Your unique identifier used in all API paths (prefixed with MA_)

Token Best Practices

Store tokens securely in encrypted storage (never browser localStorage)
Implement automatic refresh 5 minutes before access token expiration
Handle 401 errors gracefully by triggering re-authentication flow

POST/api/v1/auth/login

▶HTTP Headers

Host:api.vobiz.ai

Content-Type:application/json

Request Body

{
  "email": "user@example.com",
  "password": "P@ssw0rd123!"
}

Response Example

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "def502004a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6...",
  "token_type": "Bearer",
  "expires_in": 1800,
  "account_id": "MA_2210JXXN"
}

Important: Save the access_token and account_id. You'll use the access token in the Authorization header for all subsequent API calls.

Step 2: Create SIP Trunk

Provision your first SIP trunk. The system will automatically generate a unique SIP domain in the format trunkId.sip.vobiz.ai. Use your JWT Bearer token for authentication.

Provisioning Your SIP Infrastructure

Creating a SIP trunk provisions your dedicated telephony gateway for making and receiving VoIP calls. The platform automatically generates a unique SIP domain, authentication credentials, and registers the trunk with the underlying Kamailio SIP proxy server. The trunk becomes immediately active and ready to handle calls once provisioned, with credentials returned in the response for SIP client configuration.

Automatic Configuration

Unique domain: Auto-generated in format trunkId.sip.vobiz.ai for SIP registration
Authentication: Secure password automatically created and returned once
Kamailio integration: Trunk instantly registered in SIP proxy routing tables

Configuration Parameters

concurrent_calls_limit: Maximum concurrent calls allowed on this trunk
cps_limit: Calls per second rate limit to prevent traffic surges
ip_whitelist: IP addresses allowed to use this trunk without password auth

POST/api/v1/account/MA_2210JXXN/trunks

▶HTTP Headers

Host:api.vobiz.ai

Content-Type:application/json

Authorization:Bearer {{accessToken}}

Request Body

{
  "name": "US Primary",
  "username": "trunkuser",
  "password": "TrunkPassword123!",
  "concurrent_calls_limit": 20,
  "cps_limit": 10,
  "ip_whitelist": [
    "198.51.100.10"
  ],
  "description": "Primary outbound trunk"
}

Response Example

Trunk Created Response

{
  "id": "trunk_7a8b9c0d1e2f3g4h",
  "account_id": "MA_2210JXXN",
  "name": "US Primary",
  "description": "Primary outbound trunk",
  "domain": "trunk_7a8b9c0d1e2f3g4h.sip.vobiz.ai",
  "username": "trunkuser",
  "password": "TrunkPassword123!",
  "concurrent_calls_limit": 20,
  "cps_limit": 10,
  "ip_whitelist": ["198.51.100.10"],
  "status": "active",
  "created_at": "2025-10-12T10:00:00.000Z"
}

Success! Your SIP trunk is now active. Save the domain, username, and password - you'll need them to configure your SIP client.

Step 3: Get Trunk Details

Retrieve your trunk details anytime to check configuration or get credentials.

Verifying Your Trunk Configuration

After trunk creation, use this endpoint to retrieve complete configuration details including SIP credentials, domain information, current usage statistics, and operational status. The response includes real-time metrics like active channels and total call count, enabling you to monitor trunk utilization.

What You Can Retrieve

Credentials: Username and password for SIP client authentication
Real-time stats: Current active channels and call limits
Configuration: Rate limits and IP whitelist settings

Common Use Cases

Retrieving SIP credentials for client reconfiguration
Monitoring trunk capacity usage before scaling
Auditing configuration before production deployment

GET/api/v1/account/MA_2210JXXN/trunks/trunk_7a8b9c0d1e2f3g4h

▶HTTP Headers

Host:api.vobiz.ai

Authorization:Bearer {{accessToken}}

Response Example

Trunk Details Response

{
  "id": "trunk_7a8b9c0d1e2f3g4h",
  "account_id": "MA_2210JXXN",
  "name": "US Primary",
  "domain": "trunk_7a8b9c0d1e2f3g4h.sip.vobiz.ai",
  "username": "trunkuser",
  "status": "active",
  "concurrent_calls_limit": 20,
  "cps_limit": 10,
  "ip_whitelist": ["198.51.100.10"]
}

Step 4: Configure SIP Client

Configure your SIP client (softphone, PBX, or application) with the trunk credentials:

Connection Details

SIP Domain:: trunk_7a8b9c0d1e2f3g4h.sip.vobiz.ai
Username:: trunkuser
Password:: TrunkPassword123!
Port:: 5060 (UDP/TCP)

Advanced Settings

Transport:: UDP (recommended) or TCP
Registration:: Optional (for inbound calls)
Concurrent Calls:: 20 max
Rate Limit:: 10 calls per second

Pro Tip: IP-based authentication is enabled for 198.51.100.10. Calls from this IP don't require password authentication for enhanced security in production deployments.

Next Steps