Prices Resources#
Use Prices Resources to read the prices of the plans assigned to your DIDWW account. You can look up what one number costs (for SMS, also every price of one country), or download the whole price list of a plan as a compressed CSV file.
Prices are served by three dedicated services, each on its own host. They are not served by
api.didww.com: send each request to the host of the service whose prices you need.
Service |
Prices |
Production |
Sandbox |
|---|---|---|---|
Inbound Call Rates |
Inbound calls to toll-free, shared-cost and metered numbers. |
|
|
Outbound Call Rates |
Outbound calls to each destination, including scheduled price changes. |
|
|
SMS Rates |
SMS IN, and SMS OUT for the A2P, P2P and OTP plans. |
|
|
All prices are the values of the plan assigned to the account, in USD, VAT excluded.
Resource overview#
Resource |
Use it to |
|---|---|
Look up the inbound call prices of a number, or download the inbound call price file. |
|
Look up the current and next outbound call prices of a number, or download the outbound call price file. |
|
Look up the SMS IN or SMS OUT prices of a number or a country, or download the SMS price files. |
Endpoints#
Service |
Action |
Method |
Endpoint |
|---|---|---|---|
Inbound Call Rates |
Look up prices |
|
|
Inbound Call Rates |
Download price file |
|
|
Outbound Call Rates |
Look up prices |
|
|
Outbound Call Rates |
Download price file |
|
|
SMS Rates |
Look up SMS IN prices |
|
|
SMS Rates |
Download SMS IN price file |
|
|
SMS Rates |
Look up SMS OUT prices |
|
|
SMS Rates |
Download SMS OUT price file |
|
|
Inbound Call Rates and Outbound Call Rates use the same paths. The host of the request selects the service.
Authentication#
Every request is authenticated with a bearer access token in the Authorization header:
Authorization: Bearer [access token]
Mint the token with POST /token on the token service of the environment you call
(https://auth.didww.com/token for Production, https://auth-sandbox.didww.com/token
for Sandbox), with an API key of that environment. A token minted in one environment is
refused by the other. See Authentication.
A service accepts a token only when the token’s aud lists the audience of that service.
The audience is the production host name of the service, on the production and on the
sandbox host alike:
Service |
Audience ( |
|---|---|
Inbound Call Rates |
|
Outbound Call Rates |
|
SMS Rates |
|
These audiences apply to the price lookup, download and file-header endpoints listed
above. To configure phone numbers or voice and SMS trunks, use api.didww.com.
See Audiences for the complete service mapping.
Mint one token per service, or one token that lists every service you call. Every prices
operation only reads, so a token minted with the read scope is enough. For example, the
body of a POST /token request for a read-only token accepted by all three services:
1{
2 "aud": ["api-vin.didww.com", "api-vout.didww.com", "api-sms.didww.com"],
3 "scope": "read"
4}
Price lookups#
A lookup is a JSON:API GET request that returns a collection of resources of type
prices.
Send
Accept: application/vnd.api+json. A request whoseAcceptheader admits neitherapplication/vnd.api+jsonnor*/*returns406 Not Acceptable.filteris the only query parameter a lookup reads.sort,page,fields,include, a filter the lookup does not support and any unrecognised parameter return400 Bad Request.datais never empty. When nothing in the plan matches the filters, the response is404with the error codeprice_not_found.meta.total_recordsis the number of resources indata. Lookups are not paginated.Each resource has a UUID
idthat names the answering price. It is a name, not an address: there is no endpoint that returns a single price by its ID.Prices are decimal strings. In inbound call, outbound call, and SMS OUT lookups, a destination that the plan rejects is still returned: its
reject_callsorreject_smsattribute istrueand its current price (rateandconnection_fee, orprice) isnull.
Price files#
A price file contains the whole price list of the plan assigned to the account.
GETreturns the file as a gzipped CSV (Content-Type: application/gzip): UTF-8, LF line endings, and a header row. The file is served whole, without byte ranges.HEADreturns the same headers without the body, so you can check whether your copy is current before you download the file.The file belongs to the account. One URL returns each account the file of its own plan.
A successful response carries these headers:
Header |
Description |
|---|---|
Content-Disposition |
|
Last-Modified |
HTTP date of the later of the last change of the file content and the last change of the account’s plan assignment. Send it back in |
Cache-Control |
Always |
Accept-Ranges |
Always |
Vary |
Always |
Content-Length |
Size of the gzipped file in bytes. A |
Conditional requests#
Conditional requests use Last-Modified and If-Modified-Since only:
Send the
Last-Modifiedvalue of the copy you hold in theIf-Modified-Sincerequest header. If the file has not changed since that date, the response is304 Not Modifiedwith the headers of the200response exceptContent-Length, and no body.No
ETagis sent. A request that carriesIf-None-Matchis always answered in full, and itsIf-Modified-Sinceheader is ignored.Because
Last-Modifiedalso reflects changes of the plan assignment, an account that is moved to another plan never receives304for the prices of the plan it left.
When the file cannot be served, for example because the assigned plan has no generated file
yet, the response is 503 Service Unavailable with the error code serving_failure and a
Retry-After header.
Errors#
Errors are returned as JSON:API error documents (see Error objects).
Responses to HEAD requests carry no body. Each prices service counts the requests of
an account in its own budget; once it is spent, that service returns 429 Too Many Requests.
Status |
Error code |
Returned when |
|---|---|---|
400 |
Numeric JSON:API code, for example |
Lookups only. A filter is missing or malformed, a filter is not supported, or the request carries another query parameter ( |
401 |
|
The bearer token was refused: absent, malformed, expired, signed by a key this service does not hold, minted for another audience or environment, presented from an address outside the IP allowlist of the API key it was minted with, or naming an account this service has no record of. The response carries |
403 |
|
The token does not carry the |
404 |
|
No price plan is assigned to the account. For SMS Rates, the account holds no price plan of the service in the requested domain. |
404 |
|
Lookups only. Nothing in the plan matches the filters. |
406 |
Lookups only. The |
|
429 |
|
The request budget of the account on this service for the current window is spent. |
503 |
|
Price files only. The file could not be served. |
Example of an error response:
HTTP/1.1 404 Not Found
Content-Type: application/vnd.api+json
{
"errors": [
{
"title": "Price plan not assigned",
"detail": "No price plan is assigned to this account.",
"code": "price_plan_not_assigned",
"status": "404"
}
]
}
Common prices use cases#
Use case |
Description |
|---|---|
Show the price of a call before it is made |
Look up a number on Outbound Call Rates and read |
Track upcoming outbound call price changes |
Read the |
Estimate the cost of inbound toll-free traffic |
Look up a toll-free number on Inbound Call Rates, optionally for a given source country. |
Compare SMS prices of a destination country |
Look up the SMS OUT prices of a country with |
Keep a local copy of a price list |
Download a price file, then check it periodically with |