Complete endpoint reference for the Volume Reach Public API.

Base URL: https://api.volumereach.com/api/v1/public Auth: Authorization: Bearer vr_live_... Content-Type: application/json Rate limits: 60 req/min per tenant on write routes, 120 req/min per tenant on read routes. Limits are shared across all API keys on a single tenant — a customer with 3 keys still has one shared budget. Exceeding → 429 rate_limited with a Retry-After header. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Conventions

• All request/response bodies are JSON.
• Timestamps are ISO-8601 in UTC.
• Phone numbers are E.164 (+15551234567).
• All routes are tenant-scoped — objects created with one API key are invisible to API keys from other tenants, even if you guess the ID.
• Error envelope shape is consistent: { error: { code, message, details? } }.
• idempotencyKey is opt-in but recommended on write routes to protect against CRM retries.

Calls

POST /calls — Trigger an outbound qualification call

Scope: calls:place

Request body:

Response 201 Created:

{
  "call": {
    "id": "call_xyz",
    "status": "queued",
    "agentId": "va_abc",
    "phoneNumber": "+15551234567",
    "fromPhoneNumber": "+15559876543",
    "direction": "ai_outbound",
    "outcome": null,
    "endedReason": null,
    "durationSeconds": null,
    "startedAt": null,
    "endedAt": null,
    "createdAt": "2026-04-22T14:03:21.000Z",
    "transcript": null,
    "extraction": null,
    "extractionError": null,
    "variables": { "leadName": "Jane Smith" },
    "metadata": { "crmLeadId": "hubspot-987" },
    "knownConsent": true,
    "consentRecordId": null
  }
}

Error codes:

GET /calls/:id — Read a call

Scope: calls:read

Response 200 OK — same shape as the POST /calls response, with fields populated as the call progresses:

• status: queued → ringing → in-progress → completed / no_answer / busy / failed / canceled.
• transcript: full transcript text (populated after call ends).
• extraction: structured output (populated if the agent has extractionSchema configured).
• recordingUrl: only returned via this endpoint (not in webhook). Signed GCS URL, expires in 15 minutes. Fetch fresh when you need to download.
• durationSeconds: conversation duration. null if the call was never answered.

Error codes:

POST /calls/:id/end — Force-terminate a call

Scope: calls:place

Hang up an in-progress call. Idempotent — safe to call multiple times; if the call has already ended, returns the current state.

Response 200 OK:

{ "id": "call_xyz", "status": "ending" }

Agents

GET /agents — List voice agents

Scope: read

Response 200 OK:

{
  "agents": [
    {
      "id": "va_abc",
      "name": "Roofing Lead Qualifier",
      "isDefault": true,
      "extractionSchema": { "type": "object", "properties": { "interested": { "type": "boolean" } }, "required": ["interested"] },
      "updatedAt": "2026-04-22T13:00:00.000Z"
    }
  ]
}

Only public-facing agent fields are exposed. Full configuration (system prompt, voice settings, LLM tuning) is managed in the Volume Reach app.

GET /agents/:id — Read a single agent

Scope: read

Same shape as the list item. 404 agent_not_found if the ID doesn't exist or isn't in your tenant.

POST /agents/:id/extraction-schema — Save / update extraction schema

Scope: write

Request body:

{ "schema": { "type": "object", "properties": {...}, "required": [...] } }

Pass { "schema": null } to clear the schema (disable extraction for this agent).

See extraction.md for schema authoring tips and examples.

Error codes:

Webhooks

See webhooks.md for event types, payload shapes, and signature verification.

GET /webhooks — List webhook endpoints

Scope: webhooks

Response:

{
  "endpoints": [
    {
      "id": "whe_abc",
      "name": "Production",
      "url": "https://your-app.com/webhooks",
      "method": "POST",
      "signingSecret": "****xxxx",
      "isActive": true,
      "createdAt": "2026-04-22T..."
    }
  ]
}

Signing secrets are masked (last 4 chars only). The full secret is only returned once, at creation or regeneration time.

POST /webhooks — Create an endpoint

Scope: webhooks

Request body:

{
  "name": "Production webhook",
  "url": "https://your-app.com/webhooks/volumereach",
  "method": "POST",
  "headers": { "X-Custom": "value" }
}

Response 201 Created:

{
  "endpoint": {
    "id": "whe_abc",
    "name": "Production webhook",
    "url": "https://your-app.com/webhooks/volumereach",
    "method": "POST",
    "signingSecret": "<HEX>",
    "isActive": true
  }
}

⚠️ Save signingSecret now — it's only shown once.

Errors:

DELETE /webhooks/:id — Delete an endpoint

Scope: webhooks

Removes the endpoint and any pending retry deliveries targeting it. Triggers referencing this endpoint are also cleaned up.

Webhook deliveries (DLQ inspection + replay)

Every webhook attempt creates a WebhookDeliveryLog row. Successful deliveries are marked success; failures retry on the schedule documented in webhooks.md. After 6 failed attempts the row is marked failed and lands in the DLQ. These endpoints let you inspect and replay deliveries programmatically (all require webhooks scope).

GET /webhook-deliveries — List deliveries

Scope: webhooks

Query params:

Response 200 OK:

{
  "deliveries": [
    {
      "id": "dlv_abc123",
      "createdAt": "2026-04-22T14:05:47.123Z",
      "eventType": "call.completed",
      "status": "failed",
      "attempts": 6,
      "responseStatus": 500,
      "errorMessage": "HTTP 500",
      "nextRetryAt": null,
      "lastAttemptAt": "2026-04-23T14:08:02.100Z",
      "endpoint": { "id": "whe_abc", "name": "Production", "url": "https://your-app.com/webhooks" },
      "trigger": { "id": "trg_xyz", "name": "All call completions" }
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 4, "totalPages": 1 }
}

GET /webhook-deliveries/:id — Single delivery

Scope: webhooks

Returns the same shape as the list endpoint PLUS payload — the full JSON body we sent (useful for forensics when your handler logs were insufficient).

POST /webhook-deliveries/:id/retry — Replay a failed delivery

Scope: webhooks

Re-dispatches the stored payload to the original endpoint using the same X-Webhook-Delivery-Id so your idempotent handler sees it as a retry, not a new event.

Response 200 OK — returns the updated delivery record (status flipped to retrying or success).

Error codes:

Automation triggers (event → endpoint subscriptions)

A webhook endpoint is a URL; an automation trigger subscribes an endpoint to an event type.

POST /automation-triggers — Subscribe

Scope: webhooks

Request body:

{
  "name": "All call completions",
  "eventType": "call.completed",
  "webhookEndpointId": "whe_abc",
  "conditions": { "outcome": ["INTERESTED", "APPOINTMENT"] }
}

Max 25 triggers per tenant.

GET /automation-triggers — List

Scope: webhooks

{
  "triggers": [
    {
      "id": "at_abc",
      "name": "...",
      "eventType": "call.completed",
      "webhookEndpointId": "whe_abc",
      "conditions": {},
      "isActive": true,
      "webhookEndpoint": { "id": "whe_abc", "name": "Production", "url": "https://..." }
    }
  ]
}

GET /automation-triggers/:id — Read

Scope: webhooks

DELETE /automation-triggers/:id — Unsubscribe

Scope: webhooks

Future additions

Reserved space — will be added when we receive consistent customer requests. Documented so integrators can plan around eventual support.