Start recording a call

POST

api

Account

{auth_id}

Call

{call_uuid}

Record

Start recording a call

curl --request POST \
  --url https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Record/ \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "time_limit": 120,
  "file_format": "mp3"
}
'

import requests

url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Record/"

payload = {
    "time_limit": 120,
    "file_format": "mp3"
}
headers = {
    "X-Auth-ID": "<api-key>",
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<api-key>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({time_limit: 120, file_format: 'mp3'})
};

fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Record/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "recording_id": "rec_XXXXXXXXXX",
  "message": "Recording started"
}

POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Record/

Start recording a call that is currently in progress. You can create multiple recordings on the same call, customize the audio format, enable automated transcription, and receive a callback when recording completes.

Transcription is available only in English, for calls between 500ms and 4 hours in duration, and under 2GB in file size.

Path parameters

Parameter	Type	Required	Description
`auth_id`	string	Yes	Your Vobiz authentication ID
`call_uuid`	string	Yes	Unique identifier of the call to record

Request parameters

Field	Type	Required	Description
`time_limit`	integer	No	Maximum recording duration in seconds. Default: `60`. Increase for longer calls (e.g., `300`, `900`).
`file_format`	string	No	Audio format. Values: `mp3`, `wav`. Default: `mp3`
`transcription_type`	string	No	Set to `auto` to enable automated transcription. Turnaround under 5 minutes.
`transcription_url`	string	No	URL to receive transcription data via HTTP POST
`callback_url`	string	No	URL invoked when recording ends with recording details
`callback_method`	string	No	HTTP method for `callback_url`. Values: `GET`, `POST`. Default: `POST`
`record_channel_type`	string	No	Recording channel type. Values: `mono`, `stereo`. Default: `mono`

Use MP3 format for smaller file sizes. Stereo recording separates caller and callee into left/right channels for easier analysis.

Example requests

{
  "time_limit": 120,
  "file_format": "mp3"
}

{
  "time_limit": 60,
  "file_format": "mp3",
  "callback_url": "https://example.com/recording_callback",
  "callback_method": "POST"
}

curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Record/ \
  -H "X-Auth-ID: YOUR_AUTH_ID" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "time_limit": 60,
    "file_format": "mp3"
  }'

Response

200 OK

{
  "api_id": "uuid-here",
  "message": "recording started",
  "recording_id": "recording-uuid-here",
  "url": "https://recordings.example.com/recording-uuid.mp3"
}

Field	Description
`api_id`	Unique identifier for this API request
`message`	Confirmation that recording has started
`recording_id`	Unique identifier for this recording. Save it to stop or correlate this specific recording later.
`url`	URL where the recording file will be available once finalized.

A single call can have multiple recordings running at once. Each POST starts a new one with its own recording_id and url. Recording stops automatically when time_limit is reached, when you call Stop Recording, or when the call ends.

Error responses

Status	Meaning	How to handle
`401 Unauthorized`	Missing/incorrect auth headers or a lowercase path.	Use both auth headers and the PascalCase path.
`404 Not Found`	The `call_uuid` is not an active call.	The call must be in-progress; confirm with Retrieve a Live Call.

Callback URL parameters

When recording ends, these fields are sent to your callback_url via HTTP POST:

Field	Type	Description
`api_id`	string	The API ID returned by the Record API
`record_url`	string	URL where the recorded file can be accessed
`call_uuid`	string	The call UUID of the recorded call
`recording_id`	string	Unique identifier for this recording
`recording_duration`	integer	Duration of the recording in seconds
`recording_duration_ms`	integer	Duration of the recording in milliseconds
`recording_start_ms`	integer	Start time since epoch in milliseconds
`recording_end_ms`	integer	End time since epoch in milliseconds

Transcription callback parameters

When transcription completes, these fields are sent to your transcription_url:

Field	Type	Description
`transcription_charge`	number	Credit deducted for the transcription
`transcription`	string	The transcribed text
`duration`	integer	Recording duration in seconds
`call_uuid`	string	The call UUID that was transcribed
`transcription_rate`	number	Rate of transcription per minute
`recording_id`	string	Recording ID of the transcribed recording
`error`	string	Error message if transcription failed; empty on success

If you see “Recording file size too large for transcription”, switch to mp3 format - MP3 files are significantly smaller than WAV.

Authorizations

X-Auth-ID

string

header

required

Your Vobiz account Auth ID

X-Auth-Token

string

header

required

Your Vobiz account Auth Token

Path Parameters

auth_id

string

required

Your account Auth ID

Example:

"MA_XXXXXX"

call_uuid

string

required

Example:

"cdr_XXXXXXXXXX"

Body

application/json

time_limit

integer

default:60

file_format

enum<string>

default:mp3

Available options:

mp3,

wav

transcription_type

string

Set to auto to enable transcription

callback_url

string

record_channel_type

enum<string>

default:mono

Available options:

mono,

stereo

Response

200 - application/json

Recording started

Start recording a call

curl --request POST \
  --url https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Record/ \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "time_limit": 120,
  "file_format": "mp3"
}
'

import requests

url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Record/"

payload = {
    "time_limit": 120,
    "file_format": "mp3"
}
headers = {
    "X-Auth-ID": "<api-key>",
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<api-key>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({time_limit: 120, file_format: 'mp3'})
};

fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Record/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "recording_id": "rec_XXXXXXXXXX",
  "message": "Recording started"
}

​Path parameters

​Request parameters

​Example requests

​Response

​Error responses

​Callback URL parameters

​Transcription callback parameters

Authorizations

Path Parameters

Body

Response

Path parameters

Request parameters

Example requests

Response

Error responses

Callback URL parameters

Transcription callback parameters