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.

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#

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}

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. 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.