Quickstart

This guide will help you make your first API call to Voicy in just a few minutes.

Prerequisites

A Voicy account (sign up here)
An API key (create one)
A phone number assigned to your account with an agent configured

Step 1: Set Up Your Environment

Store your API key as an environment variable:

export VOICY_API_KEY="voicy_sk_live_your_key_here"

$env:VOICY_API_KEY = "voicy_sk_live_your_key_here"

Step 2: List Your Calls

Let’s start by listing recent calls to verify your API key works:

curl -X POST https://api.voicy.co/functions/v1/call-list \
  -H "Authorization: Bearer $VOICY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 5}'

const response = await fetch('https://api.voicy.co/functions/v1/call-list', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.VOICY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ limit: 5 }),
});

const calls = await response.json();
console.log(calls);

import os
import requests

response = requests.post(
    'https://api.voicy.co/functions/v1/call-list',
    headers={
        'Authorization': f'Bearer {os.environ["VOICY_API_KEY"]}',
        'Content-Type': 'application/json',
    },
    json={'limit': 5},
)

calls = response.json()
print(calls)

Step 3: Make an Outbound Call

Now let’s initiate an AI-powered phone call:

curl -X POST https://api.voicy.co/functions/v1/call-dial \
  -H "Authorization: Bearer $VOICY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number": "+15559876543",
    "vars_provided": {
      "customer_name": "John"
    }
  }'

const response = await fetch('https://api.voicy.co/functions/v1/call-dial', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.VOICY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from_number: '+15551234567',
    to_number: '+15559876543',
    vars_provided: {
      customer_name: 'John',
    },
  }),
});

const call = await response.json();
console.log(`Call initiated: ${call.call_id}`);

import os
import requests

response = requests.post(
    'https://api.voicy.co/functions/v1/call-dial',
    headers={
        'Authorization': f'Bearer {os.environ["VOICY_API_KEY"]}',
        'Content-Type': 'application/json',
    },
    json={
        'from_number': '+15551234567',
        'to_number': '+15559876543',
        'vars_provided': {
            'customer_name': 'John',
        },
    },
)

call = response.json()
print(f'Call initiated: {call["call_id"]}')

Replace +15551234567 with a phone number assigned to your account, and +15559876543 with the destination number.

Step 4: Get Call Details

After the call completes, retrieve the full details including transcript:

curl https://api.voicy.co/functions/v1/call-get/YOUR_CALL_ID \
  -H "Authorization: Bearer $VOICY_API_KEY"

const callId = 'YOUR_CALL_ID';
const response = await fetch(`https://api.voicy.co/functions/v1/call-get/${callId}`, {
  headers: {
    'Authorization': `Bearer ${process.env.VOICY_API_KEY}`,
  },
});

const callDetails = await response.json();
console.log('Transcript:', callDetails.transcript);
console.log('Duration:', callDetails.duration_ms, 'ms');

import os
import requests

call_id = 'YOUR_CALL_ID'
response = requests.get(
    f'https://api.voicy.co/functions/v1/call-get/{call_id}',
    headers={
        'Authorization': f'Bearer {os.environ["VOICY_API_KEY"]}',
    },
)

call_details = response.json()
print(f'Transcript: {call_details["transcript"]}')
print(f'Duration: {call_details["duration_ms"]}ms')

Getting Started

Resources

Quickstart

Quickstart

Prerequisites

Step 1: Set Up Your Environment

Step 2: List Your Calls

Step 3: Make an Outbound Call

Step 4: Get Call Details

What’s Next?

API Reference

Error Handling

​Quickstart

​Prerequisites

​Step 1: Set Up Your Environment

​Step 2: List Your Calls

​Step 3: Make an Outbound Call

​Step 4: Get Call Details

​What’s Next?

API Reference

Error Handling

Quickstart

Prerequisites

Step 1: Set Up Your Environment

Step 2: List Your Calls

Step 3: Make an Outbound Call

Step 4: Get Call Details

What’s Next?