API reference · v1 · Updated October 8, 2026

VICIfast API reference

The VICIfast API is a REST API for phone numbers: search the catalogue, buy and route numbers to your VICIdial servers, place back-orders, read calls with their recordings and transcripts, and follow your wallet, from your own code. JSON over HTTPS, one error shape, signed webhooks, and a sandbox that never charges.

Get an API key OpenAPI 3.1 spec

Guides: Quickstart · Receiving webhooks · Testing in the sandbox · SDKs for TypeScript and Python

SDKs: npm install @vicifast/api · pip install vicifast

Authentication

Create a key in API → Keys in the dashboard and send it on every request. A key carries scopes — reading numbers, buying them, releasing them, transcribing calls, seeing billing and managing webhooks are separate grants — and can be limited to the IP addresses you use. The number, order, call and billing endpoints need an approved termination account.

curl https://vicifast.com/api/v1/numbers \
  -H "Authorization: Bearer vf_live_…"

Test mode

Keys that start vf_test_ work against a sandbox: a pretend $100.00 wallet, a made-up catalogue (555-0100 to 555-0199 in every area code; numbers ending 00 or 11 are premium at $25.00) and one server, srv_sandbox. Prices are your real ones. Nothing real is bought, charged or pointed, and every response carries X-VICIfast-Mode: test. A sandbox back-order delivers half of each line at once and leaves the rest open, so you can try tracking and cancelling. With the sandbox:simulate scope, a test key can also make things happen: an inbound call, a month passing, a back-order filling, a low wallet — each sending its webhook to your test endpoints (see Sandbox). Start over with POST /api/v1/sandbox/reset.

Errors

Every error has the same shape. Branch on code; the message is for people and may change. Every response carries an X-Request-Id to quote to support.

{ "error": { "code": "insufficient_funds",
             "message": "That comes to $5.00 and the wallet holds $2.10. …",
             "details": { "needed_cents": 500, "balance_cents": 210 } } }

Code	Status	Meaning
`invalid_request`	400	Malformed input; `param` names the field.
`unauthorized`	401	No API key, or not a valid one.
`insufficient_funds`	402	The wallet cannot cover it. Nothing was charged; top up and retry with the same Idempotency-Key.
`forbidden`	403	The key lacks the scope this endpoint needs.
`ip_not_allowed`	403	The key is restricted to other addresses.
`account_not_approved`	403	The account has no approved termination account yet. Test keys still work.
`purchasing_disabled`	403	Number purchases are turned off for this account. Numbers it owns keep working; test keys still work.
`test_mode_unsupported`	403	This endpoint has no sandbox.
`sandbox_only`	403	A sandbox simulation: use a test key (vf_test_…). Nothing real can be simulated.
`not_found`	404	No such thing on this account.
`conflict`	409	A request with this Idempotency-Key is still running, or the thing changed state.
`numbers_unavailable`	409	Those numbers are no longer for sale, or there are not enough. `details` says which.
`unprocessable`	422	Understood but refused (an Idempotency-Key reused for a different request, a server that cannot take numbers).
`premium_price_not_accepted`	422	A premium number named without accept_premium_price_cents equal to its price.
`limit_exceeded`	422	It would charge more than your max_total_cents or max_charge_cents. Nothing happened.
`rate_limited`	429	Over 600 requests a minute on this key. Wait Retry-After seconds.
`internal_error`	500	Our fault. Quote X-Request-Id to support.
`service_unavailable`	503	Something we depend on did not answer. Retry shortly.

Retries and Idempotency-Key

Requests that spend or refund money — buying, releasing, placing and cancelling back-orders, transcribing a call — need an Idempotency-Key header: any unique string, sent again unchanged when you retry. A retry of a request that succeeded gets the original answer back (with Idempotent-Replayed: true) and nothing happens twice. A request refused with a 4xx changed nothing, so the same key may be retried once the cause is fixed. Keys are remembered for 24 hours.

Pagination

Lists answer { "data": […], "has_more": true, "next_cursor": "…" }. Pass cursor=next_cursor for the next page, and limit (up to 500) for its size.

Rate limits

600 requests a minute per key, on every endpoint. Over it, the answer is 429 with a Retry-After header.

Numbers

What you hold, the catalogue, buying and releasing.

get/api/v1/numbers

List your numbers

The numbers this account holds (or held), newest first.

Needs the numbers:read scope.

Try it in the playground →

Parameters

`status`	"active" \| "released" \| "all" · query	Default active.
`type`	"local" \| "toll_free" · query
`routed`	"true" \| "false" · query	Pointed somewhere, or not.
`area_code`	string · query	Only numbers in this area code (or toll-free prefix).
`order_id`	string · query	Only numbers from this order.
`limit`	integer · query	Page size, up to 500.
`cursor`	string · query	next_cursor from the previous page.

200 · A page of numbers.

`data`required	PhoneNumber[]
`has_more`required	boolean
`next_cursor`required	string \| null

curl 'https://vicifast.com/api/v1/numbers?status=active&limit=50' \
  -H "Authorization: Bearer $VICIFAST_KEY"

patch/api/v1/numbers

Change many numbers at once

One change — label, notes, auto_renew, routing (with CID groups) — to up to 500 of your numbers. Every one must be a number you hold now, or nothing changes and the answer lists the ones that are not.

Needs the numbers:write scope.

Try it in the playground →

Request body

`label`	string \| null
`notes`	string \| null
`auto_renew`	boolean
`routing`	object \| null	Where it rings: a server and in-group, or {"sip_endpoints": true}. null unpoints it; it stays yours and keeps billing.
`numbers`required	string[]	Up to 500 of your numbers. Every one must be a number you hold now, or nothing changes.

200 · Changed. warnings says what did not fully land (a carrier update, a CID group).

`data`required	BulkUpdateResult
`warnings`	string[]

curl -X PATCH 'https://vicifast.com/api/v1/numbers' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers":["+13055550101","+13055550102"],"routing":{"server_id":"srv_…","in_group":"SALES","cid_groups":["FL_LOCAL"]},"auto_renew":true}'

get/api/v1/numbers/available

Search numbers for sale

Numbers in stock, at your own price, in the order a quantity purchase takes them: never-owned first. Premium numbers only with include_premium=true.

Needs the numbers:read scope.

Try it in the playground →

Parameters

`type`	"local" \| "toll_free" · query
`area_code`	string · query	For toll-free, the prefix: 800, 833, 844…
`state`	string · query	Two-letter state.
`contains`	string · query	Digits, or letters read off a keypad, anywhere in the number: 7777, or FLOWERS.
`ends_with`	string · query	Digits or keypad letters the number must END with: 0000, or SALES.
`npa_nxx`	string · query	Area code and exchange together: 305555.
`rate_center`	string · query	The rate center (in practice, the town) the number belongs to, as the numbering plan names it: MIAMI, NEW YORK CITY. Case does not matter.
`include_premium`	"true" \| "false" · query	Default false.
`sort`	"recommended" \| "number" \| "number_desc" · query	recommended (the default): never-owned numbers first, as a quantity purchase takes them. number / number_desc: by the digits.
`limit`	integer · query	Page size, up to 500.
`cursor`	string · query	next_cursor from the previous page.

200 · A page of numbers for sale.

`data`required	AvailableNumber[]
`has_more`required	boolean
`next_cursor`required	string \| null

curl 'https://vicifast.com/api/v1/numbers/available?area_code=305&ends_with=SALES&sort=number' \
  -H "Authorization: Bearer $VICIFAST_KEY"

post/api/v1/numbers/purchase

Buy numbers

Pays from the wallet: the first month of each number (plus any setup fee) now, then monthly. All of them or none. Name the numbers, or ask for a quantity matching criteria. A premium number is bought only when named with accept_premium_price_cents equal to its monthly price. Each number has a three-month minimum term. dry_run returns the exact charge and buys nothing; without it an Idempotency-Key is required.

Needs the numbers:buy scope.

Try it in the playground →

Parameters

Idempotency-Key string · header

Request body

