Phone numbers

Provision and connect responses include advisory warnings for display names: stable code, field and informational message. Tyxter advice does not block submission or predict Meta approval. Names are not rewritten. Older cached idempotency responses may omit warnings; replay preserves the accepted result.

Available regions

Response

Provision (Salvy)

In sandbox, provision returns 202 with a simulated number. In production it rents nothing: it creates a rental order, as POST /v1/phone-numbers/orders does, and returns 409 phone_number_rental_approval_required whose error.details.order carries the order's id, approval_url and expires_at, with the error.feedback pointer. The JavaScript SDK exposes those fields as TyxterApiError.rentalOrder. Do not also create an order for the same number. A keyed replay spends a rate-limit token and answers the 409 stored at creation, so read the order below for its status. Migration note (October 2026): production provision used to return 202 with a rented number; there is no deprecation window, a replay of an Idempotency-Key first used before the change still returns its original 202, and numbers already rented are unchanged. Reading the order needs the phone_numbers:read scope, which a key that only had phone_numbers:write for provision lacks.

Production provision and order creation need both the business-identity declaration and a separate current owner/admin billing WhatsApp recipient with explicit transactional-alert consent only when the default-off PHONE_PROVISIONING_REQUIRE_BILLING_WHATSAPP deployment policy is enabled. The legal KYC contact phone is not a delivery address. Missing or stale evidence then returns 403 billing_whatsapp_required before an order is written, and the approval checks it again; existing rentals, sandbox, and BYON connect are unaffected.

Request body

Response

Rental orders

A rental order asks to rent one Tyxter-provisioned number. In production it is created awaiting_approval and nothing is rented or charged: hand its approval_url to an owner or admin of the organization, who approves or declines it in the dashboard within 24 hours. No API key can approve an order: each production number is a phone line held in the organization's name, so a person there, an owner or admin, must authorize the rental. In sandbox the order is approved on creation with a free preview. A replay of the same Idempotency-Key returns the order as it was created; read the order for its current status.

The approval link opens the order's approval page in the dashboard, which shows the order's charge summary, the rental terms and a link to the renewal policy. Any organization member with access to the order's project can view the order (owners and admins always can), and only an owner or admin can approve or decline it. No /v1 route approves or declines an order, and no webhook event or notification announces a new one, so relay the link yourself. Approval re-runs the business-identity, billing WhatsApp, plan allowance and Tyxter-provisioned number limit checks, compares the current price, charge dates and terms_version with the order's preview, and reserves the first month. A refused approval, such as 402 insufficient_balance, leaves the order awaiting_approval until expires_at. An undeterminable price or charge date answers 503 phone_number_rental_preview_unavailable and creates no order.

Creation shares the per-organization provision rate limit (burst 5, sustained 10/hour). A keyed replay still spends a token before the stored response is found, so with an empty bucket it answers 429 rate_limited with Retry-After. Without a key every request creates a new order. The provisioning feature control blocks creation with 403 feature_disabled, not the read or the dashboard decision.

Request body

Response

Returns the order with its status computed now. A declined or expired order carries failure.code phone_number_order_declined, phone_number_order_expired or phone_number_order_terms_changed; an unknown id answers 404 phone_number_order_not_found.

