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.

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#

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}

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