Getting started

Go from "I just heard of voepy" to "I just placed a real phone call from code" in five minutes.

1 · Sign up

Create an account at the dashboard (or, programmatically, POST to /v1/signup). You give us:

• Your email and a strong password.
• Your tenant (workspace) name.
• Country + company size + use case — quick KYC so we can route you to the right pricing tier.

The signup response includes your first API key as plaintext exactly once. Copy it somewhere safe.

POST /v1/signup HTTP/1.1
Host: api.voepy.com
Content-Type: application/json

{
  "email": "you@yourco.com",
  "password": "a-strong-passphrase",
  "tenant_name": "Yourco Voice",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "legal_name": "Yourco, Inc.",
  "country": "US",
  "company_size": "11-50",
  "industry": "voice_ai",
  "use_case": "AI voice agents for restaurants."
}

Response (truncated):

{
  "tenant": { "id": "9b3e…", "name": "Yourco Voice", "status": "active" },
  "api_key": { "id": "…", "prefix": "voepy_live_abc12345", "scopes": ["*"] },
  "api_key_plaintext": "voepy_live_abc12345_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "verification_email_sent": true
}

A verification email lands in your inbox. You have seven days to click the link or your tenant auto-suspends.

Already have a dashboard login? Issue more API keys at POST /v1/api-keys once authenticated.

2 · Stash your key in an environment variable

export VOEPY_KEY="voepy_live_abc12345_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Every example in these docs reads VOEPY_KEY — swap in your own.

3 · Confirm you're authenticated

curl https://api.voepy.com/v1/account \
  -H "Authorization: Bearer $VOEPY_KEY"

You'll get back your tenant identity and current balance (in cents). A 401 means the key is wrong or revoked; a 200 means you're live.

4 · Fund your balance

You can't place outbound calls with a zero balance. Two steps:

1. Add a card. Create a Stripe SetupIntent and confirm it in your frontend with Stripe.js.
2. Top up. Call POST /v1/billing/topup with amount_cents and the saved payment_method_id. We charge Stripe, credit your balance, and write a ledger entry.

Full walkthrough in Billing. For a quick test you can also ask support to drop in a starter credit — talk to your onboarding contact.

5 · Buy a phone number

You need an inbound DID before you can place outbound calls — it's your caller-id. Search the inventory, then order:

# Find one
curl "https://api.voepy.com/v1/numbers/available?country_code=US&national_destination_code=512&limit=5" \
  -H "Authorization: Bearer $VOEPY_KEY"

# Buy it
curl -X POST https://api.voepy.com/v1/numbers/order \
  -H "Authorization: Bearer $VOEPY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["+15125550100"],
    "country_code": "US",
    "number_type": "local"
  }'

The order debits your balance for the non-recurring charge (NRC) up front, then activates the number. See Phone numbers for type options, toll-free, lookup, and porting.

6 · Place your first call

curl -X POST https://api.voepy.com/v1/calls \
  -H "Authorization: Bearer $VOEPY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "from": "+15125550100",
    "to":   "+15558675309"
  }'

The response is your Call resource:

{
  "id": "voepy_call_01HZABC…",
  "direction": "outbound",
  "status": "initiated",
  "from": "+15125550100",
  "to":   "+15558675309",
  "initiated_at": "2026-05-12T14:32:18.000Z",
  "legs": [],
  "recordings": []
}

The call is now ringing the far side. Voepy will fire webhook events (call.started, call.answered, call.ended) so your app can react in real time. Wire that up next.

7 · Wire up a webhook

You need a public HTTPS endpoint. Once you have one:

curl -X POST https://api.voepy.com/v1/webhook-subscriptions \
  -H "Authorization: Bearer $VOEPY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://yourapp.com/webhooks/voepy",
    "event_types": ["*"],
    "description": "All events"
  }'

The response includes a signing_secret shown exactly once. Use it to verify the X-Webhook-Signature header on every delivery. Full example (including a Node and Python handler) in Webhooks.

8 · You're live

That's the happy path:

signup → fund → buy a number → place a call → handle webhooks

From here, dive into:

• Calls for the full control surface — transfer, bridge, record, IVR menus, real-time transcription, answering-machine detection.
• Phone numbers for ordering toll-free, porting numbers in, and per-number configuration.
• Billing for auto-recharge and invoices.
• Error reference to map error codes to the right retry or fix.

Quick reference