Poll it about once a minute. Reading spends no provision rate-limit token; the production credit hard-block still applies (402 credit_balance_exhausted). The status moves from awaiting_approval through approved (first month reserved, phone_number_id set) and provisioning to a final fulfilled (the number became active) or failed (the number never became active: provisioning failed after approval, which returns the reservation and sets the phone's error_code, or the number was released or disconnected first, which does not refund a month charged at delivery). declined and expired are final too, and rented and charged nothing: create a new order.

Connect (BYON)

Request body

Response

Import a selected Salvy number

Imports one selected cached resource from a connected Salvy account. This write requires phone_numbers:write, Idempotency-Key, and continuation_terms_version: "salvy_byok_v1". It creates a customer-owned BYON phone with provider_number_id: null; the call neither calls Salvy nor starts a Tyxter rental, release, wallet, fee, or usage operation. A foreign connection or resource returns 404 without revealing scope. The nullable salvy_management object is the enrollment record, and renewal is null.

Importing needs an active Standard or Growth plan; without one the call returns 403 salvy_byok_subscription_required. While that plan stays active, and through the end of the UTC month in which it ends, management of an imported number costs nothing. After that, billing charges one full phone.management.month fee from the balance on each month’s 1st. On the free plan, a number whose month is still unpaid at 12:00 UTC on the month’s last UTC day is disabled. While neither a plan nor a charged month covers the number, sends from it fail with phone_service_suspended; the number is not released. The renewal policy gives the full terms. Every phone response’s salvy_management reports billing’s live coverage, next charge and state, with suspension_reason while suspended. GET /v1/billing/phone-management reads the same values, plus payment status and the disable deadline; convert-to-byon ends management for free.

Request body

Response

Complete imported Salvy registration

Queues independent Meta WABA ownership validation for the current imported attachment. Send the Meta phone id with an Idempotency-Key. A connected Salvy account, carrier status, or received SMS never activates messaging; activation follows only a same-environment Meta ownership confirmation.

Request body

Response

List

Response

Retrieve

Response

verified_name is Meta's current verified display name; in production it is observed by the scheduled health sweep and is null before that observation. Sandbox supplies a deterministic simulated value. display_name remains the customer-entered row label. pending_name_review is null or { requested_name: string | null; status: string | null; observed_at: ISO timestamp }: the pending Graph observation from a successful complete health sweep. Its nullable status is open Meta vocabulary and observed_at is the same freshness fact as meta_health_synced_at. A successful complete sweep is authoritative and writes or clears it. A completed callback can clear it immediately only when its requested name matches and its effective time is not older than observed_at; all other callbacks wait for the next sweep. Failed or partial refreshes leave prior values and freshness intact. Sandbox deterministically returns pending_name_review: null, which means no pending observation, not approval.name_review is separately null until a durable completed callback decision arrives; then its nullable requested_name and reason accompany reviewed_at and an open, forward-compatible Meta decision string. These read responses never call Meta.

remaining_messaging_allowance_estimate is how many more unique recipients this number can contact outside their customer-service windows before Tyxter begins holding sends. It is not a remaining-message count. A recipient already holding a slot in the moving 24-hour period costs nothing more, and any message from that recipient opens a separate 24-hour customer-service window whose sends also cost no allowance. It counts against a cap reduced by the configured safety margin and sending-phone quality ratio, so it may reach zero before the raw allowance is spent. Linked phones compare shared portfolio usage with their own quality-adjusted thresholds, so different quality can yield different remaining values. The raw health tier is descriptive; an unlinked Meta phone uses a conservative per-phone fallback, while sandbox follows its simulated phone tier. Treat it as a planning estimate, not a quota to spend exactly: concurrent sends move it, slots expire one by one with no reset moment, and a paused number can report a number above zero before a send observes recovery. Missing authoritative linked capability or an unread unlinked tier uses a deliberately low default rather than an assumed unlimited allowance. null means Tyxter cannot estimate it at all, and never means zero.

Disconnect

Disconnects a number from the current environment and returns its terminal record. This operation is an idempotent no-op for an already disconnected, released, or failed number. Disconnecting does not end a rental: a Tyxter-rented number keeps billing until POST /v1/phone-numbers/{id}/release.

Response

Convert to BYON

Send exactly {} with an Idempotency-Key to end an optional customer-Salvy management episode while retaining the same phone, Meta link, andsource: 'byon'. This free exit never releases or deregisters the number. It remains available when the customer credential was explicitly disconnected and cleanup is still queued.

Request body

Response

Release

Releases the upstream resource. Salvy numbers first enter release_requested while a worker cancels the rental; BYON numbers move directly to released. The request has no JSON body and supports Idempotency-Key.

Response

Transfer

Moves a non-terminal number between projects or environments in the same organization. The body confirms both scopes and the route identifier; cross-organization targets return 404. This write supports Idempotency-Key.

Request body

Response

{
  "id": "pn_abc",
  "object": "phone_number",
  "source": "salvy",
  "status": "active",
  "environment": "production",
  "display_name": "Tyxter Brazil",
  "ddd": "11",
  "phone": "+5511987654321",
  "provider_number_id": "salvy_456",
  "meta_phone_number_id": "456_phone",
  "waba_id": null,
  "quality_rating": "unknown",
  "messaging_tier": "unknown",
  "messaging_limit_tier": null,
  "meta_throughput_tier": null,
  "meta_quality_rating": null,
  "verified_name": null,
  "pending_name_review": null,
  "name_review": null,
  "meta_health_synced_at": null,
  "current_24h_unique_recipients": 0,
  "remaining_messaging_allowance_estimate": 225,
  "verification_code": null,
  "verification_code_received_at": null,
  "monthly_fee_brl": "49.90",
  "error_code": null,
  "error_message": null,
  "created_at": "2026-04-25T10:00:00Z",
  "updated_at": "2026-04-25T11:30:00Z",
  "activated_at": "2026-04-25T11:30:00Z",
  "released_at": null,
  "recent_messages": [],
  "renewal": {
    "state": "at_risk",
    "reason_codes": [
      "insufficient_credit"
    ],
    "cycle_id": null,
    "amount_brl": "49.9000",
    "currency": "brl",
    "next_renewal_at": "2026-12-01T00:05:00.000Z",
    "release_cutoff_at": "2026-11-30T12:00:00.000Z",
    "renewal_warning_48h_at": null,
    "renewal_warning_24h_at": null,
    "grace_selected_at": null,
    "grace_ends_at": null,
    "automatic_release_enabled": true,
    "release_requested_at": null,
    "recommended_action": "add_credit_or_enable_auto_topup",
    "evaluated_at": "2026-11-10T12:00:00.000Z",
    "provider_evidence_observed_at": null
  }
}

{
  "state": "at_risk",
  "reason_codes": [
    "insufficient_credit"
  ],
  "cycle_id": null,
  "amount_brl": "49.9000",
  "currency": "brl",
  "next_renewal_at": "2026-12-01T00:05:00.000Z",
  "release_cutoff_at": null,
  "renewal_warning_48h_at": null,
  "renewal_warning_24h_at": null,
  "grace_selected_at": null,
  "grace_ends_at": null,
  "automatic_release_enabled": false,
  "release_requested_at": null,
  "recommended_action": "add_credit_or_enable_auto_topup",
  "evaluated_at": "2026-11-10T12:00:00.000Z",
  "provider_evidence_observed_at": null
}

{
  "state": "upcoming",
  "reason_codes": [],
  "cycle_id": null,
  "amount_brl": "49.9000",
  "currency": "brl",
  "next_renewal_at": "2026-12-01T00:05:00.000Z",
  "release_cutoff_at": null,
  "renewal_warning_48h_at": null,
  "renewal_warning_24h_at": null,
  "grace_selected_at": null,
  "grace_ends_at": null,
  "automatic_release_enabled": true,
  "release_requested_at": null,
  "recommended_action": "none",
  "evaluated_at": "2026-11-10T12:00:00.000Z",
  "provider_evidence_observed_at": null
}