Skip to main content

Recording Controls

Endpoint​

POST /v1/calls/:id/recordings

Method​

POST

Auth requirement​

Bearer application API key. The call must belong to the authenticated application and customer.

Business example: start recording during an appointment confirmation call, stop before a payment transfer, then use the recording for QA or transcription.

Request body​

{
  "action": "start"
}

action defaults to start. Supported values are start and stop.

Response body​

{
  "data": {
    "call_id": "call_123",
    "provider_call_id": "uuid",
    "action": "start",
    "recording": {
      "id": "rec_call_123",
      "call_id": "call_123",
      "customer_id": "cust_123",
      "application_id": "app_123",
      "provider_call_id": "uuid",
      "status": "started",
      "storage_type": "local",
      "file_url": "",
      "duration_seconds": 0,
      "size_bytes": 0,
      "created_at": "2026-05-29T12:00:00Z",
      "updated_at": "2026-05-29T12:00:00Z"
    }
  }
}

Errors​

400 invalid_request, invalid_json, invalid_action. 401 unauthorized. 404 active_call_not_found or recording_not_started. 409 call_uuid_missing. 502 recording_start_failed or recording_stop_failed.

Common Error Example​

{
  "error": {
    "code": "recording_not_started",
    "message": "recording is not currently started"
  }
}

Example curl​

curl -sS -X POST https://api.minivoice.eu/v1/calls/call_123/recordings \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY' \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "action": "start"
}
JSON

Test procedure​

Start recording on an active call, stop it, then verify recording.started and recording.completed webhooks.

Integration checklist

Use recording controls only when your application needs the audio later for review, transcription, or quality workflows. Start recording at a clear point in the call flow, store the recording ID from responses or webhooks, and wait for the final call state before assuming the file is ready for downstream processing.

For testing, place a short call with known spoken phrases, then verify that your application can connect the call ID, recording ID, and later AI result. Also test a call with no recording so your UI has a clean empty state.

Copy/Paste Examples​

Real Request​

curl -sS -X POST https://api.minivoice.eu/v1/calls/call_123/recordings \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY' \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "action": "start"
}
JSON

Real Response​

{
  "data": {
    "call_id": "call_123",
    "action": "start",
    "recording": {
      "id": "rec_call_123",
      "status": "started",
      "duration_seconds": 0,
      "size_bytes": 0
    }
  }
}

Real Webhook Example​

{
  "event": "call.completed",
  "created_at": "2026-05-29T12:10:00Z",
  "call": {
    "id": "call_123",
    "customer_id": "cust_123",
    "application_id": "app_123",
    "status": "completed",
    "direction": "inbound",
    "from": "+15551230001",
    "to": "+15551230002"
  },
  "variables": {},
  "data": {}
}

Common Use Case​

Start and stop recording around the part of the call that needs QA, transcription, or compliance review.

Common Failure Case​

{
  "error": {
    "code": "recording_not_started",
    "message": "recording is not currently started"
  }
}

Use the error code for branching and log the full response body while testing.