# Inbound Call Prices

Use the Inbound Call Prices resource to read what inbound calls to your toll-free, shared-cost
and metered numbers cost, as priced by the inbound call pricing plan assigned to your DIDWW account.

Inbound call prices are served by the Inbound Call Rates service:

| Environment | Base URL |
| --- | --- |
| Production | `https://api-vin.didww.com/v3` |
| Sandbox | `https://api-vin-sandbox.didww.com/v3` |

The access token must list `api-vin.didww.com` in its `aud`, on the sandbox host as well.
A token with the `read` scope is enough. See [Prices Resources](../index.html) for
authentication, common rules and errors.

An inbound call price depends on the destination prefix of the called number, the destination
country, the calling party category (`source_type`, such as `cellular` or `fixed`)
and, for some prices, the country the call comes from. Prices are in USD, VAT excluded.

## Endpoints

| Action | Method | Endpoint |
| --- | --- | --- |
| Look up inbound call prices | `GET` | `/v3/lookup/prices` |
| Download inbound call price file | `GET` | `/v3/prices.csv.gz` |
| Check inbound call price file | `HEAD` | `/v3/prices.csv.gz` |

## Look up inbound call prices

Returns the prices that cover one number: for every source type and destination country
that the plan prices, the price of the longest prefix covering the number.

`filter[number]` is required. Add `filter[src_country_iso]` to include the prices that
the plan sets for calls from a specific country.

See [Look up Inbound Call Prices](lookup-inbound-call-prices.html).

```
GET /v3/lookup/prices?filter[number]=18005550123
```

## Download inbound call price file

Downloads the whole price list of the plan as `voice_in_prices.csv.gz`. Use `HEAD` or
`If-Modified-Since` to check whether your copy is current.

See [Get Inbound Call Price File](get-inbound-call-price-file.html).

```
GET /v3/prices.csv.gz
HEAD /v3/prices.csv.gz
```

## Data reference

See [Inbound Call Price Object](inbound-call-price-object.html) for all attributes returned by a
lookup.

## Common inbound call pricing use cases

| Use case | Description |
| --- | --- |
| Estimate the cost of inbound calls to a number | Look up the number and compare the prices of each source type. |
| Price calls from a specific country | Add `filter[src_country_iso]` to see the price the plan sets for calls from that country. |
| Check rejected destinations | Find prices where `reject_calls` is `true`. |
| Keep a local price list | Download the price file and refresh it when `Last-Modified` changes. |

## Related resources

| Resource | Description |
| --- | --- |
| [DIDs](../../inventory-resources/did/index.html) | DID phone numbers owned by the account. |
| [Outbound Call Prices](../outbound-call-prices/index.html) | Prices of outbound calls. |
| [SMS Prices](../sms-prices/index.html) | Prices of inbound and outbound SMS. |