`numbers`	(string \| object)[]	Buy these exact numbers. All of them or none. Premium numbers need accept_premium_price_cents.
`number`required	string	Any common North American form.
`accept_premium_price_cents`	integer	Required for a premium number: its monthly price, as you were shown it.
`quantity`	integer	Or buy this many matching the criteria, chosen for you (never premium). All of them or none.
`type`	"local" \| "toll_free"	With quantity: local or toll-free.
`area_code`	string	With quantity: the area code (toll-free: the prefix).
`state`	string	With quantity: two-letter state.
`contains`	string	With quantity: digits or keypad letters the numbers must contain.
`ends_with`	string	With quantity: digits or keypad letters the numbers must end with.
`npa_nxx`	string	With quantity: area code and exchange.
`rate_center`	string	With quantity: the rate center.
`max_total_cents`	integer	Refuse the purchase if it would charge more than this now.
`ring_on`	object	Point the new numbers here straight away.
`server_id`required	string
`in_group`required	string
`dry_run`	boolean	Return exactly what the purchase would charge and buy nothing. Needs no Idempotency-Key. Not a reservation.

200 · With dry_run: what it would charge. Nothing bought.

datarequired PurchaseQuote

201 · Bought. The numbers are yours.

datarequired PurchaseResult

curl -X POST 'https://vicifast.com/api/v1/numbers/purchase' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"quantity":5,"area_code":"305","max_total_cents":1000,"ring_on":{"server_id":"srv_…","in_group":"SALES"}}'

post/api/v1/numbers/release

Give numbers back

Inside the three-month minimum term, the rest of the term is charged per number. dry_run returns that charge and changes nothing; the same call without it releases. All of them or none. Needs an Idempotency-Key unless dry_run.

Needs the numbers:release scope.

Try it in the playground →

Parameters

Idempotency-Key string · header

Request body

`numbers`required	string[]
`dry_run`	boolean	Return exactly what releasing would charge, and release nothing.
`max_charge_cents`	integer	Refuse if the minimum-term charge would be more than this.

200 · Released (or, with dry_run, what releasing would cost).

datarequired ReleaseResult

curl -X POST 'https://vicifast.com/api/v1/numbers/release' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"numbers":["+13055550101"],"dry_run":true}'

get/api/v1/numbers/{number}

Get a number

Needs the numbers:read scope.

Try it in the playground →

Parameters

numberrequired string · path The number, in any common form (+13055551234 URL-encoded as %2B13055551234).

200 · The number.

datarequired PhoneNumber

curl 'https://vicifast.com/api/v1/numbers/%2B13055550101' \
  -H "Authorization: Bearer $VICIFAST_KEY"

patch/api/v1/numbers/{number}

Update a number

Label it, write notes, turn auto-renew on or off, or change where it rings: routing points it at one of your servers and an in-group, and null unpoints it (it stays yours and keeps billing). With auto-renew off a number is released at its first renewal after the minimum term.

Needs the numbers:write scope.

Try it in the playground →

Parameters

numberrequired string · path The number, in any common form (+13055551234 URL-encoded as %2B13055551234).

Request body

`label`	string \| null
`notes`	string \| null
`auto_renew`	boolean
`routing`	object \| null	Where it rings: a server and in-group, or {"sip_endpoints": true}. null unpoints it; it stays yours and keeps billing.

200 · The number, as it is now.

datarequired PhoneNumber

curl -X PATCH 'https://vicifast.com/api/v1/numbers/%2B13055550101' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"Miami sales","auto_renew":false,"routing":{"server_id":"srv_…","in_group":"SALES"}}'

get/api/v1/servers

List your servers

Where numbers can be pointed: use a server id in routing or ring_on.

Needs the numbers:read scope.

Try it in the playground →

200 · Your servers.

`data`required	Server[]
`has_more`required	boolean
`next_cursor`required	string \| null

curl 'https://vicifast.com/api/v1/servers' \
  -H "Authorization: Bearer $VICIFAST_KEY"

get/api/v1/servers/{id}/cid-groups

List a server's CID groups

The caller-ID pools on one of your servers that its campaigns dial out from, read from a snapshot of the server taken every minute.

Needs the numbers:read scope.

Try it in the playground →

Parameters

idrequired string · path

200 · Every CID group on the server.

`data`required	CidGroup[]
`has_more`required	boolean
`next_cursor`required	string \| null

curl 'https://vicifast.com/api/v1/servers/:id/cid-groups' \
  -H "Authorization: Bearer $VICIFAST_KEY"

get/api/v1/servers/{id}/cid-groups/{group}

Get a CID group, with its numbers

Needs the numbers:read scope.

Try it in the playground →

Parameters

`id`required	string · path
`group`required	string · path

200 · The group.

datarequired CidGroupWithNumbers

curl 'https://vicifast.com/api/v1/servers/:id/cid-groups/:group' \
  -H "Authorization: Bearer $VICIFAST_KEY"

post/api/v1/servers/{id}/cid-groups/{group}/numbers

Put numbers into a CID group

Written to the server straight away. The area code column is filled the way the group's type needs: the number's area code, its state, or NONE in a rotation. Numbers the server will not take come back in skipped.

Needs the numbers:write scope.

Try it in the playground →

Parameters

`id`required	string · path
`group`required	string · path

Request body

`numbers`required	string[]
`description`	string	Default "VICIfast DID".

200 · Added.

datarequired CidGroupAdded

curl -X POST 'https://vicifast.com/api/v1/servers/:id/cid-groups/:group/numbers' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers":["+13055550101","+13055550102"]}'

post/api/v1/servers/{id}/cid-groups/{group}/numbers/remove

Take numbers out of a CID group

The numbers stay yours and keep ringing; campaigns using the group stop calling out from them.

Needs the numbers:write scope.

Try it in the playground →

Parameters

`id`required	string · path
`group`required	string · path

Request body

numbersrequired string[]

200 · Removed; not_in_group lists any that were not in it.

datarequired CidGroupRemoved

curl -X POST 'https://vicifast.com/api/v1/servers/:id/cid-groups/:group/numbers/remove' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers":["+13055550102"]}'

Orders

Purchases and back-orders.

get/api/v1/orders

List orders

Batches of numbers you received: a purchase, or a back-order as it fills.

Needs the orders:read scope.

Try it in the playground →

Parameters

`status`	"open" \| "filled" \| "routed" \| "closed" · query
`limit`	integer · query	Page size, up to 500.
`cursor`	string · query	next_cursor from the previous page.

200 · A page of orders.

`data`required	Order[]
`has_more`required	boolean
`next_cursor`required	string \| null

curl 'https://vicifast.com/api/v1/orders' \
  -H "Authorization: Bearer $VICIFAST_KEY"

get/api/v1/orders/{id}

Get an order, with its numbers

Needs the orders:read scope.

Try it in the playground →

Parameters

idrequired string · path

200 · The order.

datarequired Order

curl 'https://vicifast.com/api/v1/orders/:id' \
  -H "Authorization: Bearer $VICIFAST_KEY"

get/api/v1/backorders

List back-orders

Needs the orders:read scope.

Try it in the playground →

Parameters

`status`	"open" \| "filled" \| "cancelled" \| "expired" · query
`limit`	integer · query	Page size, up to 500.
`cursor`	string · query	next_cursor from the previous page.

200 · A page of back-orders.

`data`required	Backorder[]
`has_more`required	boolean
`next_cursor`required	string \| null

curl 'https://vicifast.com/api/v1/backorders' \
  -H "Authorization: Bearer $VICIFAST_KEY"

post/api/v1/backorders

Place a back-order

Ask for numbers by area code (or toll-free prefix). Paid up front at your price; numbers are delivered as stock arrives, each line counted separately. Cancel any time to get back what has not arrived.

Needs the orders:write scope.

Try it in the playground →

Parameters

Idempotency-Key string · header

Request body

