canonical: https://jentic.com/apis/nexmo.com/nexmo-pricing-api

# Nexmo Pricing API

The Nexmo Pricing API exposes outbound SMS, voice, and other Vonage service rates so applications can calculate cost before sending traffic. It returns full pricing tables, per-country pricing, and per-prefix pricing for any service type, which lets billing dashboards, finance teams, and routing systems make cost-aware decisions in real time. The endpoint is rate-limited to one request per second, so the typical pattern is to fetch the full pricing table once and cache locally.

## For AI agents

Retrieve outbound SMS and voice pricing per country or per dialing prefix so an agent can estimate spend before sending traffic.

## Scope

Does not send messages, place calls, or expose inbound pricing - use for outbound SMS and voice rate lookups only.

## Capabilities

- Retrieve the full outbound pricing table for SMS, voice, or any other service type
- Look up the price of an outbound SMS to a specific country by ISO code
- Look up the price of a number by dialing prefix when the destination country is unknown
- Compare carrier-level pricing across mobile networks within a single country
- Feed live pricing into a routing engine that picks least-cost destinations

## Use cases

### Cost estimation before send

Customer success and billing dashboards call /get-pricing/outbound/sms with a country code to display the per-message rate beside a campaign builder. Showing the rate up-front prevents finance surprises and lets account managers approve high-volume campaigns with full cost visibility before any traffic actually flows.

Example prompt: GET /get-pricing/outbound/sms?country=BR and surface the unit price beside the campaign volume slider

### Least-cost routing

Routing engines that send the same message via multiple providers fetch the full Nexmo pricing table via /get-full-pricing/outbound/sms, cache it locally, and join it against equivalent tables from other vendors to choose the cheapest viable route per destination. Because the endpoint is rate-limited to 1 request per second, a daily refresh into a local store is the right pattern.

Example prompt: GET /get-full-pricing/outbound/sms once per day, cache the response, and join against vendor B's table to pick the cheapest route per destination

### Prefix-based price lookup

When a number is captured in raw E.164 form without a country code mapping, applications call /get-prefix-pricing/outbound/sms with the leading digits to fetch the price directly. This is essential for fraud and abuse teams reviewing logs of outbound traffic where only the dialed digits are recorded, not the parsed country.

Example prompt: GET /get-prefix-pricing/outbound/sms?prefix=44 and return the per-network breakdown for the United Kingdom

### AI agent cost-aware routing via Jentic

An AI agent that sends transactional notifications can call the Pricing API through Jentic to make cost-aware sending decisions per message. The agent searches for the pricing operation, supplies the country, and Jentic returns the unit cost which the agent compares against alternative providers before executing the send.

Example prompt: Search Jentic for 'get sms pricing for a country', load /get-pricing/outbound/sms, and execute with country=DE

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /get-full-pricing/outbound/{type} | Full outbound pricing table for a service type |
| GET | /get-pricing/outbound/{type} | Outbound pricing for a specific country |
| GET | /get-prefix-pricing/outbound/{type} | Outbound pricing for a specific dialing prefix |

## Key resources

- **Full pricing** — GET /get-full-pricing/outbound/{type} returns the complete outbound pricing table for a service.
- **Country pricing** — GET /get-pricing/outbound/{type} returns pricing for a specific country.
- **Prefix pricing** — GET /get-prefix-pricing/outbound/{type} returns pricing for a specific dialing prefix.

## Why Jentic

- **Setup:** Wiring the Pricing API by hand means attaching your Nexmo credentials to every rate lookup and targeting the rest.nexmo.com/account host with the right SMS or voice type. Through Jentic you install once, import the Pricing API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** The Pricing API takes the rate type in the path and country details in the query, so scoping is by operation rather than by resource: limit the agent to the operations it needs, such as a full pricing or per-prefix outbound lookup. These are read-only rate lookups, and nothing beyond the allowed ones runs.
- **Credential handling:** Your Nexmo api_key and api_secret are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get SMS pricing for a country', and Jentic returns the matching outbound pricing operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Twilio Pricing v2** — Twilio's equivalent pricing API covering messaging, voice, and phone numbers.
- **Nexmo SMS API** — The SMS API is the spend driver whose unit cost the Pricing API surfaces.
- **Nexmo Account API** — Account API exposes balance and top-up state that pairs naturally with pricing for spend forecasting.

## FAQ

### What authentication does the Nexmo Pricing API use?

The OpenAPI spec for Pricing v0.0.3 does not declare a security scheme on its operations, but in practice Vonage requires the same apiKey and apiSecret query parameters as the rest of the platform. Through Jentic those credentials live in the encrypted vault and never reach the agent.

### Can I get inbound pricing through this API?

No - every operation in the spec is scoped to outbound traffic. The path templates are /outbound/{type} and there is no /inbound counterpart. For inbound costs (which Vonage charges differently per number type) consult the Numbers API metadata or your Vonage dashboard.

### What are the rate limits for the Pricing API?

The Pricing API is rate-limited to one request per second per account. The right pattern is to call /get-full-pricing/outbound/{type} once a day, cache the table in your own store, and serve cost lookups from cache rather than hitting the live endpoint per send.

### How do I get SMS pricing for a country through Jentic?

Run pip install jentic, search for 'get outbound sms pricing for a country', and Jentic returns GET /get-pricing/outbound/sms. Execute with country=DE and Jentic returns the per-network price breakdown directly.

### What service types are supported on the {type} parameter?

The Pricing API supports sms, sms-transit, and voice as the {type} path parameter on all three endpoints. Calling the same path with different service types lets a finance pipeline pull a complete cost picture for a destination in three calls.

### Is the Nexmo Pricing API free to call?

Yes - Vonage does not charge per pricing-lookup. Only the underlying SMS and voice traffic incurs cost. That said, the 1-request-per-second rate limit means you should not poll it as a cheap alternative to caching.

### Can I limit what my agent is allowed to do with the Nexmo Pricing API?

Yes. Because you run Jentic One yourself, your own rules decide which operations the agent may call, so you can grant only the read-only rate lookups it needs, such as the per-country outbound lookup while withholding the full-table or per-prefix operations. Every operation here is a read-only pricing query scoped by the rate type in the path, so nothing beyond the operations you allow will run. The agent never sees your api_key or api_secret, since those are stored and injected by your instance at execution time.