ZEOVOICE DEVELOPER API · V1

Build on your AI workforce without bypassing governance.

Use scoped API keys, metered access, signed webhooks, deployment evidence, and stable versioned endpoints to connect Zeovoice with your software.

Get Developer API →Explore the API

CURRENT INTEGRATION MODEL

A controlled path from public brief to authenticated work.

The marketing site is a safe definition and evaluation surface. Operational truth lives in the authenticated Zeovoice application, where employees, readiness, approvals, evidence, calls, leads, billing, and metrics are authoritative.

Same-origin application

The recommended topology keeps marketing, authenticated app routes, APIs, telephony callbacks, and billing callbacks under the Zeovoice origin or an equivalent secured edge configuration.

Verified onboarding

Public employee briefs can be carried into a verified workspace. The browser preview never becomes the authoritative employee by itself.

Scoped connections

Business systems are connected for the work the employee is allowed to perform. Integration access should map back to role, permission, policy, and approval boundaries.

Operational evidence

Production workflows separate requests, decisions, actions, outcomes, approvals, and evidence so operators can inspect what happened and why.

ZEOVOICE DEVELOPER API · V1

Scoped access to the workforce—not an unrestricted runtime.

Entitled workspaces can create display-once API keys with explicit scopes, inspect metered usage, register signed HTTPS webhooks, and integrate against a stable /api/v1 boundary. Voice calls, AI simulation, billing changes, and unrestricted mutations are intentionally excluded from v1.

Business integrationsGoogle Calendar and HubSpot managed connections →Security architectureTenant isolation, scoped keys, rate limits and evidence →Deployment readinessWhat must be true before customer-facing work →Platform statusService-health and monitoring surface →

API REFERENCE · V1

A small, stable surface with explicit authority.

Base path /api/v1. Authenticate with Authorization: Bearer zv_live_…. Keys are workspace-bound, independently revocable, metered, and rate-limited.

GET

/api/v1/workspace

Returns workspace identity and operating metadata.

workspace:read

GET

/api/v1/employees

Lists governed AI Employees and their current status.

employees:read

GET

/api/v1/employees/{employeeId}

Returns one employee's governed configuration.

employees:read

GET

/api/v1/deployment/{employeeId}

Returns deployment readiness and verified channel state.

deployment:read

POST

/api/v1/deployment/{employeeId}/verify/{channel}

Runs and records an explicit deployment verification.

deployment:verify

GET

/api/v1/usage?days=30

Returns metered request/usage totals for the workspace.

usage:read

QUICKSTART · CURL

Make your first request.

curl https://zeovoice.com/api/v1/employees   -H "Authorization: Bearer $ZEOVOICE_API_KEY"   -H "Accept: application/json"

JAVASCRIPT

Use standard fetch.

const response = await fetch(
  "https://zeovoice.com/api/v1/employees",
  { headers: {
      Authorization: `Bearer ${process.env.ZEOVOICE_API_KEY}`
  }}
);
const data = await response.json();

PYTHON

Use any HTTPS client.

import requests, os

r = requests.get(
  "https://zeovoice.com/api/v1/employees",
  headers={"Authorization":
    f"Bearer {os.environ['ZEOVOICE_API_KEY']}"}
)
r.raise_for_status()
employees = r.json()["items"]

REQUEST EXAMPLE

Verify a deployment channel.

POST /api/v1/deployment/EMPLOYEE_ID/verify/WEBSITE
Authorization: Bearer zv_live_…

Response

{
  "channel": "WEBSITE",
  "status": "READY",
  "last_verified_at": "2026-10-02T…Z",
  "evidence": {
    "summary": "1 active website widget"
  }
}

EMPLOYEE RESPONSE

Stable governed fields.

{
  "id": "…",
  "name": "AI Receptionist",
  "role_name": "AI Receptionist",
  "status": "LIVE",
  "capabilities": ["answer_calls","capture_leads"],
  "permissions": { "telephony": { "answer": true } },
  "policies": { "humanApprovalForSensitiveActions": true }
}

SIGNED WEBHOOKS

React to workforce events without polling.

Each endpoint receives a display-once signing secret. Zeovoice signs the exact raw request body with HMAC-SHA256 and retries failed deliveries through the background worker.

{
  "id": "EVENT_UUID",
  "type": "deployment.verified",
  "created": "2026-10-02T…Z",
  "data": {
    "employeeId": "…",
    "channel": "WEBSITE",
    "status": "READY"
  }
}

X-Zeovoice-Signature: t=TIMESTAMP,v1=SIGNATURE

WEBHOOK VERIFICATION

Verify before processing.

signed = timestamp + "." + raw_body
expected = HMAC_SHA256(webhook_secret, signed)

reject if timestamp is stale
compare expected and v1 in constant time

Webhook endpoints must be public HTTPS destinations. Zeovoice rejects private/internal targets and pins delivery to validated public addresses.

EVENT CATALOG

V1 events

developer.testdeployment.verifiedemployee.createdemployee.liveemployee.paused

STARTER KITS

Use the contract directly—or start from a working client.

All starter assets map to the same governed v1 boundary. Begin with a TEST key, then move to LIVE only when your integration is production-ready.

OpenAPI 3.1

Canonical endpoint, scope and version contract for tooling, client generation and internal review.

Download OpenAPI →

JavaScript + Python

Minimal starter clients for authentication, employee reads, deployment verification and usage.

JavaScript Python

Postman + changelog

Import the v1 collection and track compatibility, deprecations and new capabilities.

Postman Changelog

DOCUMENTATION BOUNDARY

Document what is real.

Zeovoice developer documentation describes shipped, governed capabilities and their actual authority boundaries. Examples do not imply broader production access, autonomous authority, or unsupported integrations.

Integration boundaries →Security model →

ERRORS

Predictable errors for predictable integrations.

Status	Code	Meaning
401	`API_KEY_REQUIRED`	Bearer token missing.
401	`API_KEY_INVALID`	Key is invalid, expired, rotated, or revoked.
402	`DEVELOPER_API_ENTITLEMENT_REQUIRED`	The workspace Developer API add-on is not active.
403	`API_SCOPE_REQUIRED`	The key lacks the required explicit scope.
404	`Not found`	The resource is unavailable inside this workspace.
429	`API_RATE_LIMITED`	Per-key request limit reached. Respect `Retry-After`.

VERSIONING

Stable major-version boundary.

Breaking API changes require a new major path such as /api/v2. Compatible additions may be introduced within v1. Clients should ignore unknown JSON fields.

V1 intentionally excludes outbound calls, AI simulation, billing mutations, phone provisioning, go-live activation, and unrestricted employee writes.

CHANGELOG

V1 · October 2026

Scoped display-once API keys.
Workspace and employee read endpoints.
Deployment state and explicit verification.
Metered usage endpoint.
Signed webhook delivery and test events.

ZEOVOICE DEVELOPER API

Connect your software to a governed AI workforce.

Developer API is a paid add-on for active Zeovoice subscriptions. Purchase and manage access from your authenticated workspace.

Get Developer API →