`type`	"local" \| "toll_free"	Default local.
`lines`	object[]	Required for local. A toll-free order may give quantity instead.
`area_code`required	string	Area code; for toll-free, the prefix (800, 833…).
`quantity`required	integer
`quantity`	integer	Toll-free only, in place of lines: this many numbers from whichever toll-free prefix is in stock.
`notes`	string	Free text sent with the order, for the people filling it.
`allow_nearby`	boolean	When an area code runs short, a nearby one in the same state will do (any toll-free prefix, on a toll-free order).
`ring_on`	object	Point the numbers here as they arrive.
`server_id`required	string
`in_group`required	string
`max_total_cents`	integer	Refuse the order if it would charge more than this now.
`dry_run`	boolean	Return exactly what the order would charge and place nothing. Needs no Idempotency-Key.

200 · With dry_run: what it would charge. Nothing placed.

datarequired BackorderQuote

201 · Placed and paid.

datarequired Backorder

curl -X POST 'https://vicifast.com/api/v1/backorders' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"lines":[{"area_code":"305","quantity":20},{"area_code":"786","quantity":10}],"allow_nearby":true}'

get/api/v1/backorders/{id}

Get a back-order

Needs the orders:read scope.

Try it in the playground →

Parameters

idrequired string · path

200 · The back-order.

datarequired Backorder

curl 'https://vicifast.com/api/v1/backorders/:id' \
  -H "Authorization: Bearer $VICIFAST_KEY"

post/api/v1/backorders/{id}/cancel

Cancel a back-order

Stops waiting and refunds the numbers that have not arrived. Delivered numbers stay yours.

Needs the orders:write scope.

Try it in the playground →

Parameters

`id`required	string · path
`Idempotency-Key`required	string · header	Required. Any unique string (a UUID is ideal). Retry with the same key and the original result is returned instead of the work being done twice.

200 · Cancelled and refunded.

`data`required	object
`object`required	"backorder"
`id`required	string
`status`required	"open" \| "filled" \| "cancelled" \| "expired"
`type`required	"local" \| "toll_free"
`quantity`required	integer
`filled`required	integer
`allow_nearby`required	boolean
`price_each_cents`required	integer	Prepaid per number; the most any will cost.
`paid_cents`required	integer	US cents.
`refunded_cents`required	integer	US cents.
`lines`required	object[]
`area_code`required	string	Area code, or toll-free prefix.
`state`required	string \| null
`quantity`required	integer
`filled`required	integer
`ring_on`required	object \| null
`server_id`required	string
`in_group`required	string
`order_id`required	string \| null	The order the delivered numbers are in, once the first arrives.
`notes`required	string \| null	What you sent with the order.
`created_at`required	string
`cancelled_at`required	string \| null
`refunded_now_cents`required	integer

curl -X POST 'https://vicifast.com/api/v1/backorders/:id/cancel' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Calls

Call records and recordings.

get/api/v1/calls

List calls

Outbound calls you made and inbound calls to your numbers, newest first, from the last 90 days at most.

Needs the calls:read scope.

Try it in the playground →

Parameters

`direction`	"inbound" \| "outbound" · query
`number`	string · query	Inbound calls to this one of your numbers.
`answered`	"true" \| "false" · query
`from`	string · query	Only calls from this number.
`to`	string · query	Only calls to this number.
`window`	"1h" \| "24h" \| "7d" \| "30d" \| "90d" · query	Default 7d. Calls are kept for at least 90 days.
`limit`	integer · query	Page size, up to 500.
`cursor`	string · query	next_cursor from the previous page.

200 · A page of calls.

`data`required	Call[]
`has_more`required	boolean
`next_cursor`required	string \| null

curl 'https://vicifast.com/api/v1/calls?direction=inbound&window=7d' \
  -H "Authorization: Bearer $VICIFAST_KEY"

get/api/v1/calls/{id}

Get a call

Needs the calls:read scope.

Try it in the playground →

Parameters

idrequired string · path

200 · The call.

datarequired Call

curl 'https://vicifast.com/api/v1/calls/:id' \
  -H "Authorization: Bearer $VICIFAST_KEY"

get/api/v1/calls/export

Export calls as CSV

The same calls and the same fields as List calls, as a CSV file of up to 50,000 rows. When there are more, X-Next-Cursor names where the next file starts (pass it as cursor).

Needs the calls:read scope.

Try it in the playground →

Parameters

`direction`	"inbound" \| "outbound" · query
`number`	string · query	Inbound calls to this one of your numbers.
`answered`	"true" \| "false" · query
`from`	string · query	Only calls from this number.
`to`	string · query	Only calls to this number.
`window`	"1h" \| "24h" \| "7d" \| "30d" \| "90d" · query	Default 7d. Calls are kept for at least 90 days.
`limit`	integer · query	Rows per file, up to 50,000 (default 10,000).
`cursor`	string · query	next_cursor from the previous page.

curl 'https://vicifast.com/api/v1/calls/export?window=90d&direction=outbound&from=%2B13055550101' \
  -H "Authorization: Bearer $VICIFAST_KEY"

get/api/v1/calls/{id}/transcript

Get a call's transcript

A transcript made before, free to read as often as you like.

Needs the calls:read scope.

Try it in the playground →

Parameters

idrequired string · path

200 · The transcript.

datarequired Transcript

curl 'https://vicifast.com/api/v1/calls/:id/transcript' \
  -H "Authorization: Bearer $VICIFAST_KEY"

post/api/v1/calls/{id}/transcript

Transcribe a call

Transcribes the call's recording, with the speakers told apart. 5¢ a minute of call (rounded up), charged to the wallet once: a call already transcribed returns its transcript free. dry_run says what it would cost. If the transcription fails, nothing is charged.

Needs the calls:transcribe scope.

Try it in the playground →

Parameters

`id`required	string · path
`Idempotency-Key`	string · header

Request body

`dry_run`	boolean	Say what it would cost, and change nothing.
`max_charge_cents`	integer	Refuse if it would cost more than this.

200 · With dry_run: what it would cost. Or the transcript made before, free.

datarequired TranscriptQuote | Transcript

201 · Made and charged.

datarequired Transcript

curl -X POST 'https://vicifast.com/api/v1/calls/:id/transcript' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"max_charge_cents":50}'

get/api/v1/calls/{id}/recording

Get a recording link

A link to the call's recording, good for fifteen minutes and usable without an API key (hand it to a browser or a player). Only for calls that have one.

Needs the calls:read scope.

Try it in the playground →

Parameters

idrequired string · path

200 · The link.

datarequired RecordingLink

curl 'https://vicifast.com/api/v1/calls/:id/recording' \
  -H "Authorization: Bearer $VICIFAST_KEY"

Billing

The wallet.

get/api/v1/billing/balance

Get the wallet balance

Needs the billing:read scope.

Try it in the playground →

200 · The wallet.

datarequired Balance

curl 'https://vicifast.com/api/v1/billing/balance' \
  -H "Authorization: Bearer $VICIFAST_KEY"

get/api/v1/billing/transactions

List wallet transactions

Needs the billing:read scope.

Try it in the playground →

Parameters

`type`	string · query	One type or several, comma-separated: charge_did_purchase,topup_stripe
`direction`	"credit" \| "debit" · query
`from`	string · query
`to`	string · query
`limit`	integer · query	Page size, up to 500.
`cursor`	string · query	next_cursor from the previous page.

200 · A page of transactions, newest first.

`data`required	Transaction[]
`has_more`required	boolean
`next_cursor`required	string \| null

curl 'https://vicifast.com/api/v1/billing/transactions' \
  -H "Authorization: Bearer $VICIFAST_KEY"

get/api/v1/billing/renewals

List upcoming renewals

What the wallet will be charged, and when: your numbers and wallet-billed servers.

Needs the billing:read scope.

Try it in the playground →

Parameters

days integer · query Default 30.

200 · Upcoming renewals, soonest first.

`data`required	Renewal[]
`has_more`required	boolean
`next_cursor`required	string \| null

curl 'https://vicifast.com/api/v1/billing/renewals' \
  -H "Authorization: Bearer $VICIFAST_KEY"

Messaging

SMS and MMS from your numbers.

post/api/v1/messages

Send a message

