Ringez Phone Calling API

Make affordable international phone calls from anywhere. No hidden fees, no subscriptions — just pay for the minutes you use.

What is Ringez?

Ringez is a simple, privacy-focused international calling service that lets you make phone calls to 200+ countries without complicated setups or expensive plans.

Perfect for:

• Calling family abroad
• Business calls to international clients
• AI agents making reservations or appointments
• Quick calls without buying a calling plan

Quick Start Guide

1. Create an Account

First, check if your email is already registered:

POST https://ringez-api.vercel.app/api/v1/auth/check-email
Content-Type: application/json

{"email": "[email protected]"}

Response:

• new_user → Continue to OTP verification
• existing_user → Login with password

For New Users: Verify with OTP

Step 1: Request OTP

POST https://ringez-api.vercel.app/api/v1/auth/send-otp
Content-Type: application/json

{"email": "[email protected]"}

Step 2: Verify OTP

POST https://ringez-api.vercel.app/api/v1/auth/verify-otp
Content-Type: application/json

{
  "email": "[email protected]",
  "otp": "123456"
}

Response:

{
  "session_id": "sess_abc123xyz",
  "user": {
    "email": "[email protected]",
    "balance_minutes": 5
  }
}

Save the session_id — you will need it for all API calls.

For Existing Users: Login

POST https://ringez-api.vercel.app/api/v1/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "your-password"
}

2. Check Your Balance

See how many minutes you have before making a call:

GET https://ringez-api.vercel.app/api/v1/auth/me
X-Session-ID: sess_abc123xyz

Response:

{
  "balance_minutes": 5,
  "balance_usd": 0,
  "email": "[email protected]"
}

3. Make a Phone Call

Use the idempotency_key to prevent accidental duplicate calls:

POST https://ringez-api.vercel.app/api/v1/calls/initiate
X-Session-ID: sess_abc123xyz
Content-Type: application/json

{
  "to_number": "+919876543210",
  "idempotency_key": "sess_abc123xyz_1700000000000_xyz789"
}

Response (Success):

{
  "call_id": "call_xyz789",
  "status": "initiated",
  "mode": "bridge",
  "to_number": "+919876543210",
  "from_number": "+17623713590",
  "twilio_call_sid": "CAxxxxx"
}

Response (Duplicate Call):

{
  "alreadyInitiated": true,
  "callSid": "CAxxxxx"
}

Call Modes Explained

Ringez supports two ways to make calls:

Bridge Mode (Default)

• How it works: Calls your phone first, then connects you to the destination
• Best for: Personal calls where you want to talk
• Your phone: Will ring first

Direct Mode

• How it works: Calls the destination directly
• Best for: AI agents, automated calls, or when you do not want your phone to ring
• Your phone: Does not ring