# Look up Outbound Call Prices

Returns the outbound 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 set of routing
conditions that the plan prices, the longest prefix covering the number answers, so the
collection contains one price per such set. The collection is never empty: a number that no
prefix covers returns `404` with the error code `price_not_found`.

- A prefix answers only while its price is in effect, and only for a number whose length is
  within the bounds that the plan sets for it.
- A change that is already scheduled is returned in the `next_` attributes and
  `effective_at`, and named by `comment`.
- A destination that the plan rejects is still returned: `reject_calls` is `true`, and
  `rate` and `connection_fee` are `null`.

## Request

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

HTTP Method: `GET`

URI Path: `/v3/lookup/prices`

Note

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

The access token must list `api-vout.didww.com` in its `aud`. The `read` scope is
enough. `filter[number]` is the only query parameter read. Any other filter, including
`filter[src_country_iso]` and `filter[id]`, and `sort`, `page`, `fields`,
`include` or 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}$`. |

## Examples

Look up a NumberRejected DestinationUnsupported Filter

[[DIDWW-API-EXAMPLE-START]]

http

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

curl

```
1curl -i -X GET 'https://api-vout.didww.com/v3/lookup/prices?filter%5Bnumber%5D=493012345678' -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": "7b82cac2-c42a-4fa9-8da4-ccba2843068f",
 8            "type": "prices",
 9            "attributes": {
10                "category": "International",
11                "country": "Germany",
12                "network": "Fixed",
13                "prefix": "4930",
14                "rate": "0.0045",
15                "connection_fee": "0.0",
16                "initial_increment": 1,
17                "recurring_increment": 1,
18                "reject_calls": false,
19                "next_rate": "0.005",
20                "next_connection_fee": "0.0",
21                "next_initial_increment": 1,
22                "next_recurring_increment": 1,
23                "effective_at": "2026-11-01T00:00:00.000Z",
24                "comment": "Increase"
25            }
26        },
27        {
28            "id": "9159cccf-ec23-459a-b63b-94a0ade0fa51",
29            "type": "prices",
30            "attributes": {
31                "category": "Origin based",
32                "country": "Germany",
33                "network": "Fixed",
34                "prefix": "4930",
35                "rate": "0.0012",
36                "connection_fee": "0.0",
37                "initial_increment": 1,
38                "recurring_increment": 1,
39                "reject_calls": false,
40                "next_rate": null,
41                "next_connection_fee": null,
42                "next_initial_increment": null,
43                "next_recurring_increment": null,
44                "effective_at": null,
45                "comment": null
46            }
47        }
48    ],
49    "meta": {
50        "total_records": 2
51    }
52}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

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

curl

```
1curl -i -X GET 'https://api-vout.didww.com/v3/lookup/prices?filter%5Bnumber%5D=88213456789' -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": "78602463-2614-4b67-99f6-729c34254b57",
 8            "type": "prices",
 9            "attributes": {
10                "category": "International",
11                "country": null,
12                "network": null,
13                "prefix": "88213",
14                "rate": null,
15                "connection_fee": null,
16                "initial_increment": 1,
17                "recurring_increment": 1,
18                "reject_calls": true,
19                "next_rate": null,
20                "next_connection_fee": null,
21                "next_initial_increment": null,
22                "next_recurring_increment": null,
23                "effective_at": null,
24                "comment": null
25            }
26        }
27    ],
28    "meta": {
29        "total_records": 1
30    }
31}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

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

curl

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

response

```
 1HTTP/1.1 400 Bad Request
 2Content-Type: application/vnd.api+json
 3
 4{
 5    "errors": [
 6        {
 7            "title": "Filter not allowed",
 8            "detail": "src_country_iso is not allowed.",
 9            "code": "102",
10            "status": "400"
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; a filter other than `number` is sent, `filter[id]` and `filter[src_country_iso]` included; 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. |