SMS (text) or MMS (media_urls) from one of your numbers. Accepted with 202: queued, not yet at the carrier; watch status for sent and delivered. An Idempotency-Key makes a retry return the same message (200) instead of sending twice. Not in the sandbox.

Needs the messages:send scope.

Try it in the playground →

Parameters

Idempotency-Key string · header

Request body

`from`required	string	One of your numbers that can send messages.
`to`required	string
`text`	string
`media_urls`	string[]	For MMS.
`send_at`	string	Schedule it instead of sending now.

200 · The message an Idempotency-Key already sent.

datarequired Message

202 · Accepted and queued.

datarequired Message

curl -X POST 'https://vicifast.com/api/v1/messages' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"from":"+13055550101","to":"+12125559999","text":"Your appointment is at 3pm."}'

get/api/v1/messages

List messages

Sent and received, newest first. Pages also carry X-Next-Cursor, as they always have.

Needs the messages:read scope.

Try it in the playground →

Parameters

`direction`	"inbound" \| "outbound" · query
`status`	"queued" \| "scheduled" \| "sending" \| "sent" \| "delivered" \| "undelivered" \| "failed" \| "suppressed" \| "received" · query
`conversation_id`	string · query
`limit`	integer · query	Page size, up to 100. Default 25.
`cursor`	string · query	next_cursor from the previous page.

200 · A page of messages.

`data`required	Message[]
`has_more`required	boolean
`next_cursor`required	string \| null

curl 'https://vicifast.com/api/v1/messages' \
  -H "Authorization: Bearer $VICIFAST_KEY"

Journeys

Starting a journey for a lead from outside the dialer.

post/api/v1/journeys/{id}/enroll

Enrol a lead in a journey

Starts a journey's calls and texts for a phone number, from a web form or a CRM. A number the dialer does not know yet becomes a lead first, in the journey's list (or list_id), after the dialer's own DNC checks. The journey must allow API enrolment in its settings. Already enrolled is not an error: enrolled comes back false with the reason. Not in the sandbox.

Needs the journeys:enroll scope.

Try it in the playground →

Parameters

`id`required	string · path
`Idempotency-Key`	string · header

Request body

`phone_number`required	string	A North American number: the dialer stores ten digits.
`list_id`	integer	The dialer list a new lead is added to. Default: the journey's own list. Not used when the number is already a lead.
`first_name`	string
`last_name`	string
`address1`	string
`address2`	string
`city`	string
`state`	string
`postal_code`	string
`country_code`	string
`email`	string
`comments`	string
`vendor_lead_code`	string
`source_id`	string
`title`	string
`fields`	object	Any other lead fields, by their VICIdial names.
`idempotency_key`	string	Deprecated: send the Idempotency-Key header instead. Still honoured.

200 · Enrolled, or why not.

datarequired JourneyEnrollment

curl -X POST 'https://vicifast.com/api/v1/journeys/:id/enroll' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"phone_number":"+13055550123","first_name":"Ana","email":"ana@example.com","fields":{"lead_source":"web form"}}'

SIP endpoints

Your own PBX or SBC: the addresses your numbers ring when they are not on a server we host.

get/api/v1/sip-endpoints

List your SIP endpoints

Every endpoint with the addresses it resolves to and their health, how calls are shared, and whether new numbers ring them.

Needs the numbers:read scope.

Try it in the playground →

200 · Your endpoints and settings.

datarequired SipEndpointList

curl 'https://vicifast.com/api/v1/sip-endpoints' \
  -H "Authorization: Bearer $VICIFAST_KEY"

post/api/v1/sip-endpoints

Add a SIP endpoint

A public IP address or a DNS name. Refused: private and reserved addresses, ours and our carriers’, and an address another account uses.

Needs the numbers:write scope.

Try it in the playground →

Request body

`host`required	string
`port`	integer	Default 5060, or 5061 for tls.
`transport`	"udp" \| "tcp" \| "tls"	Default udp.
`weight`	integer	Default 1.
`enabled`	boolean	Default true.
`note`	string

201 · Added.

datarequired SipEndpoint

curl -X POST 'https://vicifast.com/api/v1/sip-endpoints' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"host":"pbx.example.com","port":5060,"transport":"udp","weight":70}'

patch/api/v1/sip-endpoints/{id}

Change a SIP endpoint

Its host, port, transport, weight or note, or switch it off and on.

Needs the numbers:write scope.

Try it in the playground →

Parameters

idrequired string · path

Request body

`host`	string
`port`	integer	Default 5060, or 5061 for tls.
`transport`	"udp" \| "tcp" \| "tls"	Default udp.
`weight`	integer	Default 1.
`enabled`	boolean	Default true.
`note`	string

200 · Changed.

datarequired SipEndpoint

curl -X PATCH 'https://vicifast.com/api/v1/sip-endpoints/:id' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

delete/api/v1/sip-endpoints/{id}

Remove a SIP endpoint

Numbers keep ringing the endpoints that are left.

Needs the numbers:write scope.

Try it in the playground →

Parameters

idrequired string · path

200 · Removed.

datarequired DeletedSipEndpoint

curl -X DELETE 'https://vicifast.com/api/v1/sip-endpoints/:id' \
  -H "Authorization: Bearer $VICIFAST_KEY"

put/api/v1/sip-endpoint-settings

Change how SIP endpoints are used

How calls are shared, whether new numbers ring the endpoints, and whether existing numbers move there now.

Needs the numbers:write scope.

Try it in the playground →

Request body

`share`	"roundrobin" \| "weighted"	roundrobin: every address takes calls equally. weighted: in proportion to weight.
`new_numbers_ring_endpoints`	boolean
`move_unpointed`	boolean	With new_numbers_ring_endpoints true: also point every number that rings nowhere at the endpoints.
`move_server_pointed`	boolean	With new_numbers_ring_endpoints true: also move every number that rings a server to the endpoints.

200 · The endpoints and settings, as they now are.

datarequired SipEndpointList

curl -X PUT 'https://vicifast.com/api/v1/sip-endpoint-settings' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"share":"weighted","new_numbers_ring_endpoints":true,"move_unpointed":true}'

Webhook endpoints

Where events are sent, their signing secrets, and what was delivered.

get/api/v1/webhook-endpoints

List webhook endpoints

This key's mode only: a live key sees live endpoints, a test key test ones.

Needs the webhooks:read scope.

Try it in the playground →

200 · Every endpoint, oldest first.

`data`required	WebhookEndpoint[]
`has_more`required	boolean
`next_cursor`required	string \| null

curl 'https://vicifast.com/api/v1/webhook-endpoints' \
  -H "Authorization: Bearer $VICIFAST_KEY"

post/api/v1/webhook-endpoints

Add a webhook endpoint

Up to 10 per account. The endpoint gets this key's mode: one made with a test key receives the sandbox's events. The secret is in the answer; keep it.

Needs the webhooks:write scope.

Try it in the playground →

Request body

`url`required	string	https only, and on the public internet: private and loopback addresses are refused.
`description`	string
`events`required	("numbers.arrived" \| "number.released" \| "number.renewal_failed" \| "call.inbound.completed" \| "call.outbound.completed" \| "wallet.low" \| "backorder.filled" \| "number.routing_failed" \| "wallet.topped_up" \| "ai_call.completed")[]
`wallet_low_threshold_cents`	integer	Required with wallet.low.

201 · Added.

datarequired WebhookEndpointWithSecret

curl -X POST 'https://vicifast.com/api/v1/webhook-endpoints' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/vicifast","events":["numbers.arrived","number.routing_failed","wallet.low"],"wallet_low_threshold_cents":5000}'

get/api/v1/webhook-endpoints/{id}

Get a webhook endpoint

Needs the webhooks:read scope.

Try it in the playground →

Parameters

idrequired string · path

200 · The endpoint.

datarequired WebhookEndpoint

curl 'https://vicifast.com/api/v1/webhook-endpoints/:id' \
  -H "Authorization: Bearer $VICIFAST_KEY"

patch/api/v1/webhook-endpoints/{id}

Change a webhook endpoint

