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.

https://api-vin.didww.com/v3

https://api-vin-sandbox.didww.com/v3

Outbound Call Rates

Outbound calls to each destination, including scheduled price changes.

https://api-vout.didww.com/v3

https://api-vout-sandbox.didww.com/v3

SMS Rates

SMS IN, and SMS OUT for the A2P, P2P and OTP plans.

https://api-sms.didww.com/v3

https://api-sms-sandbox.didww.com/v3

All prices are the values of the plan assigned to the account, in USD, VAT excluded.

Resource overview#

Resource

Use it to

Inbound Call Prices

Look up the inbound call prices of a number, or download the inbound call price file.

Outbound Call Prices

Look up the current and next outbound call prices of a number, or download the outbound call price file.

SMS Prices

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

GET

/v3/lookup/prices

Inbound Call Rates

Download price file

GET, HEAD

/v3/prices.csv.gz

Outbound Call Rates

Look up prices

GET

/v3/lookup/prices

Outbound Call Rates

Download price file

GET, HEAD

/v3/prices.csv.gz

SMS Rates

Look up SMS IN prices

GET

/v3/sms_in/lookup/prices

SMS Rates

Download SMS IN price file

GET, HEAD

/v3/sms_in/prices.csv.gz

SMS Rates

Look up SMS OUT prices

GET

/v3/sms_out/{a2p|p2p|otp}/lookup/prices

SMS Rates

Download SMS OUT price file

GET, HEAD

/v3/sms_out/{a2p|p2p|otp}/prices.csv.gz

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 (aud)

Inbound Call Rates

api-vin.didww.com

Outbound Call Rates

api-vout.didww.com

SMS Rates

api-sms.didww.com

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 whose Accept header admits neither application/vnd.api+json nor */* returns 406 Not Acceptable.

  • filter is the only query parameter a lookup reads. sort, page, fields, include, a filter the lookup does not support and any unrecognised parameter return 400 Bad Request.

  • data is never empty. When nothing in the plan matches the filters, the response is 404 with the error code price_not_found.

  • meta.total_records is the number of resources in data. Lookups are not paginated.

  • Each resource has a UUID id that 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_calls or reject_sms attribute is true and its current price (rate and connection_fee, or price) is null.

Price files#

A price file contains the whole price list of the plan assigned to the account.

  • GET returns 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.

  • HEAD returns 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

attachment with the file name of the price domain, for example voice_in_prices.csv.gz.

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 If-Modified-Since.

Cache-Control

Always private. The file is served per account.

Accept-Ranges

Always none. The file is served whole.

Vary

Always Authorization. A cache keyed by the URL alone must not return the file to another account.

Content-Length

Size of the gzipped file in bytes. A HEAD response returns the size that the download sends.

Conditional requests#

Conditional requests use Last-Modified and If-Modified-Since only:

  • Send the Last-Modified value of the copy you hold in the If-Modified-Since request header. If the file has not changed since that date, the response is 304 Not Modified with the headers of the 200 response except Content-Length, and no body.

  • No ETag is sent. A request that carries If-None-Match is always answered in full, and its If-Modified-Since header is ignored.

  • Because Last-Modified also reflects changes of the plan assignment, an account that is moved to another plan never receives 304 for 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 102

Lookups only. A filter is missing or malformed, a filter is not supported, or the request carries another query parameter (sort, page, fields, include or an unrecognised one).

401

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 WWW-Authenticate: Bearer error="invalid_token".

403

403

The token does not carry the read scope (title Insufficient scope). The response carries WWW-Authenticate: Bearer error="insufficient_scope".

404

price_plan_not_assigned

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

price_not_found

Lookups only. Nothing in the plan matches the filters.

406

Lookups only. The Accept header admits neither application/vnd.api+json nor */*.

429

too_many_requests

The request budget of the account on this service for the current window is spent. Retry-After gives the number of seconds to wait.

503

serving_failure

Price files only. The file could not be served. Retry-After gives the number of seconds to wait.

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 rate, connection_fee and the billing increments.

Track upcoming outbound call price changes

Read the next_ attributes, effective_at and comment of a lookup, or the Next, Effective date and Comment columns of the outbound call price file.

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 filter[dst_country_iso].

Keep a local copy of a price list

Download a price file, then check it periodically with HEAD or a conditional GET that sends If-Modified-Since.