Phone numbers

Real US/Canada local numbers, provisioned in seconds, owned by exactly one agent each.

Provision

One call — search and purchase together, optionally creating a minimal agent if you don't pass one:

curl -X POST https://klaw-voice.netlify.app/api/v1/numbers \
  -H "Authorization: Bearer $KLAW_KEY" -H "Content-Type: application/json" \
  -d '{"area_code": "415", "agent_id": "AGENT_UUID", "nickname": "Front desk line"}'

Or pick precisely: GET /api/twilio/numbers/available?area_code=415 lists candidates, then pass the chosen phone_number instead of area_code. Voice, SMS, and status webhooks are wired at purchase — the number answers immediately.

Manage

Action	Endpoint
List numbers	GET /api/v1/numbers
Get one	GET /api/v1/numbers/{id}
Rename / set inbound instruction	PATCH /api/v1/numbers/{id}
Release (returns it to Twilio)	DELETE /api/v1/numbers/{id}

In v1, a number is addressed by its owning agent — number.id equals the agent's id.

Invariants and limits

• One number per agent. Attaching a number that belongs to another agent returns 409 — release it there first.
• Purchases are capped at 5/hour per account (each one bills real money).
• Numbers cost about $1/month; releasing stops the charge.
• Attach to an existing agent later with POST /api/v1/agents/{id}/phone-number ({"mode": "purchase", "area_code": "415"} or an exact phone_number), or do it at creation with with_number: true on quickstart.