Its address, events, threshold, description, or switch it off and on.

Needs the webhooks:write scope.

Try it in the playground →

Parameters

idrequired string · path

Request body

`url`	string	https only, and on the public internet: private and loopback addresses are refused.
`description`	string \| null
`events`	("numbers.arrived" \| "number.released" \| "number.renewal_failed" \| "call.inbound.completed" \| "call.outbound.completed" \| "wallet.low" \| "backorder.filled" \| "number.routing_failed" \| "wallet.topped_up" \| "ai_call.completed")[]	Replaces the list.
`enabled`	boolean
`wallet_low_threshold_cents`	integer \| null

200 · Changed.

datarequired WebhookEndpoint

curl -X PATCH 'https://vicifast.com/api/v1/webhook-endpoints/:id' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

delete/api/v1/webhook-endpoints/{id}

Remove a webhook endpoint

Its undelivered events are dropped with it.

Needs the webhooks:write scope.

Try it in the playground →

Parameters

idrequired string · path

200 · Removed.

`data`required	object
`object`required	"webhook_endpoint"
`id`required	string
`deleted`required	true

curl -X DELETE 'https://vicifast.com/api/v1/webhook-endpoints/:id' \
  -H "Authorization: Bearer $VICIFAST_KEY"

post/api/v1/webhook-endpoints/{id}/rotate-secret

Rotate the signing secret

A new secret for this endpoint, used from the next delivery on. The old one stops working at once, so update your receiver straight after.

Needs the webhooks:write scope.

Try it in the playground →

Parameters

idrequired string · path

200 · The new secret.

datarequired WebhookSecret

curl -X POST 'https://vicifast.com/api/v1/webhook-endpoints/:id/rotate-secret' \
  -H "Authorization: Bearer $VICIFAST_KEY"

post/api/v1/webhook-endpoints/{id}/test

Send a test event

Sends a sample of one event type to this endpoint now, signed like any other, and says what came back. The sample has test: true in its data and is tried once.

Needs the webhooks:write scope.

Try it in the playground →

Parameters

idrequired string · path

Request body

200 · Sent; delivered says whether it arrived.

datarequired WebhookTestResult

curl -X POST 'https://vicifast.com/api/v1/webhook-endpoints/:id/test' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"numbers.arrived"}'

get/api/v1/webhook-endpoints/{id}/deliveries

List deliveries to an endpoint

Newest first: what was sent, what came back, and what is still being retried.

Needs the webhooks:read scope.

Try it in the playground →

Parameters

`id`required	string · path
`state`	"pending" \| "retrying" \| "delivered" \| "gave_up" · query
`limit`	integer · query	Page size, up to 500.
`cursor`	string · query	next_cursor from the previous page.

200 · A page of deliveries.

`data`required	WebhookDelivery[]
`has_more`required	boolean
`next_cursor`required	string \| null

curl 'https://vicifast.com/api/v1/webhook-endpoints/:id/deliveries' \
  -H "Authorization: Bearer $VICIFAST_KEY"

Events

The events of the last 30 days, and sending one again.

get/api/v1/events

List events

The events of the last 30 days, newest first, in this key's mode — each one exactly as its webhook body. An event is recorded when at least one endpoint was subscribed to it at the time; catch up on what your receiver missed from here.

Needs the webhooks:read scope.

Try it in the playground →

Parameters

`type`	string · query	One type or several, comma-separated: numbers.arrived,number.released
`from`	string · query
`to`	string · query
`limit`	integer · query	Page size, up to 500.
`cursor`	string · query	next_cursor from the previous page.

200 · A page of events.

`data`required	Event[]
`has_more`required	boolean
`next_cursor`required	string \| null

curl 'https://vicifast.com/api/v1/events?type=numbers.arrived,number.released&limit=50' \
  -H "Authorization: Bearer $VICIFAST_KEY"

get/api/v1/events/{id}

Get an event, with its deliveries

Needs the webhooks:read scope.

Try it in the playground →

Parameters

idrequired string · path

200 · The event.

datarequired EventWithDeliveries

curl 'https://vicifast.com/api/v1/events/:id' \
  -H "Authorization: Bearer $VICIFAST_KEY"

post/api/v1/events/{id}/resend

Send an event again

Queues the event again, to one endpoint or to every endpoint subscribed to it now, and starts sending at once. Each is a new delivery with a new X-VICIfast-Delivery id; the event id is the same, so a receiver that keeps the event ids it has handled can tell it is a repeat.

Needs the webhooks:write scope.

Try it in the playground →

Parameters

idrequired string · path

Request body

endpoint_id string Only to this endpoint. Left out: to every endpoint that is on and subscribed to the type now.

202 · Queued; the deliveries are on their way.

datarequired ResendResult

curl -X POST 'https://vicifast.com/api/v1/events/:id/resend' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"endpoint_id":"we_…"}'

Sandbox

Test keys only: make a call ring, time pass, a back-order fill or the wallet run low, and see what your code does.

post/api/v1/sandbox/inbound-calls

Simulate an inbound call

A caller rings one of your sandbox numbers. The call appears in List calls (with a recording you can transcribe, when answered) and call.inbound.completed goes to your test endpoints.

Needs the sandbox:simulate scope.

Try it in the playground →

Request body

`number`required	string	One of the sandbox numbers you hold.
`from`	string	The caller. Default +12025550123.
`answered`	boolean	Default true.
`duration_s`	integer	How long it lasted, if answered. Default 60.

201 · The call.

datarequired Call

curl -X POST 'https://vicifast.com/api/v1/sandbox/inbound-calls' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":"+13055550100","from":"+12125559999","duration_s":95}'

post/api/v1/sandbox/time-travel

Move the sandbox on in time

Up to 400 days. Renewals that fall due are charged to the pretend wallet, oldest first; a number with auto-renew off past its minimum term is released; a renewal the wallet cannot pay fails. Each sends its webhook to your test endpoints.

Needs the sandbox:simulate scope.

Try it in the playground →

Request body

daysrequired integer How far to move the sandbox on. Renewals that fall due are charged to the pretend wallet, numbers with auto-renew off past their minimum term are released, and a renewal the wallet cannot pay fails — each with its webhook.

200 · What happened.

datarequired TimeTravelResult

curl -X POST 'https://vicifast.com/api/v1/sandbox/time-travel' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"days":31}'

post/api/v1/sandbox/backorders/{id}/deliver

Simulate a back-order delivery

Numbers arrive against an open sandbox back-order: numbers.arrived, and backorder.filled once everything asked for is in.

Needs the sandbox:simulate scope.

Try it in the playground →

Parameters

idrequired string · path

Request body

quantity integer How many to deliver now. Default: everything still to come.

200 · The back-order, after the delivery.

datarequired Backorder

curl -X POST 'https://vicifast.com/api/v1/sandbox/backorders/:id/deliver' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quantity":5}'

post/api/v1/sandbox/wallet

Set the sandbox wallet

Sets the pretend balance. Dropping below a test endpoint’s wallet.low threshold sends wallet.low; raising it sends wallet.topped_up. Set it low, then time-travel, to see a renewal fail.

Needs the sandbox:simulate scope.

Try it in the playground →

Request body

balance_centsrequired integer The pretend balance to set. Below a test endpoint’s wallet.low threshold sends wallet.low; raising it sends wallet.topped_up.

200 · The pretend wallet.

datarequired Balance

curl -X POST 'https://vicifast.com/api/v1/sandbox/wallet' \
  -H "Authorization: Bearer $VICIFAST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"balance_cents":150}'

post/api/v1/sandbox/reset

Start the sandbox over

No numbers, no orders, and a fresh $100 pretend wallet.

Needs the sandbox:simulate scope.

Try it in the playground →

200 · Reset.

datarequired SandboxReset

curl -X POST 'https://vicifast.com/api/v1/sandbox/reset' \
  -H "Authorization: Bearer $VICIFAST_KEY"

Webhooks

