# Vocaleo

> Vocaleo lets a personal AI assistant place one phone call and read one
> structured result. You hand over a phone number and a task in plain language;
> Vocaleo makes the call and returns what happened as machine-readable facts,
> not a transcript to parse. The customer is the agent. This file is for you.

## Status: LIVE

The API answers at https://api.vocaleo.co.

## How it works, in four calls

1. POST https://api.vocaleo.co/v1/accounts (no auth) — create an account. The response
   holds the API key (shown once — save it) and a payment_url.
2. Send your user to the payment_url to add credit. A call needs a balance that
   covers max_charge_cents_per_call. If payment_url is null, Stripe is not
   connected to that environment yet.
3. POST https://api.vocaleo.co/v1/calls (bearer) — place the call. Body:
   {"to_phone_number": "+1...", "task": "what to do", "on_behalf_of": "name"}.
   The response is 202 with a call_id.
4. GET https://api.vocaleo.co/v1/calls/{call_id}?wait_seconds=60 (bearer) — read the
   result. Repeat until status is completed or error, then read outcome,
   summary, transcript, and charged_cents.

## The rules of a call

- You write the task the way you would brief a person: what to accomplish, and
  what to accept if the first answer is no.
- The agent says it is an AI on a recorded line, names the person it calls for
  when you set on_behalf_of, and never invents a fact you did not give it.
- US and Canada numbers only. A task screen refuses harassment, fraud,
  impersonation, emergency-service calls, and unsolicited marketing.

## Authentication

- Header: Authorization: Bearer vok_... — the key from step 1.
- The key is shown once at account creation and never again. Store it securely,
  never over a chat channel.

## Money

- Read the price from the account response: price_cents_per_minute and
  max_charge_cents_per_call. These are the source of truth — do not hardcode.
- A call holds max_charge_cents_per_call up front, then refunds the difference
  when it settles. A call that errors is not charged; the whole hold is refunded.

## Results

- outcome is one of: achieved, partial, not_achieved, unclear.
- transcript is a list of {"role": "assistant" | "user", "content": "..."}.
- A non-terminal call has null outcome, summary, transcript, and charged_cents.

## Errors

- Every error body is {"error": {"code", "message"}} plus any named extra fields.
- Codes: unauthorized, not_found, invalid_request, task_rejected, insufficient_credit, rate_limited, conflict, temporarily_unavailable, executor_error.
- 402 insufficient_credit carries needed_cents and payment_url.
- 429 rate_limited carries Retry-After.

## Full contract

- Docs (human and agent readable): https://vocaleo.co/docs
- OpenAPI 3.1: https://vocaleo.co/openapi.json

## Contact

- support@vocaleo.co