---
title: "Lease a SIP name from the relay pool for a BYO agent call"
method: POST
path: "/v1/relay"
---

# Lease a SIP name from the relay pool for a BYO agent call

`POST /v1/relay`

## Request

- Base URL: `https://volai.cz`
- URL: `https://volai.cz/v1/relay`
- Auth: HTTP bearer

Creates a lease - `to` is the destination number, `from` is your own volai number the call should appear to come from. The returned `sipName` is the BARE name for ElevenLabs's `to_number` (**not** `sipUri` - ElevenLabs rejects a full SIP URI). Set your platform's outbound trunk to `outboundTrunkAddress` from `GET /v1/numbers/{e164}/sip` - a different address means the call is not routed on the network and the platform reports a timeout.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `to` string, required: Destination the leased SIP name will dial. The lease must be used before it expires.
  - `from` string, required: Owned volai number used as the caller id for the outbound leg.
  - `ttlSecs` integer: Lease lifetime in seconds, 15-300. Omit to use the server default. Creating a lease does not itself place a call.

## Response `200`

Created lease

- object
  - `id` string, required
  - `sipName` string, required
  - `sipUri` string, required
  - `expiresAt` number, required
  - `callId` string, required

## Other responses

- `400`: Error codes: invalid_number (request), validation (request), on_dnc (account), relay_lease_limit (account).
- `401`: Error codes: unauthorized (request).
- `402`: Error codes: insufficient_credit (account), subscription_cap_reached (account).
- `403`: Error codes: account_suspended (account).
- `404`: Error codes: from_number_not_owned (account).
- `409`: Error codes: idempotency_in_progress (busy), destination_busy (busy).
- `429`: Error codes: rate_limited (busy).
- `500`: Error codes: internal_error (service).
- `503`: Error codes: capacity_busy (busy).

---

[API](https://skmtc.dev/volai/apis/volai-rest-api.md) · [All operations](https://skmtc.dev/volai/apis/volai-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volai/apis/volai-rest-api/revisions/12029b05e2fa?raw)