Add endpoints in API → Webhooks in the dashboard or with the endpoints API — several if you like, each with its own events and its own signing secret. We POST each event as JSON and retry anything but a 2xx after 1, 5, 15, 60 and 240 minutes. Skip an event you have already handled by its id, which is the same on every retry and on a resend; X-VICIfast-Delivery names one delivery, and a resend is a new one. Missed some? The last 30 days are in List events. No receiver yet? Point an endpoint at the hosted test inbox in API → Webhooks and see each request, its headers and whether its signature checks out.

{
  "id": "cmg…",
  "object": "event",
  "type": "numbers.arrived",
  "livemode": true,
  "created_at": "2026-10-03T20:00:00.000Z",
  "data": { … }
}

Checking a request is from us

X-VICIfast-Signature: t=…,v1=… carries an HMAC-SHA256 of `${t}.${body}` with the endpoint’s secret. Compare it in constant time and refuse a t more than five minutes old.

import crypto from 'node:crypto';

function fromVicifast(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const want = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return v1?.length === want.length &&
    crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(want));
}

numbers.arrived

Numbers are yours: bought, delivered against a back-order, or assigned.

data

`source`required	"purchase" \| "backorder" \| "assigned"
`order_id`required	string \| null
`backorder_id`required	string \| null
`numbers`required	string[]
`test`	true	Only on a sample sent with "send test": the values are made up. Real events never carry it.

number.released

A number left your account.

data

`number`required	string	E.164, with the plus.
`reason`required	"customer" \| "auto_renew_off" \| "account"
`charge_cents`required	integer
`released_at`required	string
`test`	true	Only on a sample sent with "send test": the values are made up. Real events never carry it.

number.renewal_failed

A renewal could not be paid (sent once per number per billing month; the charge is retried every hour).

data

`number`required	string	E.164, with the plus.
`amount_cents`required	integer
`due_at`required	string
`reason`required	"insufficient_funds" \| "error"
`test`	true	Only on a sample sent with "send test": the values are made up. Real events never carry it.

call.inbound.completed

An inbound call to one of your numbers finished.

data

`object`required	"call"
`id`required	string	The SIP call id.
`direction`required	"inbound" \| "outbound"
`from`required	string	The caller, E.164 when it is a North American number.
`to`required	string
`number`required	string \| null	Inbound: which of your numbers it arrived on.
`started_at`required	string
`answered_at`required	string \| null
`ended_at`required	string \| null
`answered`required	boolean
`duration_s`required	integer
`billable_s`required	integer
`sip_code`required	integer \| null
`hangup_cause`required	string
`charge_nanos`required	integer	What the call cost, in billionths of a dollar (2000000 = $0.002).
`recording`required	boolean	A recording can be fetched with GET /v1/calls/{id}/recording.
`test`	true	Only on a sample sent with "send test": the values are made up. Real events never carry it.

call.outbound.completed

An outbound call you made finished, answered or not. A dialer makes many; each is one delivery.

data

`object`required	"call"
`id`required	string	The SIP call id.
`direction`required	"inbound" \| "outbound"
`from`required	string	The caller, E.164 when it is a North American number.
`to`required	string
`number`required	string \| null	Inbound: which of your numbers it arrived on.
`started_at`required	string
`answered_at`required	string \| null
`ended_at`required	string \| null
`answered`required	boolean
`duration_s`required	integer
`billable_s`required	integer
`sip_code`required	integer \| null
`hangup_cause`required	string
`charge_nanos`required	integer	What the call cost, in billionths of a dollar (2000000 = $0.002).
`recording`required	boolean	A recording can be fetched with GET /v1/calls/{id}/recording.
`test`	true	Only on a sample sent with "send test": the values are made up. Real events never carry it.

wallet.low

The wallet dropped below the endpoint's threshold.

data

`object`required	"balance"
`balance_cents`required	integer
`threshold_cents`required	integer
`currency`required	"usd"
`test`	true	Only on a sample sent with "send test": the values are made up. Real events never carry it.

backorder.filled

Every number a back-order asked for has arrived (sent once, after the numbers.arrived for the last delivery).

data

`backorder_id`required	string
`order_id`required	string	The order the numbers were delivered into.
`quantity`required	integer
`refunded_cents`required	integer	Refunded in all because numbers cost less than the price paid up front.
`filled_at`required	string
`test`	true	Only on a sample sent with "send test": the values are made up. Real events never carry it.

number.routing_failed

A number could not be pointed where you asked (a server, or your SIP endpoints), so it will not ring there yet. Point it again (PATCH the number) once the cause is fixed.

data

`number`required	string	E.164, with the plus.
`server_id`required	string	Empty when it was being pointed at your SIP endpoints.
`route_kind`required	string	ingroup, or endpoints for your SIP endpoints.
`target`required	string	The in-group (or other target) it was to ring.
`stage`required	"platform" \| "switch" \| "server"	platform: the server had no address or VICIfast trunk, or pointing failed before anything was sent. switch: our switch did not take the change. server: your server did not take it after three tries (is it running?).
`error`required	string \| null
`test`	true	Only on a sample sent with "send test": the values are made up. Real events never carry it.

wallet.topped_up

Money was added to the wallet: by card, PayPal, crypto, or by us.

data

`object`required	"transaction"
`id`required	string
`type`required	string
`amount_cents`required	integer	Signed: positive credits the wallet.
`balance_after_cents`required	integer	US cents.
`description`required	string \| null
`reference_id`required	string \| null
`created_at`required	string
`test`	true	Only on a sample sent with "send test": the values are made up. Real events never carry it.

ai_call.completed

One of your AI agents finished a call: its outcome, the answers it collected, and a summary. Sent a minute or so after the call, once the summary is written. Only for agents with "Notify my CRM" on; never for test calls.

data

`object`required	"ai_call"
`id`required	string
`agent`required	object
`id`required	string
`name`required	string
`direction`required	"inbound" \| "outbound"
`mode`required	"live" \| "voicemail"	voicemail: the agent left a message on an answering machine.
`caller_number`required	string \| null	The other party: who called in, or the lead that was dialled.
`lead_id`required	string \| null	The VICIdial lead id, when there is one.
`started_at`required	string \| null
`ended_at`required	string \| null
`duration_seconds`required	integer \| null
`outcome`required	string \| null	What the agent decided the call was: qualified, appointment, not_interested, callback, do_not_call, wrong_number, answered, message, and so on.
`vicidial_status`required	string \| null	The status written on the lead in VICIdial.
`transferred_to`required	string \| null	The in-group the caller was handed to, when the agent transferred them.
`answers`required	object	What the agent collected, keyed by the question you set up.
`callback_at`required	string \| null
`appointment_at`required	string \| null
`do_not_call`required	boolean	The person asked not to be called again.
`summary`required	string \| null
`sentiment`required	"positive" \| "neutral" \| "negative" \| null
`flags`required	string[]	Problems found when the call was reviewed: ai_not_disclosed, dnc_ignored, promise_made, talked_over, rude, wrong_info.
`recording`required	boolean	A recording is kept for this call (90 days).
`test`	true	Only on a sample sent with "send test": the values are made up. Real events never carry it.

Objects

What the endpoints and events above return, described once. Every object carries an object field naming its kind.

AvailableNumber

Fields

`object`required	"available_number"
`number`required	string	E.164, with the plus.
`type`required	"local" \| "toll_free"
`state`required	string \| null
`area_code`required	string \| null
`rate_center`required	string \| null
`fresh`required	boolean	Never owned by anybody before.
`premium`required	boolean
`monthly_price_cents`required	integer	Your price, from your own terms.
`setup_price_cents`required	integer	US cents.

Backorder

Fields

`object`required	"backorder"
`id`required	string
`status`required	"open" \| "filled" \| "cancelled" \| "expired"
`type`required	"local" \| "toll_free"
`quantity`required	integer
`filled`required	integer
`allow_nearby`required	boolean
`price_each_cents`required	integer	Prepaid per number; the most any will cost.
`paid_cents`required	integer	US cents.
`refunded_cents`required	integer	US cents.
`lines`required	object[]
`area_code`required	string	Area code, or toll-free prefix.
`state`required	string \| null
`quantity`required	integer
`filled`required	integer
`ring_on`required	object \| null
`server_id`required	string
`in_group`required	string
`order_id`required	string \| null	The order the delivered numbers are in, once the first arrives.
`notes`required	string \| null	What you sent with the order.
`created_at`required	string
`cancelled_at`required	string \| null

