# Look up Inbound Call Prices

Returns the inbound call prices that cover one number in the plan assigned to the account.

The number is matched against the destination prefixes of the plan. For every source type
and destination country that the plan prices, the longest prefix covering the number
answers, so the collection contains one price per such pair. The collection is never empty:
a number that no prefix covers returns `404` with the error code `price_not_found`.

- Without `filter[src_country_iso]`, only the prices that apply to a call from any country
  take part.
- With `filter[src_country_iso]`, a price that the plan sets for calls from that country
  ranks above the any-source price of the same source type and destination country,
  whatever their prefix lengths. The any-source price answers where the plan sets no price
  for that country. `src_country_name` names the country whose price answered, and is
  `null` when the any-source price answered.
- A destination that the plan rejects is still returned: `reject_calls` is `true`, and
  `rate` and `connection_fee` are `null`.

## Request

Host: `api-vin.didww.com` (Sandbox: `api-vin-sandbox.didww.com`)

HTTP Method: `GET`

URI Path: `/v3/lookup/prices`

Note

For all returned data attributes, see [Inbound Call Price Object](inbound-call-price-object.html).

The access token must list `api-vin.didww.com` in its `aud`. The `read` scope is
enough. `filter` is the only query parameter read: `sort`, `page`, `fields`,
`include` and any unrecognised parameter return `400 Bad Request`.

### URI Query Parameters

| Name | Type | Is Required? | Description |
| --- | --- | --- | --- |
| filter[number] | `string` | Yes | The number to price: `8` to `15` digits with a non-zero first digit, in international format without a `+` or a dialling prefix. Pattern: `^[1-9][0-9]{7,14}$`. |
| filter[src\_country\_iso] | `string` | No | The country the call comes from, as its upper-case ISO 3166-1 alpha-2 code (pattern `^[A-Z]{2}$`). A price that the plan sets for calls from that country then answers ahead of the any-source price. Without this filter, only any-source prices answer. |

## Examples

Look up a NumberLook up for a Source CountryNumber Not Covered

[[DIDWW-API-EXAMPLE-START]]

http

```
1GET /v3/lookup/prices?filter%5Bnumber%5D=18005550123 HTTP/1.1
2Host: api-vin.didww.com
3Accept: application/vnd.api+json
4Authorization: Bearer [access token]
```

curl

```
1curl -i -X GET 'https://api-vin.didww.com/v3/lookup/prices?filter%5Bnumber%5D=18005550123' -H "Accept: application/vnd.api+json" -H "Authorization: Bearer [access token]"
```

response

```
 1HTTP/1.1 200 OK
 2Content-Type: application/vnd.api+json
 3
 4{
 5    "data": [
 6        {
 7            "id": "df73d9e4-46ce-4af0-817e-f090dc8144f1",
 8            "type": "prices",
 9            "attributes": {
10                "destination": "1800",
11                "country": "United States",
12                "src_country_name": null,
13                "source_type": "cellular",
14                "rate": "0.025",
15                "connection_fee": "0.0",
16                "initial_interval": 60,
17                "next_interval": 60,
18                "reject_calls": false
19            }
20        },
21        {
22            "id": "cd143ebe-a667-4823-bfea-315868ab502b",
23            "type": "prices",
24            "attributes": {
25                "destination": "1800",
26                "country": "United States",
27                "src_country_name": null,
28                "source_type": "fixed",
29                "rate": "0.018",
30                "connection_fee": "0.0",
31                "initial_interval": 60,
32                "next_interval": 60,
33                "reject_calls": false
34            }
35        }
36    ],
37    "meta": {
38        "total_records": 2
39    }
40}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
1GET /v3/lookup/prices?filter%5Bnumber%5D=448001234567&filter%5Bsrc_country_iso%5D=GB HTTP/1.1
2Host: api-vin.didww.com
3Accept: application/vnd.api+json
4Authorization: Bearer [access token]
```

curl

```
1curl -i -X GET 'https://api-vin.didww.com/v3/lookup/prices?filter%5Bnumber%5D=448001234567&filter%5Bsrc_country_iso%5D=GB' -H "Accept: application/vnd.api+json" -H "Authorization: Bearer [access token]"
```

response

```
 1HTTP/1.1 200 OK
 2Content-Type: application/vnd.api+json
 3
 4{
 5    "data": [
 6        {
 7            "id": "cb1335e1-6cfd-4921-8724-153d9ed67ac3",
 8            "type": "prices",
 9            "attributes": {
10                "destination": "44800",
11                "country": "United Kingdom",
12                "src_country_name": null,
13                "source_type": "cellular",
14                "rate": null,
15                "connection_fee": null,
16                "initial_interval": 60,
17                "next_interval": 60,
18                "reject_calls": true
19            }
20        },
21        {
22            "id": "accabf9c-cd90-4ff8-9bc1-a14fa8ca7ec0",
23            "type": "prices",
24            "attributes": {
25                "destination": "4480012",
26                "country": "United Kingdom",
27                "src_country_name": "United Kingdom",
28                "source_type": "fixed",
29                "rate": "0.0125",
30                "connection_fee": "0.0",
31                "initial_interval": 60,
32                "next_interval": 60,
33                "reject_calls": false
34            }
35        }
36    ],
37    "meta": {
38        "total_records": 2
39    }
40}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
1GET /v3/lookup/prices?filter%5Bnumber%5D=99912345678 HTTP/1.1
2Host: api-vin.didww.com
3Accept: application/vnd.api+json
4Authorization: Bearer [access token]
```

curl

```
1curl -i -X GET 'https://api-vin.didww.com/v3/lookup/prices?filter%5Bnumber%5D=99912345678' -H "Accept: application/vnd.api+json" -H "Authorization: Bearer [access token]"
```

response

```
 1HTTP/1.1 404 Not Found
 2Content-Type: application/vnd.api+json
 3
 4{
 5    "errors": [
 6        {
 7            "title": "Price not found",
 8            "detail": "No effective price covers this number in the assigned plan.",
 9            "code": "price_not_found",
10            "status": "404"
11        }
12    ]
13}
```

[[DIDWW-API-EXAMPLE-END]]

## Other Responses

| Code | Success | Description |
| --- | --- | --- |
| 400 | No | Malformed request: `filter[number]` is missing, blank, or not `8` to `15` digits with a non-zero first digit; `filter[src_country_iso]` is not the upper-case code of a known country; another filter is sent; or another query parameter is sent (`sort`, `page`, `fields`, `include` or an unrecognised one). |
| 401 | No | [Unauthorized](../../authentication.html#authentication-v35). The bearer token was refused. The response carries `WWW-Authenticate: Bearer error="invalid_token"`. |
| 403 | No | The token does not carry the `read` scope (title `Insufficient scope`). The response carries `WWW-Authenticate: Bearer error="insufficient_scope"`. |
| 404 | No | No price plan is assigned to the account (`price_plan_not_assigned`), or no prefix of the plan covers the number (`price_not_found`). |
| 406 | No | The `Accept` header admits neither `application/vnd.api+json` nor `*/*`. |
| 429 | No | The request budget of the account on this service for the current window is spent (`too_many_requests`). `Retry-After` gives the number of seconds to wait. |
