Look up SMS OUT Prices#

Returns the SMS OUT prices of one number or one country in the plan assigned to the account in an SMS OUT domain: A2P, P2P or OTP. The three domains have the same request and response format; the path selects the domain.

  • With filter[dst_number], the number is matched against the destination prefixes of the plan. The longest prefix covering the number wins, and every price of the plan 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 (source_prefix), by the destination network (mcc and mnc, which only the delivery decides) and by plan settings that the API does not return. The collection is therefore the prices of the plan that apply, not the one price that is charged. A destination that the plan rejects is still returned: reject_sms is true and price is null.

Request#

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

HTTP Method: GET

URI Path:

Domain

URI Path

SMS OUT A2P

/v3/sms_out/a2p/lookup/prices

SMS OUT P2P

/v3/sms_out/p2p/lookup/prices

SMS OUT OTP

/v3/sms_out/otp/lookup/prices

Note

For all returned data attributes, see SMS OUT 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_out/a2p/lookup/prices?filter%5Bdst_number%5D=4915123456789 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_out/a2p/lookup/prices?filter%5Bdst_number%5D=4915123456789' -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": "d8e4d372-42a6-4bb6-80ec-6c29c49aa9fd",
 8            "type": "prices",
 9            "attributes": {
10                "source_prefix": null,
11                "destination_prefix": "49151",
12                "country": "Germany",
13                "mcc": 262,
14                "mcc_name": "Germany",
15                "mnc": 1,
16                "mnc_name": "Telekom Deutschland",
17                "reject_sms": false,
18                "price": "0.075"
19            }
20        },
21        {
22            "id": "e554d414-527f-411f-b021-e63c554606c4",
23            "type": "prices",
24            "attributes": {
25                "source_prefix": null,
26                "destination_prefix": "49151",
27                "country": "Germany",
28                "mcc": 262,
29                "mcc_name": "Germany",
30                "mnc": 2,
31                "mnc_name": "Vodafone",
32                "reject_sms": false,
33                "price": "0.078"
34            }
35        }
36    ],
37    "meta": {
38        "total_records": 2
39    }
40}

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.