BackorderQuote

Fields

`object`required	"backorder_quote"
`dry_run`required	true
`charge_cents`required	integer	US cents.
`quantity`required	integer
`price_each_cents`required	integer	US cents.
`balance_cents`required	integer	US cents.

Balance

Fields

`object`required	"balance"
`balance_cents`required	integer	US cents.
`currency`required	"usd"
`credit_limit_cents`required	integer	How far below zero renewals may take the wallet so numbers keep ringing. Purchases need the funds.
`low_balance_alert`required	object
`enabled`required	boolean
`threshold_cents`required	integer \| null
`auto_top_up`required	object
`enabled`required	boolean

BulkUpdateResult

Fields

`object`required	"bulk_update"
`updated`required	integer
`numbers`required	PhoneNumber[]

Call

Fields

`object`required	"call"
`id`required	string	The SIP call id.
`direction`required	"inbound" \| "outbound"
`from`required	string	The caller, E.164 when it is a North American number.
`to`required	string
`number`required	string \| null	Inbound: which of your numbers it arrived on.
`started_at`required	string
`answered_at`required	string \| null
`ended_at`required	string \| null
`answered`required	boolean
`duration_s`required	integer
`billable_s`required	integer
`sip_code`required	integer \| null
`hangup_cause`required	string
`charge_nanos`required	integer	What the call cost, in billionths of a dollar (2000000 = $0.002).
`recording`required	boolean	A recording can be fetched with GET /v1/calls/{id}/recording.

CidGroup

Fields

`object`required	"cid_group"
`id`required	string
`type`required	"area_code" \| "state" \| "rotation"	area_code: a caller ID is picked to match the area code dialled. state: to match the state. rotation: every caller ID in turn.
`notes`required	string \| null
`numbers_count`required	integer
`synced_at`required	string	When the server was last read.

CidGroupAdded

Fields

`object`required	"cid_group_change"
`group_id`required	string
`added`required	integer
`skipped`required	object[]
`number`required	string	E.164, with the plus.
`error`required	string

CidGroupRemoved

Fields

`object`required	"cid_group_change"
`group_id`required	string
`removed`required	integer
`not_in_group`required	string[]

CidGroupWithNumbers

Fields

`object`required	"cid_group"
`id`required	string
`type`required	"area_code" \| "state" \| "rotation"	area_code: a caller ID is picked to match the area code dialled. state: to match the state. rotation: every caller ID in turn.
`notes`required	string \| null
`numbers_count`required	integer
`synced_at`required	string	When the server was last read.
`numbers`required	object[]
`number`required	string
`area_code`required	string	What VICIdial matches on: an area code, a state, or NONE in a rotation.
`active`required	boolean
`description`required	string \| null

DeletedSipEndpoint

Fields

`object`required	"sip_endpoint"
`id`required	string
`deleted`required	true

Event

Fields

`id`required	string
`object`required	"event"
`type`required	string
`livemode`required	boolean
`created_at`required	string
`data`required	object	Shaped by the type; see Webhooks below. Samples sent with "send test" have test: true.

EventWithDeliveries

Fields

`id`required	string
`object`required	"event"
`type`required	string
`livemode`required	boolean
`created_at`required	string
`data`required	object	Shaped by the type; see Webhooks below. Samples sent with "send test" have test: true.
`deliveries`required	WebhookDelivery[]

JourneyEnrollment

Fields

`object`required	"journey_enrollment"
`enrolled`required	boolean
`lead_id`required	integer
`created_lead`required	boolean	true when the number was not a lead yet.
`reason`	string	Why not, when enrolled is false (already in it, re-entry rules).

Message

Fields

`id`required	string
`object`required	"message"
`direction`required	"inbound" \| "outbound"
`status`required	"queued" \| "scheduled" \| "sending" \| "sent" \| "delivered" \| "undelivered" \| "failed" \| "suppressed" \| "received"	sent means the carrier took it; only delivered means it landed. undelivered is the common outcome of carrier filtering.
`from`required	string
`to`required	string
`text`required	string \| null
`media_urls`required	string[]
`segments`required	integer \| null
`cost_cents`required	integer \| null
`currency`required	string \| null
`error_code`required	string \| null
`error_detail`required	string \| null
`conversation_id`required	string \| null
`send_at`required	string \| null	When a scheduled message goes.
`sent_at`required	string \| null
`delivered_at`required	string \| null
`failed_at`required	string \| null
`created_at`required	string \| null

Order

Fields

`object`required	"order"
`id`required	string
`status`required	"open" \| "filled" \| "routed" \| "closed"	open: still arriving (from a back-order). filled: all delivered. routed: all pointed at one place. closed: every number released.
`type`required	"local" \| "toll_free" \| null
`quantity`required	integer
`active_numbers`required	integer
`criteria`required	object
`state`required	string \| null
`area_code`required	string \| null
`contains`required	string \| null
`backorder_id`required	string \| null
`routing`required	object \| null	Where the whole order was pointed, when it was pointed as one.
`server_id`required	string
`in_group`required	string \| null
`created_at`required	string
`numbers`	PhoneNumber[]	On GET /v1/orders/{id} only.

PhoneNumber

Fields

`object`required	"phone_number"
`id`required	string
`number`required	string	E.164, with the plus.
`type`required	"local" \| "toll_free"
`premium`required	boolean	A memorable number with its own price.
`status`required	"active" \| "released"
`label`required	string \| null
`notes`required	string \| null
`state`required	string \| null
`area_code`required	string \| null
`rate_center`required	string \| null
`monthly_price_cents`required	integer	US cents.
`currency`required	"usd"
`auto_renew`required	boolean
`at_next_renewal`required	"charge" \| "release" \| null	What happens on next_renewal_at. With auto_renew off the number is released at the first renewal after its three-month minimum term; before that, months are still charged.
`purchased_at`required	string
`min_term_ends_at`required	string
`next_renewal_at`required	string \| null
`released_at`required	string \| null
`release_charge_cents`required	integer \| null
`order_id`required	string \| null
`routing`required	object \| null	Where it rings on a server. Null when it rings nowhere or rings your SIP endpoints.
`server_id`required	string
`server_hostname`required	string
`route_kind`required	"ingroup" \| "campaign" \| "extension" \| "ivr"
`target`required	string	The in-group (or other target) calls land on.
`state`required	"pending" \| "applied" \| "failed"	Whether the server has taken the change yet.
`error`required	string \| null
`sip_endpoints`required	boolean	It rings your own SIP endpoints (see /api/v1/sip-endpoints); routing is then null.

PurchaseQuote

Fields

`object`required	"purchase_quote"
`dry_run`required	true
`charge_cents`required	integer	What the purchase would charge now.
`balance_cents`required	integer	US cents.
`numbers`required	object[]
`number`required	string	E.164, with the plus.
`type`required	"local" \| "toll_free"
`premium`required	boolean
`monthly_price_cents`required	integer	US cents.
`setup_price_cents`required	integer	US cents.

PurchaseResult

Fields

`object`required	"purchase"
`order_id`required	string
`charged_cents`required	integer	US cents.
`balance_cents`required	integer	Your wallet after the charge.
`numbers`required	PhoneNumber[]
`ringing`required	object \| null	How pointing went, when ring_on was given.
`ok`required	boolean
`message`required	string

RecordingLink

Fields

`object`required	"recording_link"
`call_id`required	string
`url`required	string	Fetch with no API key: the URL is the credential. WAV audio. Works for 15 minutes.
`expires_at`required	string

ReleaseResult

Fields

`object`required	"release"
`dry_run`required	boolean
`charge_cents`required	integer	The balance of each number's three-month minimum term. Zero once the term is served.
`numbers`required	object[]
`number`required	string	E.164, with the plus.
`released`required	boolean
`charge_cents`required	integer	US cents.
`error`required	string \| null

