# Look up SMS IN Prices

Returns the SMS IN prices of one number or one country in the plan assigned to the account in
the SMS IN domain.

- With `filter[dst_number]`, the number is matched against the destination prefixes of the
  plan. Only the prices whose destination length range holds the number take part. The
  longest prefix covering the number among them wins, and every such price under that prefix
  is returned.
- With `filter[dst_country_iso]` alone, every price of the plan for that country is
  returned, under every prefix.
- With both filters, the country narrows the prices before the prefixes are ranked.

At least one of the two filters is required. The collection is never empty: a number that no
price of the plan covers, or a country that the plan does not price, returns `404` with the
error code `price_not_found`. Prices under one prefix can differ by the sending number they
apply to and by their length ranges.

## Request

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

HTTP Method: `GET`

URI Path: `/v3/sms_in/lookup/prices`

Note

For all returned data attributes, see [SMS IN Price Object](sms-in-price-object.html).

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

### URI Query Parameters

| Name | Type | Is Required? | Description |
| --- | --- | --- | --- |
| filter[dst\_number] | `string` | Required unless `filter[dst_country_iso]` is sent | 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[dst\_country\_iso] | `string` | Required unless `filter[dst_number]` is sent | The destination country, as its upper-case ISO 3166-1 alpha-2 code (pattern `^[A-Z]{2}$`). Alone, every price of the plan for that country is returned. With a number, only the prices of that country take part in the match. |

## Examples

Prices of a NumberPrices of a Country

[[DIDWW-API-EXAMPLE-START]]

http

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

curl

```
1curl -i -X GET 'https://api-sms.didww.com/v3/sms_in/lookup/prices?filter%5Bdst_number%5D=12025550123' -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": "e93f925e-25ee-4060-bd50-a790b4945d3f",
 8            "type": "prices",
 9            "attributes": {
10                "source_prefix": null,
11                "source_number_length_min": 1,
12                "source_number_length_max": 15,
13                "destination_prefix": "1",
14                "destination_number_length_min": 11,
15                "destination_number_length_max": 11,
16                "country": "United States",
17                "price": "0.005"
18            }
19        },
20        {
21            "id": "6ee8d81e-cedf-4a1e-a397-56f36f3836d0",
22            "type": "prices",
23            "attributes": {
24                "source_prefix": "1",
25                "source_number_length_min": 11,
26                "source_number_length_max": 11,
27                "destination_prefix": "1",
28                "destination_number_length_min": 11,
29                "destination_number_length_max": 11,
30                "country": "United States",
31                "price": "0.0"
32            }
33        }
34    ],
35    "meta": {
36        "total_records": 2
37    }
38}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

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

curl

```
1curl -i -X GET 'https://api-sms.didww.com/v3/sms_in/lookup/prices?filter%5Bdst_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": "168b58a0-ee9c-4f6d-994d-98c3174bf2e4",
 8            "type": "prices",
 9            "attributes": {
10                "source_prefix": null,
11                "source_number_length_min": 1,
12                "source_number_length_max": 15,
13                "destination_prefix": "447",
14                "destination_number_length_min": 12,
15                "destination_number_length_max": 12,
16                "country": "United Kingdom",
17                "price": "0.003"
18            }
19        }
20    ],
21    "meta": {
22        "total_records": 1
23    }
24}
```

[[DIDWW-API-EXAMPLE-END]]

## Other Responses

| Code | Success | Description |
| --- | --- | --- |
| 400 | No | Malformed request: neither `filter[dst_number]` nor `filter[dst_country_iso]` is sent; `filter[dst_number]` is not `8` to `15` digits with a non-zero first digit; `filter[dst_country_iso]` is not the upper-case code of a known country; another filter is sent, `filter[id]` 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 | The account holds no price plan of the service in this domain, either no plan at all or a plan for which the service publishes no prices (`price_plan_not_assigned`), or no price of the plan matches the filters (`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. |