Renewal

Fields

`object`required	"renewal"
`kind`required	"number" \| "server"
`description`required	string	The number, or the server hostname.
`due_at`required	string
`action`required	"charge" \| "release"	release: a number with auto-renew off, past its minimum term, ends that day.
`amount_cents`required	integer	US cents.

ResendResult

Fields

`object`required	"event_resend"
`event_id`required	string
`deliveries`required	WebhookDelivery[]

SandboxReset

Fields

`object`required	"sandbox"
`reset`required	true

Server

Fields

`object`required	"server"
`id`required	string
`hostname`required	string
`status`required	string
`accepts_numbers`required	boolean	Has an address, so numbers can be pointed at it. They arrive over the VICIfast trunk, installed on the server when needed.

SipEndpoint

Fields

`object`required	"sip_endpoint"
`id`required	string
`host`required	string	A public IP address or a DNS name.
`port`required	integer
`transport`required	"udp" \| "tcp" \| "tls"
`weight`required	integer	Its share under weighted sharing, 1 to 1000.
`enabled`required	boolean	Off takes it out of the rotation without forgetting it. Its addresses can still send your outbound calls.
`note`required	string \| null
`addresses`required	object[]	What the host resolves to, checked every five minutes. Every address takes part in the rotation. Empty: the name does not resolve yet.
`ip`required	string
`health`required	"up" \| "down" \| "unknown" \| "refused"	up / down: answering our health checks, or stopped. unknown: has never answered one — common for a PBX that ignores OPTIONS, and it still gets calls. refused: never used, see 'refused'.
`refused`required	"" \| "private" \| "ours" \| "other_account"	Why a refused address is never used: private (not reachable from the internet), ours (one of our addresses or our carriers), other_account (in use on another account).

SipEndpointList

Fields

`object`required	"sip_endpoint_list"
`share`required	"roundrobin" \| "weighted"	roundrobin: every address takes calls equally. weighted: in proportion to weight.
`new_numbers_ring_endpoints`required	boolean	Numbers bought from now on ring these endpoints unless the purchase names a server.
`data`required	SipEndpoint[]

TimeTravelResult

Fields

`object`required	"time_travel"
`days`required	integer
`renewals_charged`required	integer
`charged_cents`required	integer	US cents.
`released`required	string[]
`renewal_failed`required	string[]

Transaction

Fields

`object`required	"transaction"
`id`required	string
`type`required	string
`amount_cents`required	integer	Signed: positive credits the wallet.
`balance_after_cents`required	integer	US cents.
`description`required	string \| null
`reference_id`required	string \| null
`created_at`required	string

Transcript

Fields

`object`required	"transcript"
`call_id`required	string
`language`required	string \| null
`text`required	string
`utterances`required	object[]
`speaker`required	string	A, B, … as told apart in the audio; ? when unsure.
`start_s`required	number
`end_s`required	number
`text`required	string
`duration_s`required	integer
`charged_cents`required	integer	What making it cost, once.
`created_at`required	string

TranscriptQuote

Fields

`object`required	"transcript_quote"
`dry_run`required	true
`call_id`required	string
`minutes`required	integer
`price_per_minute_cents`required	integer	US cents.
`charge_cents`required	integer	US cents.
`balance_cents`required	integer	US cents.

WebhookDelivery

Fields

`object`required	"webhook_delivery"
`id`required	string	Sent as X-VICIfast-Delivery.
`endpoint_id`required	string
`event_id`required	string
`event_type`required	string
`test`required	boolean	A sample sent with "send test". Tried once.
`state`required	"pending" \| "retrying" \| "delivered" \| "gave_up"	retrying: failed, and tried again after 1, 5, 15, 60 and 240 minutes. gave_up: every attempt failed, or the receiver refused it outright (a 4xx other than 408 or 429).
`attempts`required	integer
`last_status`required	integer \| null
`last_error`required	string \| null
`created_at`required	string
`delivered_at`required	string \| null
`next_attempt_at`required	string \| null

WebhookEndpoint

Fields

`object`required	"webhook_endpoint"
`id`required	string
`url`required	string
`description`required	string \| null
`events`required	("numbers.arrived" \| "number.released" \| "number.renewal_failed" \| "call.inbound.completed" \| "call.outbound.completed" \| "wallet.low" \| "backorder.filled" \| "number.routing_failed" \| "wallet.topped_up" \| "ai_call.completed")[]
`enabled`required	boolean	false: nothing is sent to it.
`livemode`required	boolean	true: your account's real events. false: the sandbox's, from test keys. Follows the key that created it.
`wallet_low_threshold_cents`required	integer \| null	wallet.low fires once when the balance drops below this, and again only after it has been back above.
`last_status`required	integer \| null	HTTP status of the last attempt.
`last_error`required	string \| null
`last_sent_at`required	string \| null
`failing_since`required	string \| null	Set while deliveries are failing; cleared by the next one that succeeds.
`created_at`required	string

WebhookEndpointWithSecret

Fields

`object`required	"webhook_endpoint"
`id`required	string
`url`required	string
`description`required	string \| null
`events`required	("numbers.arrived" \| "number.released" \| "number.renewal_failed" \| "call.inbound.completed" \| "call.outbound.completed" \| "wallet.low" \| "backorder.filled" \| "number.routing_failed" \| "wallet.topped_up" \| "ai_call.completed")[]
`enabled`required	boolean	false: nothing is sent to it.
`livemode`required	boolean	true: your account's real events. false: the sandbox's, from test keys. Follows the key that created it.
`wallet_low_threshold_cents`required	integer \| null	wallet.low fires once when the balance drops below this, and again only after it has been back above.
`last_status`required	integer \| null	HTTP status of the last attempt.
`last_error`required	string \| null
`last_sent_at`required	string \| null
`failing_since`required	string \| null	Set while deliveries are failing; cleared by the next one that succeeds.
`created_at`required	string
`secret`required	string	Signs every delivery (X-VICIfast-Signature). Shown when the endpoint is made and when the secret is rotated; keep it.

WebhookSecret

Fields

`object`required	"webhook_secret"
`endpoint_id`required	string
`secret`required	string	The new secret. The old one stops working from the next delivery.

WebhookTestResult

Fields

`object`required	"webhook_test"
`event_id`required	string
`delivery_id`required	string
`delivered`required	boolean	Whether your endpoint answered 2xx.
`status`required	integer \| null
`error`required	string \| null

Common questions

How do I authenticate with the VICIfast API?

Send an API key from API → Keys in the dashboard as Authorization: Bearer vf_live_…. Each key has scopes (reading numbers, buying them, releasing them, billing and webhooks are separate grants) and can be limited to the IP addresses you use.

Is there a sandbox for testing?

Yes. Keys that start vf_test_ work against a sandbox with a pretend $100 wallet, a made-up catalogue and one server. Nothing real is bought or charged, and the sandbox can simulate an inbound call, time passing, a back-order delivery or a low wallet.

What are the rate limits?

600 requests a minute per key, on every endpoint. A request over the limit is answered 429 with a Retry-After header saying when to try again.

How are webhooks signed and retried?

Every delivery carries X-VICIfast-Signature: an HMAC-SHA256 of the timestamp and the body with the endpoint’s secret. Refuse one more than five minutes old. Anything but a 2xx is retried after 1, 5, 15, 60 and 240 minutes.

How do I retry a purchase safely?

Send an Idempotency-Key header on every request that spends or refunds money. Retrying with the same key returns the original answer instead of buying twice; keys are remembered for 24 hours.

Are there SDKs for the VICIfast API?

Yes: @vicifast/api for TypeScript and Node.js (npm install @vicifast/api) and vicifast for Python (pip install vicifast). Both are generated from the OpenAPI document, and both send Idempotency-Keys, retry safely, walk pages and check webhook signatures for you.

Is there an OpenAPI specification?

Yes: an OpenAPI 3.1 document at /api-docs/openapi.json, generated from the same schemas the API validates requests with, for code generators and API clients.