Java client for DIDWW API v3.
The DIDWW API provides a simple yet powerful interface that allows you to fully integrate your own applications with DIDWW services. An extensive set of actions may be performed using this API, such as ordering and configuring phone numbers, setting capacity, creating SIP trunks and retrieving CDRs and other operational data.
The DIDWW API v3 is a fully compliant implementation of the JSON API specification.
This SDK uses jsonapi-converter for JSON:API serialization and deserialization.
Read more https://doc.didww.com/api
This SDK targets DIDWW API version 2026-11-19 (DidwwClient.DEFAULT_API_VERSION). The version is not sent as a header: it is requested in the api_version of every access token the SDK mints (see Authentication).
| SDK Version | Branch | DIDWW API Version |
|---|---|---|
| 5.x | main |
2026-11-19 |
| 4.x | release-4.1 |
2026-04-16 |
| 3.x | 2022-05-10 |
2022-05-10 |
DidwwClient.Builder#apiVersion requests a later version. build() throws an IllegalArgumentException for a value that is not a YYYY-MM-DD date and for a version earlier than 2026-11-19. The resources of earlier API versions are not in this release: use 4.x from the release-4.1 branch for API 2026-04-16 (see Migrating from 4.x).
- Java 11+
The SDK depends on OkHttp 4, Jackson 2 and jsonapi-converter. It adds no logging dependency (see Logging).
This SDK is distributed via JitPack. JitPack builds the library directly from GitHub, so no manual publishing is required.
Browse all available versions (tags, branches, commits): https://jitpack.io/#didww/didww-api-3-java-sdk
repositories {
maven("https://jitpack.io")
}
dependencies {
implementation("com.github.didww:didww-api-3-java-sdk:5.0.0")
}<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.github.didww</groupId>
<artifactId>didww-api-3-java-sdk</artifactId>
<version>5.0.0</version>
</dependency>
</dependencies>For API 2026-04-16, stay on 4.x, for example com.github.didww:didww-api-3-java-sdk:4.1.4.
You can also consume the SDK from a specific branch or commit via JitPack:
dependencies {
// specific branch (append -SNAPSHOT)
implementation("com.github.didww:didww-api-3-java-sdk:main-SNAPSHOT")
// specific commit hash
// implementation("com.github.didww:didww-api-3-java-sdk:<commit-hash>")
}import com.didww.sdk.*;
import com.didww.sdk.resource.*;
import com.didww.sdk.http.QueryParams;
import java.util.List;
DidwwClient client = DidwwClient.builder()
.credentials(new DidwwCredentials("YOUR_API_KEY", DidwwEnvironment.SANDBOX))
.build();
// Check balance
Balance balance = client.balance().find().getData();
System.out.println("Balance: " + balance.getTotalBalance());
// List DID groups with stock keeping units
QueryParams params = QueryParams.builder()
.include("stock_keeping_units")
.filter("area_name", "Acapulco")
.build();
List<DidGroup> didGroups = client.didGroups().list(params).getData();DidwwClient is immutable once built and safe for concurrent use: build one per API key and environment and reuse it. Every call is synchronous.
For more examples visit examples.
For details on obtaining your API key please visit https://doc.didww.com/api3/configuration.html
- Source code: examples/src/main/java/com/didww/examples
- How to run: examples/README.md
import com.didww.sdk.auth.DidwwScope;
import java.time.Duration;
// Production
DidwwClient client = DidwwClient.builder()
.credentials(new DidwwCredentials("YOUR_API_KEY", DidwwEnvironment.PRODUCTION))
.build();
// Sandbox, read-only tokens, logging through System.Logger, a shorter connect timeout
DidwwClient sandbox = DidwwClient.builder()
.credentials(new DidwwCredentials("YOUR_API_KEY", DidwwEnvironment.SANDBOX))
.scope(DidwwScope.READ)
.logger(System.getLogger("com.didww.sdk"))
.connectTimeout(Duration.ofSeconds(5))
.build();| Builder method | Default | Description |
|---|---|---|
credentials(credentials) |
required | new DidwwCredentials(apiKey, environment), with DidwwEnvironment.PRODUCTION or DidwwEnvironment.SANDBOX. The environment selects the API, token service and price hosts. See Environments. |
apiVersion(version) |
DidwwClient.DEFAULT_API_VERSION |
API version requested in every token. See API Version. |
scope(scope) |
none | DidwwScope.READ or DidwwScope.FULL. Without it no scope is requested and the token service grants full. See Scope. |
tokenStore(store) |
one MemoryTokenStore shared by every client of the process built without its own |
Cache for access tokens. See Token cache. |
logger(logger) |
none: nothing is logged | java.lang.System.Logger for the token warnings and debug events. See Logging. |
httpClientBuilder(builder) |
an OkHttp client shared by the SDK | OkHttpClient.Builder used as the base of every call. See HTTP client. |
connectTimeout(timeout) |
10 s, or the one of your httpClientBuilder |
Time allowed to open the TCP connection (to the proxy when one is set). The TLS handshake and the tunnel through an HTTP proxy are bounded by the read timeout, as in OkHttp. |
readTimeout(timeout) |
60 s, or the one of your httpClientBuilder |
Longest wait for a proxy tunnel, the TLS handshake, the response headers and between two reads of a body. |
baseUrl(url) |
API URL of the environment | JSON:API base URL only, including /v3. |
authUrl(url) |
Token service of the environment | Token service base URL. |
voiceInPricesUrl(url), voiceOutPricesUrl(url), smsPricesUrl(url) |
Price hosts of the environment | Price service base URLs, with or without the /v3 suffix. |
The API key is sent only to the token service. An overridden URL, for example to send the traffic through a proxy, does not change the token audiences (see Authentication).
build() throws a NullPointerException without credentials (and new DidwwCredentials(...) one for a null API key or environment), and an IllegalArgumentException, before any request, for:
- an empty API key, or one with a character outside printable ASCII (a control character, such as a trailing newline or a tab, or a non-ASCII character, such as a non-breaking space);
- an API version that is not a
YYYY-MM-DDdate, or that is earlier than2026-11-19; - a base, token service or prices URL that is not an http or https URL with a host, contains a space or a control character, or has a query or fragment.
DidwwCredentials#toString() masks the API key.
| Environment | API | Token service | Voice IN prices | Voice OUT prices | SMS prices |
|---|---|---|---|---|---|
DidwwEnvironment.PRODUCTION |
https://api.didww.com/v3 |
https://auth.didww.com |
https://api-vin.didww.com/v3 |
https://api-vout.didww.com/v3 |
https://api-sms.didww.com/v3 |
DidwwEnvironment.SANDBOX |
https://sandbox-api.didww.com/v3 |
https://auth-sandbox.didww.com |
https://api-vin-sandbox.didww.com/v3 |
https://api-vout-sandbox.didww.com/v3 |
https://api-sms-sandbox.didww.com/v3 |
A firewall that limits outgoing traffic must allow the token service, and the price hosts when you use Prices.
Without httpClientBuilder every client of the process shares one OkHttp client, so they share its connection pool and dispatcher. It opens TCP connections within 10 s, waits up to 60 s for a proxy tunnel, the TLS handshake, the response headers and between two reads or writes of a body, and has no call timeout, so a large price or export file is not cut off while its data keeps arriving.
You can pass your own OkHttpClient.Builder, for example for a proxy or a custom trust store:
import java.net.InetSocketAddress;
import java.net.Proxy;
import java.time.Duration;
import okhttp3.OkHttpClient;
OkHttpClient.Builder httpBuilder = new OkHttpClient.Builder()
.proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("proxy.example.com", 8080)))
.connectTimeout(Duration.ofSeconds(10))
.readTimeout(Duration.ofSeconds(60));
DidwwClient client = DidwwClient.builder()
.credentials(new DidwwCredentials("YOUR_API_KEY", DidwwEnvironment.PRODUCTION))
.httpClientBuilder(httpBuilder)
.build();The SDK copies the builder and leaves yours unchanged. The copy is used for every call: the token service, the JSON:API, export download, encrypted file upload and prices. Your proxy, proxy authenticator, TLS settings, interceptors, connection pool and dispatcher are kept. On the copy the SDK:
- follows no redirects (
followRedirects(false)andfollowSslRedirects(false)), whatever your builder says, so that neither a token nor the API key is sent to another URL; - uses
CookieJar.NO_COOKIES, no HTTP cache and noAuthenticator, so no state is carried between calls or API keys; - adds the bearer token to every request, with an interceptor placed after yours.
Your builder's timeouts are kept as you set them; OkHttp's own defaults are 10 s each, and connectTimeout and readTimeout of the DidwwClient.Builder override them. A callTimeout on your builder bounds the whole call, body included, so it also cuts off the download of a large price or export file. Prefer a read timeout.
Your interceptors see the Api-Key header of the token requests, and a network interceptor also sees the Authorization header of the other requests. Do not log them: with OkHttp's HttpLoggingInterceptor, call redactHeader("Api-Key") and redactHeader("Authorization"), and keep in mind that OkHttp's Request and Headers toString() print the Api-Key header in clear.
Price and export files are requested with Accept-Encoding: identity and written exactly as served (gzipped); OkHttp's transparent decompression still applies to JSON:API answers. Each attempt of a token request is limited to 10 s, independently of your timeouts. An error answer is read up to 1 MiB, within the read timeout of the client (60 s when it has none).
OkHttp itself sends a request once more, without waiting and with the same token, when it is answered 503 with Retry-After: 0, or 408 without a positive Retry-After. The SDK accepts this; other 503 answers are not resent by OkHttp (see Price files for the SDK's own 503 retry).
Every request carries Authorization: Bearer <token>. The SDK mints the tokens itself with POST /token on the token service, sending your API key in the Api-Key header. The API key is sent nowhere else. No code change is needed for this: new DidwwCredentials("YOUR_API_KEY", environment) works as before.
-
Audience. One token per audience, minted on the first call to a service and reused until it expires. The audience is the production hostname of the service, in the sandbox too:
Calls Token audience JSON:API resources, export download, encrypted file upload api.didww.comVoice IN prices api-vin.didww.comVoice OUT prices api-vout.didww.comSMS OUT (A2P, P2P, OTP) and SMS IN prices api-sms.didww.comclient.publicKeys().list()is sent without a token. -
Expiry and 401. The SDK asks for the longest lifetime the token service grants, one hour (
expires_in: 3600), and caches a token for theexpires_ingranted, with no local expiry margin. When a request is answered 401, the SDK drops that token, mints a new one and sends the request once more. A second 401 drops the new token too and is not retried: it becomes the error of the call (see Error Handling). A 403, such asinsufficient_scope, is never retried. -
Concurrency. Concurrent calls of one
DidwwClientthat need the same token wait for a single mint, which runs on the thread of the first caller. A waiting thread that is interrupted stops waiting withAuthErrorKind.CONNECTION_ERRORand keeps its interrupt flag; the mint goes on for the other callers. -
Token service errors are thrown as
DidwwAuthExceptionfrom any call that needs a new token (kinds in Error Handling):- A 429 throws
AuthErrorKind.RATE_LIMITEDwithgetRetryAfter()(theRetry-Afterseconds, at least 1 s). Every further mint for the same token service and API key in the process fails the same way without a request until that time has passed, plus a small random delay so that clients do not retry in step. Such a refusal reports the time still left, so retry in a loop rather than once. - A 5xx answer, a connection failure or a timeout is retried with exponential backoff and full jitter (0.5 s base, 8 s cap, 4 attempts in all), then throws
SERVER_ERRORorCONNECTION_ERROR. - A 400, a 401 or a TLS failure is thrown at once, without a retry.
- A 429 throws
import com.didww.sdk.auth.DidwwScope;
DidwwClient readOnly = DidwwClient.builder()
.credentials(new DidwwCredentials("YOUR_API_KEY", DidwwEnvironment.PRODUCTION))
.scope(DidwwScope.READ) // GET and HEAD only; DidwwScope.FULL allows every method
.build();
// Without scope(...) no scope is sent and the token service grants full.A READ token is enough for the price lookups and price files. A write with a READ token is answered 403, which the JSON:API repositories throw as a DidwwApiException (see Error Handling).
The SDK compares each token it receives with what it asked for:
- a different
scope(for examplefullgranted for areadrequest) or a differentapi_versionis logged as a warning through the logger (see Logging), and the token is used; - a token with an empty access token, one that is not a valid header value, or one whose
auddoes not include the requested audience, throwsAuthErrorKind.INVALID_GRANTand is not cached.
Tokens are cached in a com.didww.sdk.auth.TokenStore, keyed by the token service URL, the API key (as a SHA-256 hash), the audience, the API version and the scope. The key is an opaque string starting with didww:token:v1:. Each entry is stored for the token's expires_in.
The default is one MemoryTokenStore in process memory, shared by every client of the process built without tokenStore(...); since the key covers the API key, clients of different accounts never see each other's tokens. To share tokens between processes, pass your own implementation, for example one backed by Redis:
public interface TokenStore {
AccessToken get(String key); // null when there is none or it has expired
void set(String key, AccessToken token, Duration ttl); // zero or negative ttl: no expiry
void delete(String key);
}DidwwClient client = DidwwClient.builder()
.credentials(new DidwwCredentials("YOUR_API_KEY", DidwwEnvironment.PRODUCTION))
.tokenStore(myRedisStore)
.build();AccessToken serializes with Jackson under its wire names (access_token, token_type, expires_in, aud, scope, api_version, minted_at), the access token included, so that a store can persist it, for example with new ObjectMapper().writeValueAsString(token) and readValue(json, AccessToken.class). Its toString() never shows the access token. A shared store holds live bearer tokens, so protect it like the API key. Processes that share a store can each mint once when a token is missing. A store must be safe for concurrent use.
A store that throws a RuntimeException does not fail the call: the error is logged as a warning, and the call goes on with a newly minted token (a failed write leaves the token uncached). Each call to a store other than MemoryTokenStore is limited to 10 seconds; the SDK runs it on a daemon thread and stops waiting after that, but an abandoned call keeps its thread until it returns, so bound the store's own I/O as well, for example with connect and read timeouts on the Redis client. After a 401 the refused token is deleted from the store only while it is still the stored one, so that a token another process has just stored survives; a store that keeps returning the refused token, for example after a failed delete, does not get it reused.
logger(...) takes a java.lang.System.Logger, so the SDK needs no logging dependency. Following the usual library convention, the default logs nothing, not even the mismatch warnings, until you pass a logger:
DidwwClient client = DidwwClient.builder()
.credentials(new DidwwCredentials("YOUR_API_KEY", DidwwEnvironment.PRODUCTION))
.logger(System.getLogger("com.didww.sdk"))
.build();System.getLogger logs through java.util.logging, unless a System.LoggerFinder routes it elsewhere, such as SLF4J's org.slf4j:slf4j-jdk-platform-logging or Log4j's org.apache.logging.log4j:log4j-jpl.
WARNING:DIDWW token scope mismatchandDIDWW token api_version mismatch(followed by the requested and granted values), and token store failures (DIDWW token store read failed,write failed,write skipped,delete failed, with the exception).DEBUG:DIDWW token minted, withaud,scope,api_version,expires_inandduration_ms.
Neither the token nor the API key is ever logged. A logger that throws does not fail the call.
- Audience strategy. One token per audience, minted on first use, rather than one token naming every service. An account that never calls the prices services never requests their audiences, so a refused audience cannot break DID management, and every token is valid for one service only.
- Cache store. In-process memory by default, shared by the clients of the process, because a Java service usually keeps its clients for its lifetime. A shared store is opt-in through
tokenStore(...). - Token lifetime. The longest the token service grants, one hour, so that a process mints each token as rarely as possible. Lifetime is decided by the server through the 401 refresh, not by a local expiry margin.
- Logger.
System.Logger, silent by default, so that the SDK does not pick a logging framework for you. - HTTP defaults. Connect and read timeouts but no call timeout, so that large files are not cut off; a call timeout you set is kept as given. No redirects, so that credentials stay on the configured hosts; no cookies, cache or authenticator, so that no state is carried between calls; no decompression of files, so that they are written as served.
- Gzip handling. Price and export files are streamed to your
OutputStreamor file exactly as served, still gzipped, without being held in memory. The SDK never decompresses a price file on its own:PriceFileReaderreads a downloaded file when you want rows, anddownloadAndDecompressExportwrites an export as plain CSV. - Upload retry. The 401 retry sends the request body a second time.
uploadEncryptedFiletakes the encrypted content as abyte[]and builds the multipart body in memory, so the retry always resends the complete body. - Blocking waits. Calls are synchronous: the token backoff and the price file 503 retry wait on the calling thread. An interrupt ends them with
CONNECTION_ERRORand keeps the thread's interrupt flag set.
import com.didww.sdk.*;
import com.didww.sdk.resource.*;
import com.didww.sdk.http.QueryParams;
DidwwClient client = DidwwClient.builder()
.credentials(new DidwwCredentials("YOUR_API_KEY", DidwwEnvironment.SANDBOX))
.build();
// Countries
List<Country> countries = client.countries().list().getData();
Country country = client.countries().find("uuid").getData();
// Regions
List<Region> regions = client.regions().list().getData();
// Cities
List<City> cities = client.cities().list().getData();
// Areas
List<Area> areas = client.areas().list().getData();
// NANPA Prefixes
List<NanpaPrefix> prefixes = client.nanpaPrefixes().list().getData();
// DID Groups (with stock keeping units), filtered by number type
QueryParams dgParams = QueryParams.builder()
.include("stock_keeping_units")
.filter("number_type", "toll_free")
.build();
List<DidGroup> groups = client.didGroups().list(dgParams).getData();
// Available DIDs (with DID group and stock keeping units)
QueryParams adParams = QueryParams.builder().include("did_group.stock_keeping_units").build();
List<AvailableDid> available = client.availableDids().list(adParams).getData();
// Proof Types
List<ProofType> proofTypes = client.proofTypes().list().getData();
// Public Keys
List<PublicKey> publicKeys = client.publicKeys().list().getData();
// Address Requirements
List<AddressRequirement> requirements = client.addressRequirements().list().getData();
// Supporting Document Templates
List<SupportingDocumentTemplate> templates = client.supportingDocumentTemplates().list().getData();
// Balance (singleton)
Balance balance = client.balance().find().getData();DidGroup, AddressRequirement, EmergencyRequirement and EmergencyCallingService carry getNumberType(), one of the NumberType values (LOCAL, NATIONAL, MOBILE, TOLL_FREE, SHARED_COST, GLOBAL; in filters use the wire form, such as toll_free). DidGroup#getIsDemo() flags demo groups. NumberType replaces the DidGroupType resource and the did_group_type relationship, which API 2026-11-19 no longer has. The pops resource is gone too: a Voice IN trunk carries its point of presence in the pop attribute (see Voice In Trunks).
The mandatory fields of AddressRequirement (getPersonalMandatoryFields(), getBusinessMandatoryFields()) and of EmergencyRequirement (getAddressMandatoryFields(), getPersonalMandatoryFields(), getBusinessMandatoryFields()) list the fields as the API spells them, such as birth_date, id_number, country or area, and are empty when nothing is mandatory. tax_id stands for Identity#getVatId(). ProofType#getEntityType() is address, business or personal.
// List DIDs
List<Did> dids = client.dids().list().getData();
// Update DID - assign trunk and capacity
Did did = client.dids().find("uuid").getData();
did.setDescription("Updated");
did.setCapacityLimit(20);
did.setVoiceInTrunk(trunk);
client.dids().update(did);A DID's inbound messages go to an SMS trunk or to an SMS trunk group. The two are exclusive: setSmsTrunk with a trunk also sends sms_trunk_group as null in the same request, and setSmsTrunkGroup with a group sends sms_trunk as null, as setVoiceInTrunk and setVoiceInTrunkGroup do. Setting one of them to null sends only that one as null; set both to unroute the DID.
// sends sms_trunk and sms_trunk_group: null
Did route = new Did().withId("did-uuid");
route.setSmsTrunk(new SmsTrunk().withId("sms-trunk-uuid"));
client.dids().update(route);
// sends sms_trunk_group and sms_trunk: null
Did toGroup = new Did().withId("did-uuid");
toGroup.setSmsTrunkGroup(new SmsTrunkGroup().withId("sms-trunk-group-uuid"));
client.dids().update(toGroup);
// unroute: sends sms_trunk: null and sms_trunk_group: null
Did unroute = new Did().withId("did-uuid");
unroute.setSmsTrunk(null);
unroute.setSmsTrunkGroup(null);
client.dids().update(unroute);
List<Did> routed = client.dids().list(QueryParams.builder()
.filter("sms_trunk.id", "sms-trunk-uuid")
.include("sms_trunk", "sms_trunk_group")
.build()).getData(); // did.getSmsTrunk(), did.getSmsTrunkGroup()An SMS trunk cannot be deleted while DIDs are routed to it, nor an SMS trunk group while DIDs are routed to it or to one of its trunks: unroute those DIDs, or route them elsewhere, first.
import com.didww.sdk.resource.configuration.*;
import com.didww.sdk.resource.enums.*;
// Create SIP trunk
VoiceInTrunk trunk = new VoiceInTrunk();
trunk.setName("My SIP Trunk");
trunk.setPriority(1);
trunk.setWeight(100);
trunk.setCliFormat(CliFormat.E164);
trunk.setRingingTimeout(30);
trunk.setPop(Pop.FRA); // optional; null lets DIDWW choose
SipConfiguration sip = new SipConfiguration();
sip.setHost("sip.example.com");
sip.setPort(5060);
sip.setCodecs(Arrays.asList(Codec.PCMA, Codec.PCMU, Codec.TELEPHONE_EVENT));
sip.setIceMode(IceMode.ACCEPT);
sip.setTransportProtocolId(TransportProtocol.UDP);
trunk.setConfiguration(sip);
VoiceInTrunk created = client.voiceInTrunks().create(trunk).getData();
// Update trunk
created.setDescription("Updated");
client.voiceInTrunks().update(created);
// Delete trunk
client.voiceInTrunks().delete(created.getId());codecs lists the codecs offered on calls to the trunk by name, in priority order: the first has the highest priority. It replaces codec_ids; the names are the Codec values. Left out, the trunk offers pcmu, pcma, g729, g723 and telephone_event. setIceMode, setRtcpMuxMode and setRtcpFeedbackMode take the IceMode, RtcpMuxMode and RtcpFeedbackMode values DISABLED (the default), ACCEPT or INITIATE.
pop is a plain attribute, one of the com.didww.sdk.resource.enums.Pop values (NYC, FRA, LAC, MIA, SG, HK, AMS, sent as nyc, fra, lac, mia, sg, hk, ams). Leave it null to let DIDWW choose; setPop(null) on a built or fetched trunk sends "pop": null. A value this SDK does not know reads as null. It is no longer a relationship and cannot be included.
VoiceInTrunk popUpdate = new VoiceInTrunk().withId("trunk-uuid");
popUpdate.setPop(Pop.AMS);
client.voiceInTrunks().update(popUpdate);A Voice In Trunk can also authenticate inbound calls via SIP registration credentials generated by DIDWW. The SDK auto-cascades the dependent fields the server requires:
setEnabledSipRegistration(true)clears any previously-sethost/port(the server rejects them with 422 otherwise);setHost(<non-null>)flipsenabledSipRegistrationtofalseand forcesuseDidInRuri = falseso the server accepts the disable PATCH.
The server generates incomingAuthUsername and incomingAuthPassword and
surfaces them in the response when SIP registration is enabled (read-only
— the SDK exposes only getters).
SipConfiguration sip = new SipConfiguration();
sip.setEnabledSipRegistration(true);
sip.setUseDidInRuri(true);
sip.setCnamLookup(true);
VoiceInTrunk trunk = new VoiceInTrunk();
trunk.setName("Office (registered)");
trunk.setConfiguration(sip);
SipConfiguration created = (SipConfiguration)
client.voiceInTrunks().create(trunk).getData().getConfiguration();
// created.getIncomingAuthUsername() — server-generated
// created.getIncomingAuthPassword() — server-generatedTo disable SIP registration on an existing trunk, just set host — the
cascade flips enabledSipRegistration and useDidInRuri to false
automatically:
SipConfiguration disable = new SipConfiguration();
disable.setHost("sip.example.com");
VoiceInTrunk update = new VoiceInTrunk().withId("trunk-uuid");
update.setConfiguration(disable);
client.voiceInTrunks().update(update);VoiceInTrunkGroup group = new VoiceInTrunkGroup();
group.setName("Primary Group");
group.setCapacityLimit(50);
VoiceInTrunkGroup created = client.voiceInTrunkGroups().create(group).getData();A Voice In trunk group cannot be deleted while DIDs are routed to it or to one of its trunks (422): unroute those DIDs, or route them elsewhere, first.
Note: Voice Out Trunks require additional account configuration. Contact DIDWW support to enable. The
REPLACE_CLIandRANDOMIZE_CLIvalues ofOnCliMismatchActionalso require account configuration.
Voice Out Trunks use a polymorphic authenticationMethod (2026-04-16). Three types are supported:
credentials_and_ip-- default method;usernameandpasswordare server-generated and returned in the response.twilio-- requires atwilioAccountSid.ip_only-- read-only; can only be configured by DIDWW staff upon request. Cannot be set via the API.
import com.didww.sdk.resource.enums.DefaultDstAction;
import com.didww.sdk.resource.enums.OnCliMismatchAction;
import com.didww.sdk.resource.enums.VoiceOutCodec;
import com.didww.sdk.resource.authenticationmethod.CredentialsAndIpAuthenticationMethod;
// NOTE: 203.0.113.0/24 is RFC 5737 TEST-NET-3 documentation space.
// Replace with the real CIDR of your SIP infrastructure.
CredentialsAndIpAuthenticationMethod auth = new CredentialsAndIpAuthenticationMethod();
auth.setAllowedSipIps(Collections.singletonList("203.0.113.0/24"));
VoiceOutTrunk voTrunk = new VoiceOutTrunk();
voTrunk.setName("My Outbound Trunk");
voTrunk.setAuthenticationMethod(auth);
voTrunk.setDefaultDstAction(DefaultDstAction.ALLOW_ALL);
voTrunk.setOnCliMismatchAction(OnCliMismatchAction.REJECT_CALL);
voTrunk.setCodecs(Arrays.asList(VoiceOutCodec.OPUS, VoiceOutCodec.PCMA, VoiceOutCodec.TELEPHONE_EVENT));
VoiceOutTrunk created = client.voiceOutTrunks().create(voTrunk).getData();
// created.getAuthenticationMethod().getUsername() -- server-generated
// created.getAuthenticationMethod().getPassword() -- server-generatedcodecs lists the codecs offered on calls from the trunk by name, in priority order: the first has the highest priority. The names are the VoiceOutCodec values, which differ from the Codec values of an inbound SIP trunk. Left out, the trunk offers pcma, pcmu and telephone_event. setIceMode, setRtcpMuxMode and setRtcpFeedbackMode take DISABLED, ACCEPT (the default) or INITIATE.
An SMS trunk delivers inbound messages, accepts outbound ones, or both. Its configuration is one of five classes in com.didww.sdk.resource.smstrunkconfiguration:
| Type | Class | Notes |
|---|---|---|
sms_to_email |
SmsToEmailConfiguration |
Inbound messages are forwarded as email. sendTo, subject and message are required. |
http_in |
HttpInConfiguration |
Inbound messages are sent as an HTTP request to your url. httpMethod is one of the SmsHttpMethod values (GET, POST, PUT); POST and PUT also need bodyType (an SmsBodyType value) and body, which GET refuses. Query parameters, headers and body may use the placeholders {SMS_TEXT}, {SMS_TEXT_BASE64_ENCODED}, {SMS_SRC_ADDR}, {SMS_DST_ADDR} and {SMS_TIME}. |
http_out |
HttpOutConfiguration |
You submit outbound messages over HTTP. authName and authPassword are generated. The submit URL is trunk.getMetaHost() (from the trunk's meta). |
smpp_esme |
SmppEsmeConfiguration |
You bind to DIDWW as an SMPP ESME. serverLocation is required; systemId and password are generated. |
smpp_smsc |
SmppSmscConfiguration |
DIDWW binds to your SMSC with your host, systemId, password and serverLocation. txPort defaults to 2775 and rxPort to 2776. |
SmsTrunkConfiguration#getType() returns the wire type. The read-only getAllowIn() and getAllowOut() tell which directions a trunk handles. serverLocation is SmsServerLocation.NYC or SmsServerLocation.AMS; the sandbox accepts nyc only. A configuration type this SDK does not know is read as a GenericSmsTrunkConfiguration and sent back unchanged; its numbers keep their exact value.
import com.didww.sdk.resource.smstrunkconfiguration.*;
import com.didww.sdk.resource.enums.SmsBodyType;
import com.didww.sdk.resource.enums.SmsHttpMethod;
import com.fasterxml.jackson.databind.node.JsonNodeFactory;
import com.fasterxml.jackson.databind.node.ObjectNode;
HttpInConfiguration httpIn = new HttpInConfiguration();
httpIn.setUrl("https://example.com/sms");
httpIn.setHttpMethod(SmsHttpMethod.POST);
httpIn.setBodyType(SmsBodyType.JSON);
httpIn.setBody("{\"text\":\"{SMS_TEXT}\",\"from\":\"{SMS_SRC_ADDR}\",\"to\":\"{SMS_DST_ADDR}\"}");
SmsTrunk trunk = new SmsTrunk();
trunk.setName("Inbound webhook");
trunk.setConfiguration(httpIn);
SmsTrunk created = client.smsTrunks().create(trunk).getData();
// On update the configuration type must stay the same; attributes left out keep their values.
HttpInConfiguration newUrl = new HttpInConfiguration();
newUrl.setUrl("https://example.com/sms/v2");
SmsTrunk update = new SmsTrunk().withId(created.getId());
update.setConfiguration(newUrl);
client.smsTrunks().update(update);
// Nullable attributes are cleared with a generic configuration of the same type: null is sent as null
ObjectNode attributes = JsonNodeFactory.instance.objectNode();
attributes.put("http_method", "get");
attributes.putNull("body_type");
attributes.putNull("body");
SmsTrunk clear = new SmsTrunk().withId(created.getId());
clear.setConfiguration(new GenericSmsTrunkConfiguration("http_in", attributes));
client.smsTrunks().update(clear);
// List by configuration type, with the group
List<SmsTrunk> trunks = client.smsTrunks().list(QueryParams.builder()
.filter("configuration.type", "http_in,sms_to_email")
.include("sms_trunk_group")
.build()).getData();Changes made inside a configuration object are not tracked: call setConfiguration(...) again to send it in the next update. The configuration is sent as a whole, and a null field is left out, so on update it keeps its stored value. A typed configuration therefore cannot clear a nullable attribute: the queryParameters, headers, bodyType and body of http_in, the callbackUrl and allowedIps of http_out, the systemType and allowedIps of smpp_esme and the systemType of smpp_smsc. Send such a change as a GenericSmsTrunkConfiguration of the same type, as above: its putNull(...) attributes are sent as null.
setOutgoingDids(...) replaces the whole outgoing_dids list of the trunk: list every DID to keep (include outgoing_dids to read the current list), or pass an empty list to clear it. outgoing_dids must stay empty while allow_any_did_as_source is on, so setAllowAnyDidAsSource(true) also clears an outgoing_dids list that was loaded or set before, and a trunk read with outgoing_dids included sends an empty list. incoming_dids and sender_id_verifications can be included but are read-only and never sent back.
The generated credentials of http_out and smpp_esme trunks are read-only and are never sent in a request. The toString() of a configuration masks them, the password of an SmppSmscConfiguration, and the headers of an HttpInConfiguration, which may carry the credentials of your endpoint. A GenericSmsTrunkConfiguration masks every attribute value, since its fields are not known; only the attribute names and explicit nulls are shown. The getters return the real values. To rotate the generated credentials:
SmsTrunkRegenerateCredential regenerate = new SmsTrunkRegenerateCredential();
regenerate.setSmsTrunk(new SmsTrunk().withId(outTrunkId));
client.smsTrunkRegenerateCredentials().create(regenerate);
// The response carries no credentials: read the trunk again
SmsTrunk outTrunk = client.smsTrunks().find(outTrunkId).getData();
SmsTrunkConfiguration configuration = outTrunk.getConfiguration();
if (configuration instanceof HttpOutConfiguration) {
HttpOutConfiguration http = (HttpOutConfiguration) configuration;
// http.getAuthName() and http.getAuthPassword() are the new credentials
} else if (configuration instanceof SmppEsmeConfiguration) {
SmppEsmeConfiguration esme = (SmppEsmeConfiguration) configuration;
// esme.getSystemId() and esme.getPassword() are the new credentials
}An SMS trunk group spreads a DID's inbound messages over its trunks by their priority (the higher value first). http_out trunks cannot join a group. Deleting a group also deletes the trunks in it.
SmsTrunk member = new SmsTrunk().withId("sms-trunk-uuid");
SmsTrunkGroup group = new SmsTrunkGroup();
group.setName("Inbound SMS");
group.setSmsTrunks(Collections.singletonList(member));
SmsTrunkGroup created = client.smsTrunkGroups().create(group).getData();
System.out.println(created.getMetaSmsTrunksCount()); // 1setSmsTrunks(...) replaces the whole membership of the group: list every trunk to keep. Build the list from the included sms_trunks:
SmsTrunkGroup current = client.smsTrunkGroups().find("sms-trunk-group-uuid",
QueryParams.builder().include("sms_trunks").build()).getData();
List<SmsTrunk> members = new ArrayList<>();
if (current.getSmsTrunks() != null) {
members.addAll(current.getSmsTrunks());
}
members.add(new SmsTrunk().withId("another-sms-trunk-uuid"));
SmsTrunkGroup update = new SmsTrunkGroup().withId("sms-trunk-group-uuid");
update.setSmsTrunks(members);
client.smsTrunkGroups().update(update);
// An empty list removes every trunk from the group
SmsTrunkGroup empty = new SmsTrunkGroup().withId("sms-trunk-group-uuid");
empty.setSmsTrunks(Collections.emptyList());
client.smsTrunkGroups().update(empty);A Sender ID verification covers the sender IDs your outbound messages use. It is created and reviewed outside the API: the API lists and reads verifications, and changes only their name and the SMS trunk their messages are routed through. A closed verification cannot be changed. getStatus() is one of the SenderIdVerificationStatus values and getSenderType() one of the SenderType values; isActive(), isClosed() and the other is*() methods test the status. getMetaSetupPrice() and getMetaMonthlyPrice() return the prices of the meta as decimal strings.
List<SenderIdVerification> verifications = client.senderIdVerifications().list(QueryParams.builder()
.filter("status", "active")
.include("sms_trunk")
.build()).getData();
// http_out, smpp_esme or smpp_smsc trunks only
SenderIdVerification route = new SenderIdVerification().withId(verifications.get(0).getId());
route.setSmsTrunk(new SmsTrunk().withId("sms-trunk-uuid"));
client.senderIdVerifications().update(route);
// Outbound messages stop until a trunk is assigned again
SenderIdVerification unroute = new SenderIdVerification().withId(verifications.get(0).getId());
unroute.setSmsTrunk(null);
client.senderIdVerifications().update(unroute);Deleting an SMS trunk leaves the verifications routed through it without a trunk. The other relationships (countries, dids, order, identity, address) can be included but are read-only and never sent back.
import com.didww.sdk.resource.orderitem.*;
// Order by SKU
Order order = new Order();
DidOrderItem item = new DidOrderItem();
item.setSkuId("sku-uuid");
item.setQty(2);
order.setItems(Arrays.asList(item));
Order created = client.orders().create(order).getData();
// Order available DID
AvailableDidOrderItem availableItem = new AvailableDidOrderItem();
availableItem.setAvailableDidId("available-did-uuid");
availableItem.setSkuId("sku-uuid");
// Order reserved DID
ReservationDidOrderItem reservationItem = new ReservationDidOrderItem();
reservationItem.setDidReservationId("reservation-uuid");
reservationItem.setSkuId("sku-uuid");
// Order capacity
CapacityOrderItem capacityItem = new CapacityOrderItem();
capacityItem.setCapacityPoolId("pool-uuid");
capacityItem.setQty(1);DidReservation reservation = new DidReservation();
reservation.setDescription("Reserved for client");
reservation.setAvailableDid(availableDid);
DidReservation created = client.didReservations().create(reservation).getData();
// Delete reservation
client.didReservations().delete(created.getId());SharedCapacityGroup scg = new SharedCapacityGroup();
scg.setName("Shared Group");
scg.setSharedChannelsCount(20);
scg.setCapacityPool(capacityPool);
SharedCapacityGroup created = client.sharedCapacityGroups().create(scg).getData();import com.didww.sdk.resource.enums.IdentityType;
Identity identity = new Identity();
identity.setFirstName("John");
identity.setLastName("Doe");
identity.setPhoneNumber("12125551234");
identity.setIdentityType(IdentityType.PERSONAL);
identity.setCountry(country);
Identity created = client.identities().create(identity).getData();setCompanyWebsite(...) belongs to business identities; a personal identity refuses it, and it is left out of a create request while null.
Address address = new Address();
address.setCityName("New York");
address.setPostalCode("10001");
address.setAddress("123 Main St");
address.setIdentity(identity);
address.setCountry(country);
Address created = client.addresses().create(address).getData();AddressVerification verification = new AddressVerification();
verification.setCallbackUrl("http://example.com/callback");
verification.setCallbackMethod(CallbackMethod.GET);
AddressVerification created = client.addressVerifications().create(verification).getData();import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.LocalDate;
import java.time.ZoneOffset;
import com.didww.sdk.resource.enums.ExportServiceType;
import com.didww.sdk.resource.enums.ExportType;
// Dates are "YYYY-MM-DD HH:MM:SS" in UTC: from is inclusive, to is exclusive and not in the future
LocalDate today = LocalDate.now(ZoneOffset.UTC);
String from = today.minusDays(1) + " 00:00:00";
String to = today + " 00:00:00";
Map<String, Object> cdrFilters = new HashMap<>();
cdrFilters.put("from", from);
cdrFilters.put("to", to);
Export export = new Export();
export.setExportType(ExportType.CDR_IN);
export.setFilters(cdrFilters);
Export created = client.exports().create(export).getData();
// SMS export
Map<String, Object> smsFilters = new HashMap<>();
smsFilters.put("from", from);
smsFilters.put("to", to);
smsFilters.put("service_type", ExportServiceType.A2P); // sent as "a2p"
smsFilters.put("sms_trunk.id", Arrays.asList("sms-trunk-uuid"));
Export smsOut = new Export();
smsOut.setExportType(ExportType.SMS_OUT);
smsOut.setFilters(smsFilters);
Export createdSms = client.exports().create(smsOut).getData();
// The export is pending until its file is generated; read it again later
Export completed = client.exports().find(createdSms.getId()).getData();
if (completed.isCompleted()) {
client.downloadExport(completed.getUrl(), Path.of("/tmp/export.csv.gz")); // gzipped CSV, as served
client.downloadAndDecompressExport(completed.getUrl(), Path.of("/tmp/export.csv")); // plain CSV
try (OutputStream out = Files.newOutputStream(Path.of("/tmp/copy.csv.gz"))) {
client.downloadExport(completed.getUrl(), out); // any OutputStream
}
}The export downloads send the token only to the origin (scheme, host and port) of the JSON:API base URL or of the environment, so export URLs, which the API builds on the environment's host, are still downloaded when baseUrl(...) points elsewhere; that request goes directly to the environment's host. A URL on any other origin throws a DidwwClientException and nothing is sent. Only a 200 answer is written, as it arrives, without holding the file in memory; redirects are not followed, and any other status, a 3xx or a 204 included, throws a DidwwApiException (see Error Handling). The Path overloads write to a temporary file .didww-<16 hex digits>.tmp in the directory of the destination, which replaces it only once the whole file has arrived (or has been decompressed); the OutputStream overloads write into your stream, which is not closed and may hold part of the file after a failure.
from and to are required for every export type (cdr_in, cdr_out, sms_in, sms_out). The other filter keys depend on the type:
cdr_in:did_number,source_number,source_number_out,source_country_iso;cdr_out:voice_out_trunk.id,source,cli,destination;sms_inandsms_out:source_address_eq,source_address_cont,destination_address_eq,destination_address_cont,status,sms_id,sms_trunk.id(a string or a list of strings);sms_inonly:trunk_type, one or more of theExportTrunkTypevalues;sms_outonly:service_type, one of theExportServiceTypevalues, andsender_id_verification.id(a string or a list of strings).
Filter values are lowercase, and an enum constant of the SDK is sent as its wire value: service_type is a2p or p2p, trunk_type is one or more of smpp_smsc, smpp_esme, sms_to_email and http_in, and status is success, failed or queued for sms_in, and routing_error, in_progress, queued, failed or success for sms_out.
The Javadoc of Export#setFilters lists the keys of every type.
// List emergency requirements
List<EmergencyRequirement> emergReqs = client.emergencyRequirements().list().getData();
// Create emergency verification
EmergencyVerification emergVerification = new EmergencyVerification();
emergVerification.setCallbackUrl("https://example.com/callback");
emergVerification.setCallbackMethod("post");
emergVerification.setAddress(address);
emergVerification.setDids(Arrays.asList(did));
EmergencyVerification created = client.emergencyVerifications().create(emergVerification).getData();
// List emergency calling services
List<EmergencyCallingService> emergServices = client.emergencyCallingServices().list().getData();// List DID history
List<DidHistory> history = client.didHistory().list().getData();
for (DidHistory entry : history) {
System.out.println(entry.getAction() + " " + entry.getCreatedAt());
}Prices are served by three services outside the JSON:API (hosts in Environments). Each price list has a price file and a lookup:
| Accessor | Service | Price file | Lookup | Lookup rows |
|---|---|---|---|---|
client.voiceInPrices() |
Voice IN | prices.csv.gz |
lookup/prices |
VoiceInPrice |
client.voiceOutPrices() |
Voice OUT | prices.csv.gz |
lookup/prices |
VoiceOutPrice |
client.smsOutA2pPrices() |
SMS | sms_out/a2p/prices.csv.gz |
sms_out/a2p/lookup/prices |
SmsOutPrice |
client.smsOutP2pPrices() |
SMS | sms_out/p2p/prices.csv.gz |
sms_out/p2p/lookup/prices |
SmsOutPrice |
client.smsOutOtpPrices() |
SMS | sms_out/otp/prices.csv.gz |
sms_out/otp/lookup/prices |
SmsOutPrice |
client.smsInPrices() |
SMS | sms_in/prices.csv.gz |
sms_in/lookup/prices |
SmsInPrice |
Each accessor returns a PricesService<T>; it, the row classes and PriceFileReader are in package com.didww.sdk.prices. The account needs a price plan of that service: without one, every call throws PricesErrorKind.PRICE_PLAN_NOT_ASSIGNED.
import com.didww.sdk.prices.*;
PriceLookup<VoiceInPrice> result = client.voiceInPrices().lookup(Map.of(
"number", "18005550123",
"src_country_iso", "US"));
System.out.println(result.getTotalRecords());
for (VoiceInPrice price : result.getRows()) {
if (price.getRate() != null) {
System.out.println(price.getDestination() + " " + price.getSourceType() + ": " + price.getRate() + " USD/min");
}
}
PriceLookup<VoiceOutPrice> voiceOut = client.voiceOutPrices().lookup(Map.of("number", "493012345678"));
System.out.println(voiceOut.getRows().get(0).getCategory()); // VoiceOutPriceCategory
PriceLookup<SmsOutPrice> a2p = client.smsOutA2pPrices().lookup(Map.of("dst_number", "4915123456789"));
PriceLookup<SmsInPrice> smsIn = client.smsInPrices().lookup(Map.of("dst_country_iso", "US"));| Service | Filters |
|---|---|
| Voice IN | number (required), src_country_iso |
| Voice OUT | number (required); no other filter |
| SMS OUT and SMS IN | dst_number, dst_country_iso; at least one |
A missing or unknown filter throws an IllegalArgumentException before any request; null and blank values are dropped (Map.of refuses null, so use a HashMap for optional values). The server checks the value formats and answers a bad value with 400 (PricesErrorKind.BAD_REQUEST). A lookup is not retried, except once with a new token after a 401.
lookup returns a PriceLookup<T> with getRows() and getTotalRecords(). It always holds at least one row: no match throws PricesErrorKind.PRICE_NOT_FOUND, never an empty result. In the rows, prices and fees are BigDecimal in USD, VAT excluded, with the scale of the answer kept (compare them with compareTo, not equals); they are null when the row rejects the calls or messages (see getRejectCalls() and getRejectSms()). Intervals and increments are Integer, SmsOutPrice#getMcc() and getMnc() are Integer, VoiceOutPrice#getEffectiveAt() is an OffsetDateTime and VoiceOutPrice#getCategory() is one of the VoiceOutPriceCategory values (INTERNATIONAL, ORIGIN_BASED, LOCAL), or null for a category this SDK does not know.
The ID of an SMS OUT or SMS IN lookup row is derived from its content: it changes when the row or its price changes, so do not use it to track a destination over time. A Voice OUT ID stays the same when a re-import changes only the price. A Voice IN ID names the answering row of the plan.
The files are gzipped CSV with a header row. The SDK writes them exactly as served and never decompresses them.
import com.didww.sdk.prices.*;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.stream.Stream;
PricesService<VoiceInPrice> prices = client.voiceInPrices();
Path path = Path.of("/var/data/voice_in_prices.csv.gz");
// Download unless the copy at the path is current
PriceFile file = prices.fetch(path);
System.out.println(file.isNotModified()
? "answered 304, the file was kept"
: "downloaded " + file.getBytesWritten() + " bytes, last modified " + file.getLastModified());
// Read the rows, keyed by the header line
try (Stream<Map<String, String>> rows = PriceFileReader.rows(path)) {
rows.limit(5).forEach(row -> System.out.println(row.get("Destination") + ": " + row.get("Rate")));
}
// Lower-level calls
PriceFile status = prices.head(file.getLastModified()); // sent as If-Modified-Since; null sends none
// status.isNotModified(), status.getContentLength() (null when unknown),
// status.getFileName() (from Content-Disposition, e.g. "voice_in_prices.csv.gz")
file = prices.downloadToFile(path);
try (OutputStream out = Files.newOutputStream(Path.of("/tmp/voice_in_prices.csv.gz"))) {
file = prices.download(out); // any OutputStream; download(out, ifModifiedSince) sends If-Modified-Since
}fetch(path)sends the modification time of the file atpathasIf-Modified-Since, when the file is there; an unchanged price file is answered 304 and the file is kept. A file written bydownloadToFileorfetchgets theLast-Modifiedof the response as its modification time, so the date matches the copy on disk.fetchtrusts the modification time of any file atpath: a file copied or changed by other means can be answered 304 and kept, so replace such a file withdownloadToFile.downloadToFileandfetchstream the body into a temporary file.didww-<16 hex digits>.tmpin the directory ofpath, unique to the call, which gets the permissions of a new file (the umask on POSIX systems), is flushed to the disk and replacespathatomically only on a complete 200. A 304 or an error leaves an existing file untouched, the temporary file is always removed, and concurrent downloads to one path do not mix their bytes. A directory that does not exist throws anUncheckedIOExceptionwithout a request. On Windows the replacement fails whilepathis open, for example by aPriceFileReaderstream that has not been closed.download(destination)anddownload(destination, ifModifiedSince)write the body intodestinationonly on a 200, as it arrives, so after a transfer errordestinationmay hold part of it. The stream is not closed. AnIOExceptionofdestinationis thrown as anUncheckedIOExceptionwith it as the cause.- A body shorter than its
Content-LengththrowsPricesErrorKind.CONNECTION_ERROR; it never replaces a file. headand the downloads return aPriceFile:getStatusCode(),getLastModified()(nullwhen absent),getContentLength(),getFileName()(as sent: check it before using it as a path),getBytesWritten()andisNotModified().PriceFileReader.rows(path)andPriceFileReader.rows(inputStream)gunzip a downloaded file and return a lazyStreamof rows, each aMap<String, String>keyed by the header line, as served, in header order. A UTF-8 byte order mark and empty lines are skipped. Input that is not gzip (ZipException), gzip data cut short, an empty input included (EOFException), or a row whose field count differs from the header (anIOExceptionwhose message starts withPrice file:) throws anUncheckedIOExceptionwith that cause while the stream is consumed, so rows before the error have already been passed on. Data after the end of the gzip data is ignored unless it starts another gzip member, so a later member that is cut short or corrupt raises the error too. Close the stream:rows(path)opens the file,rows(inputStream)leaves your stream open.- The columns, prices in USD with VAT excluded. Voice IN:
Country,Src country name,Source type,Destination,Rate,Connection fee,Initial interval,Next intervalandReject calls. Voice OUT:Category,Country,Network,Prefix(one prefix per row),Rate,Connection fee,Initial increment,Recurring increment,Reject calls,Next rate,Next connection fee,Next initial increment,Next recurring increment,Effective dateandComment. SMS OUT:Source prefix,Destination prefix,Country,MCC,MCC name,MNC,MNC name,Reject SMS(trueorfalse) andPrice. SMS IN:Source prefix,Source number length min,Source number length max,Destination prefix,Destination number length min,Destination number length max,CountryandPrice. - Only
Last-ModifiedandIf-Modified-Sinceare used, in whole seconds. The service sends noETag, and the SDK never sendsIf-None-Match, which would make the service ignoreIf-Modified-Since. - A 503 on a price file is retried up to 2 times when its
Retry-Afteris 60 seconds or less, after waiting that long (at least 1 s) plus a small random delay so that clients do not retry in step. Otherwise it throwsPricesErrorKind.SERVICE_UNAVAILABLEwithgetRetryAfter(). Lookups and other statuses, 429 included, are not retried. - A 404
price_not_foundthrowsPRICE_NOT_FOUND; any other 404,price_plan_not_assignedincluded, and any 404 onhead, which has no body, throwsPRICE_PLAN_NOT_ASSIGNED.DidwwPricesException#getCode()holds the code of the answer, orprice_plan_not_assignedfor a 404 without one. - Redirects are not followed. A status without its own kind in Error Handling, such as a 3xx, a 202 or a 204, throws
PricesErrorKind.UNEXPECTED_STATUS. An error is never turned into an empty file or an empty result.
See
FILTERS.mdfor the list offilter[KEY]keys accepted by every list endpoint at API version2026-11-19.
import com.didww.sdk.http.QueryParams;
QueryParams params = QueryParams.builder()
.filter("country.id", "uuid")
.filter("name", "Arizona")
.include("country")
.sort("name")
.page(1, 25)
.build();
List<Region> regions = client.regions().list(params).getData();The SDK tracks which fields have been modified and sends only those fields in PATCH requests. This avoids overwriting server-side values that your code hasn't touched.
When you fetch a resource and modify it, only the changed fields are sent:
Did did = client.dids().find("uuid").getData();
did.setDescription("Updated description");
// PATCH payload includes only "description", not all attributes
client.dids().update(did);A writable relationship loaded through an include is sent back on update as it was read. For a to-many relationship, such as the outgoing_dids of an SMS trunk or the sms_trunks of an SMS trunk group, that replaces the stored list with the list you read, so when you change other fields of such a resource, build the update from withId(id) (below) instead.
Use withId(id) to create a lightweight resource for PATCH without fetching first:
VoiceInTrunk trunk = new VoiceInTrunk().withId("trunk-uuid");
trunk.setName("New name");
// PATCH payload includes only "name"
client.voiceInTrunks().update(trunk);Calling a setter with null marks the field as dirty and includes an explicit null in the payload, which clears the server-side value:
Did did = new Did().withId("uuid");
did.setDescription(null);
// PATCH payload includes "description": null
client.dids().update(did);Calling a relationship setter with null sends "data": null for to-one or "data": [] for to-many relationships:
Did did = new Did().withId("uuid");
did.setVoiceInTrunk(null);
// PATCH payload includes: "relationships": { "voice_in_trunk": { "data": null } }
client.dids().update(did);Dirty tracking is automatically enabled on included (sideloaded) resources, so you can fetch with includes and update a related resource directly:
Did did = client.dids().find("uuid", QueryParams.builder().include("voice_in_trunk").build()).getData();
VoiceInTrunk trunk = did.getVoiceInTrunk();
trunk.setDescription("Updated via include");
client.voiceInTrunks().update(trunk);The SDK provides an Encrypt utility for encrypting files before upload, using RSA-OAEP + AES-256-CBC (matching DIDWW's encryption requirements).
import com.didww.sdk.Encrypt;
// Instance-based: fetches public keys from the API
Encrypt enc = new Encrypt(client);
String fingerprint = enc.getFingerprint();
byte[] encrypted = enc.encrypt(fileBytes);
// Static: provide your own public keys
byte[] encryptedWithKeys = Encrypt.encryptWithKeys(fileBytes, publicKeyPems);
String fingerprintOfKeys = Encrypt.calculateFingerprint(publicKeyPems);Upload encrypted file:
String encryptedFileId = client.uploadEncryptedFile(
encrypted, // encrypted bytes
"document.pdf.enc", // uploaded file name
fingerprint, // Encrypt#getFingerprint()
"document.pdf" // description
);The upload goes through the configured HTTP client (proxy, TLS, interceptors) with a bearer token.
Validate incoming webhook callbacks from DIDWW using HMAC-SHA1 signature verification.
Initialize the validator with the callback secret that is enabled in the DIDWW User Panel (APIs → DIDWW API 3 → Callback Secrets). DIDWW signs every callback with it and sends callbacks only while a callback secret is enabled.
import com.didww.sdk.callback.RequestValidator;
RequestValidator validator = new RequestValidator("YOUR_CALLBACK_SECRET");
// In your webhook handler:
boolean valid = validator.validate(
requestUrl, // full original URL
payloadMap, // Map<String, String> of payload key-value pairs
signature // value of X-DIDWW-Signature header
);The signature header name is available as RequestValidator.HEADER_NAME.
The SDK's own exceptions derive from DidwwException, an unchecked exception in package com.didww.sdk.exception. Their messages and causes never contain the API key or a token, and the toString() of the credentials, tokens, token stores and SMS trunk configurations never shows them either.
import com.didww.sdk.exception.*;
try {
client.voiceInTrunks().find("nonexistent");
} catch (DidwwApiException e) {
System.out.println("HTTP Status: " + e.getHttpStatus());
for (DidwwApiException.ApiError error : e.getErrors()) {
System.out.println("Error: " + error.getDetail());
}
} catch (DidwwClientException e) {
System.out.println("Client error: " + e.getMessage());
}| Exception | Thrown for |
|---|---|
DidwwApiException |
An error status of the JSON:API repositories, the export downloads and uploadEncryptedFile, with getHttpStatus(), getErrors() and getRetryAfter(). |
DidwwClientException |
A failure on the client side: a JSON:API call or upload that fails in transport (the IOException is the cause) or whose resource cannot be serialized, an upload or price lookup answer that cannot be parsed, a refused export URL, an export download that breaks off or cannot be decompressed. |
DidwwAuthException |
The token service, from any call that needs a new token. |
DidwwPricesException |
The prices services. |
DidwwApiException also reports the authentication failures of the API: a 401 still answered after the token was replaced once (getHttpStatus() 401), and a 403 such as insufficient_scope for a write with a READ token, which is never retried. The export downloads do not follow redirects: any status other than 200, such as a 3xx or a 204, throws a DidwwApiException.
A 429 (too_many_requests) means the request budget of the account for the current window is spent. The repositories, the export downloads and uploadEncryptedFile throw it as a DidwwApiException with getHttpStatus() 429 and getRetryAfter(), the Retry-After of the response as a Duration (null when it is missing or not a number of seconds; any other error status carries it too). The SDK does not retry it, as a write may not be safe to send twice: wait getRetryAfter() before sending the request again.
try {
client.dids().list();
} catch (DidwwApiException e) {
if (e.getHttpStatus() != 429) {
throw e;
}
System.out.println("API rate limit, retry after " + e.getRetryAfter());
}The token service and prices errors carry a kind, which getKind() tells apart:
try {
client.smsOutA2pPrices().lookup(Map.of("dst_number", "4915123456789"));
} catch (DidwwAuthException e) {
if (e.getKind() == AuthErrorKind.RATE_LIMITED) {
// Wait getRetryAfter() and try again; repeat while the kind is RATE_LIMITED.
System.out.println("Token service rate limit, retry after " + e.getRetryAfter());
} else if (e.getKind() == AuthErrorKind.INVALID_CLIENT) {
System.out.println("API key refused: " + e.getMessage());
} else {
throw e;
}
} catch (DidwwPricesException e) {
switch (e.getKind()) {
case PRICE_NOT_FOUND:
System.out.println("No price for this number");
break;
case TOO_MANY_REQUESTS:
System.out.println("Prices rate limit, retry after " + e.getRetryAfter());
break;
default:
throw e;
}
} catch (DidwwException e) {
System.out.println("Error: " + e.getMessage());
}Token service (DidwwAuthException, with getKind(), getHttpStatus(), getError(), getErrorDescription() and getRetryAfter()):
AuthErrorKind |
Thrown when |
|---|---|
INVALID_CLIENT |
401: the token service refused the API key. Not retried. |
INVALID_REQUEST |
400, e.g. invalid_request or invalid_scope. |
RATE_LIMITED |
429. getRetryAfter() is the server's wait. Further mints fail without a request until that time plus a small random delay has passed; such a refusal reports the time still left in getRetryAfter(), so retry in a loop rather than once. |
SERVER_ERROR |
5xx on the last of the 4 attempts. |
CONNECTION_ERROR |
Connection failure or timeout on the last attempt, a TLS failure (not retried), or an interrupted thread (its interrupt flag stays set). getHttpStatus() is null. |
INVALID_GRANT |
The token is empty, not a valid header value, or does not cover the requested audience. |
UNEXPECTED_STATUS |
Any other status, such as a redirect. |
Prices (DidwwPricesException, with getKind(), getHttpStatus(), getCode(), getErrors() and getRetryAfter()):
PricesErrorKind |
Status |
|---|---|
BAD_REQUEST |
400, e.g. a filter value of the wrong format |
NOT_AUTHORIZED |
401 after the token was replaced once |
ACCESS_DENIED |
403 |
PRICE_PLAN_NOT_ASSIGNED |
404 price_plan_not_assigned, and any other 404 except price_not_found, including any 404 on head, which has no body |
PRICE_NOT_FOUND |
404 price_not_found: no price matches the lookup |
NOT_ACCEPTABLE |
406 |
TOO_MANY_REQUESTS |
429, with getRetryAfter() when the service sends it in seconds. Not retried. |
SERVICE_UNAVAILABLE |
503, with getRetryAfter(). Retried on price files only, see Price files. |
UNEXPECTED_STATUS |
Any other status, such as a redirect, a 202, a 204 or a 304 to a lookup |
CONNECTION_ERROR |
Connection failure, timeout, TLS failure, a response body that breaks off or is shorter than its Content-Length, or an interrupted thread (its interrupt flag stays set). Not retried. |
The prices services can also throw a DidwwAuthException, lookup an IllegalArgumentException for invalid filters and a DidwwClientException when a 200 answer is not a JSON:API document it can parse or holds no prices. A destination OutputStream or file that cannot be written, and the file system errors of downloadToFile and fetch (temporary file, times, move), throw an UncheckedIOException with the IOException as the cause. Outside DidwwException, the SDK also throws IllegalArgumentException from build() and NullPointerException for a required argument that is null.
| Type | Class |
|---|---|
| SIP | SipConfiguration |
| PSTN | PstnConfiguration |
For the SMS trunk configuration types, see SMS Trunks.
| Type | Class |
|---|---|
| DID | DidOrderItem |
| Available DID | AvailableDidOrderItem |
| Reservation DID | ReservationDidOrderItem |
| Capacity | CapacityOrderItem |
| Generic | GenericOrderItem |
| Resource | Repository | Operations |
|---|---|---|
| Country | client.countries() |
list, find |
| Region | client.regions() |
list, find |
| City | client.cities() |
list, find |
| Area | client.areas() |
list, find |
| NanpaPrefix | client.nanpaPrefixes() |
list, find |
| DidGroup | client.didGroups() |
list, find |
| AvailableDid | client.availableDids() |
list, find |
| ProofType | client.proofTypes() |
list, find |
| PublicKey | client.publicKeys() |
list, find |
| AddressRequirement | client.addressRequirements() |
list, find |
| SupportingDocumentTemplate | client.supportingDocumentTemplates() |
list, find |
| Balance | client.balance() |
find |
| Did | client.dids() |
list, find, update, delete |
| VoiceInTrunk | client.voiceInTrunks() |
list, find, create, update, delete |
| VoiceInTrunkGroup | client.voiceInTrunkGroups() |
list, find, create, update, delete |
| VoiceOutTrunk | client.voiceOutTrunks() |
list, find, create, update, delete |
| VoiceOutTrunkRegenerateCredential | client.voiceOutTrunkRegenerateCredentials() |
create |
| SmsTrunk | client.smsTrunks() |
list, find, create, update, delete |
| SmsTrunkGroup | client.smsTrunkGroups() |
list, find, create, update, delete |
| SmsTrunkRegenerateCredential | client.smsTrunkRegenerateCredentials() |
create |
| SenderIdVerification | client.senderIdVerifications() |
list, find, update |
| DidReservation | client.didReservations() |
list, find, create, delete |
| CapacityPool | client.capacityPools() |
list, find, update |
| SharedCapacityGroup | client.sharedCapacityGroups() |
list, find, create, update, delete |
| Order | client.orders() |
list, find, create, delete |
| Export | client.exports() |
list, find, create, update |
| Address | client.addresses() |
list, find, create, update, delete |
| AddressVerification | client.addressVerifications() |
list, find, create, update |
| Identity | client.identities() |
list, find, create, update, delete |
| EncryptedFile | client.encryptedFiles() |
list, find, delete |
| PermanentSupportingDocument | client.permanentSupportingDocuments() |
create |
| Proof | client.proofs() |
create |
| AddressRequirementValidation | client.addressRequirementValidations() |
create |
| DidHistory | client.didHistory() |
list |
| EmergencyRequirement | client.emergencyRequirements() |
list, find |
| EmergencyRequirementValidation | client.emergencyRequirementValidations() |
create |
| EmergencyCallingService | client.emergencyCallingServices() |
list, find, create, update, delete |
| EmergencyVerification | client.emergencyVerifications() |
list, find, create, update |
| StockKeepingUnit | include on didGroups |
— |
| QtyBasedPricing | include on capacityPools |
— |
| VoiceInPrice | client.voiceInPrices() |
lookup, head, download, downloadToFile, fetch |
| VoiceOutPrice | client.voiceOutPrices() |
lookup, head, download, downloadToFile, fetch |
| SmsOutPrice | client.smsOutA2pPrices(), client.smsOutP2pPrices(), client.smsOutOtpPrices() |
lookup, head, download, downloadToFile, fetch |
| SmsInPrice | client.smsInPrices() |
lookup, head, download, downloadToFile, fetch |
Note:
StockKeepingUnitandQtyBasedPricinghave no standalone API endpoints. Access them viaincludeondidGroupsandcapacityPoolsrespectively. The price rows are served by the prices services outside the JSON:API, see Prices.
The SDK distinguishes between date-only and datetime fields:
- Datetime fields — deserialized as
OffsetDateTime:getCreatedAt()— present on most resourcesgetUpdatedAt()—SmsTrunk,SmsTrunkGroupgetExpiresAt()—Did,DidReservation,Proof,EncryptedFile(nullable)getActivatedAt()—EmergencyCallingService,SenderIdVerification(nullable)getCanceledAt()—EmergencyCallingService(nullable)getClosedAt()—SenderIdVerification(nullable)getEffectiveAt()—VoiceOutPriceprice lookup rows (nullable)
- Date-only fields — deserialized as
LocalDate:Identity.getBirthDate()
- Date-only fields kept as strings — remain as
String:CapacityPool.getRenewDate(),EmergencyCallingService.getRenewDate()—"YYYY-MM-DD"(nullable)SenderIdVerification.getRenewDate()—"YYYY-MM-DD",nullonce the verification is closedDidOrderItem.getBilledFrom(),DidOrderItem.getBilledTo()
- String fields (not numeric):
EmergencyRequirement.getEstimateSetupTime()— e.g."7-14 days","1"EmergencyRequirement.getRequirementRestrictionMessage()— nullable
Important changes from previous API versions:
getExpireAt()renamed togetExpiresAt()onDidReservationandEncryptedFilegetRenewDate()returns a date-only string, NOT anOffsetDateTimegetEstimateSetupTime()returns aString, NOT an integer
Did did = client.dids().find("uuid").getData();
System.out.println(did.getCreatedAt()); // 2024-01-15T10:00:00Z (OffsetDateTime)
System.out.println(did.getExpiresAt()); // null or 2025-01-15T10:00:00Z
Identity identity = client.identities().find("uuid").getData();
System.out.println(identity.getBirthDate()); // 1990-05-20 (LocalDate)The SDK provides enum classes in com.didww.sdk.resource.enums:
CallbackMethod, IdentityType, OrderStatus, ExportType, ExportStatus, CliFormat,
OnCliMismatchAction*, MediaEncryptionMode, DefaultDstAction, VoiceOutTrunkStatus,
EmergencyCallingServiceStatus, EmergencyVerificationStatus, DiversionRelayPolicy, TransportProtocol,
RxDtmfFormat, TxDtmfFormat, SstRefreshMethod, ReroutingDisconnectCode, Feature, AreaLevel,
AddressVerificationStatus, StirShakenMode, NumberType, Pop, SenderIdVerificationStatus, SenderType,
SmsHttpMethod, SmsBodyType, SmsServerLocation, ExportTrunkType, ExportServiceType
* REPLACE_CLI and RANDOMIZE_CLI require account configuration.
Codec holds the codecs of an inbound SIP trunk (SipConfiguration#setCodecs) and VoiceOutCodec those of a Voice OUT trunk (VoiceOutTrunk#setCodecs); the two lists differ. IceMode, RtcpMuxMode and RtcpFeedbackMode serve both.
These five, in the same package, are classes rather than enums, as the API adds codecs and modes over time. Each known value is a constant, such as Codec.PCMU, and getValue() is its API name. A value this version of the SDK does not know is kept as read, such as Codec.of("evs"), and sent back unchanged on update. Reading a known value returns its constant, so == and equals both work; there is no values(), name() or switch over them.
ExportType includes SMS_IN and SMS_OUT; ExportTrunkType and ExportServiceType are the values of the trunk_type and service_type filters of SMS exports. VoiceOutPriceCategory is in com.didww.sdk.prices, and DidwwScope in com.didww.sdk.auth. For the enums, a value the API sends that this SDK does not know reads as null.
The wire value of a string enum is declared with Jackson's @JsonProperty only: name() is not the wire form (NumberType.TOLL_FREE.name() is TOLL_FREE, the API value is toll_free). Write the wire value in filters, such as filter("number_type", "toll_free") or filter("status", "changes_required").
5.0.0 targets API 2026-11-19 only. To stay on API 2026-04-16, keep 4.x (for example 4.1.4, branch release-4.1).
Most code keeps working: DidwwClient.builder().credentials(new DidwwCredentials(apiKey, environment)).build() is unchanged, and the SDK mints the access tokens itself. The breaking changes:
- Authentication. Every request carries a bearer token minted from the API key (see Authentication). The
Api-Keyheader is sent only to the token service, so outgoing traffic must reachauth.didww.com(auth-sandbox.didww.comin the sandbox). The token service can throw aDidwwAuthExceptionfrom any call. The publiccom.didww.sdk.http.ApiKeyInterceptoris removed. - API version.
X-DIDWW-API-Versionis no longer sent: the version is requested in the token. The default is2026-11-19, and an earlier version makesbuild()throw anIllegalArgumentException. - Validation.
build()throws anIllegalArgumentExceptionfor an invalid API key, API version or service URL (see Configuration), which 4.x accepted. - Removed resources.
client.pops(),client.didGroupTypes(),com.didww.sdk.resource.Popandcom.didww.sdk.resource.DidGroupTypeare removed, with thedid_group_typerelationship and include.DidGroup,AddressRequirement,EmergencyRequirementandEmergencyCallingServicehavegetNumberType()instead ofgetDidGroupType(); filter withnumber_typeinstead ofdid_group_type.id, and withdid_group.number_typeon available DIDs. - Codecs.
SipConfiguration#setCodecIdsandgetCodecIds(codec_ids) are replaced bysetCodecsandgetCodecs(codecs), the codec names in priority order.Codecis no longer an enum: it is a class with a constant per codec, sent by name (PCMUaspcmu),getValue()returns that name instead of the former integer id, andvalues(),valueOf,name(),switchandEnumSetno longer apply (see Enums).AMRandAMR_WBare new. Voice OUT trunks have their own codec list,VoiceOutCodec. Both trunk kinds gainiceMode,rtcpMuxModeandrtcpFeedbackMode. - Requirements and proof types. The mandatory fields of
AddressRequirementandEmergencyRequirementare field names as the API spells them (such asbirth_dateortax_id, not labels such asBirth Date) and nevernull.ProofType#getEntityType()is lowercase:address,businessorpersonal. - Point of presence.
VoiceInTrunk#setPoptakes the enumcom.didww.sdk.resource.enums.Pop(for examplePop.FRA), andgetPop()returns it;popis an attribute, no longer a relationship, and cannot be included. - Numbers in untyped maps. Decimal numbers that the SDK reads into a
Map<String, Object>or a Jackson node, such asApiResponse#getMeta(),GenericAuthenticationMethod#getAttributes()(an unknown Voice OUT trunk authentication method), thesourceandmetaof the errors of aDidwwApiException,Export#getFilters()and the maps ofHttpInConfiguration, are nowBigDecimalwith their exact value, notDouble. Integers are unchanged. - HTTP defaults. 4.x used OkHttp's defaults: 10 s timeouts and redirects followed. 5.x opens TCP connections within 10 s, waits up to 60 s for a proxy tunnel, the TLS handshake, the response headers and between two reads or writes, follows no redirects, sends and stores no cookies and ignores the
Authenticatorand cache of your builder (see HTTP client). The timeouts of your ownhttpClientBuilderare kept as before. - Export download and file upload.
uploadEncryptedFilenow goes through your configured HTTP client (proxy, TLS, interceptors) with the bearer token; 4.x used a separate default client. An error status ofuploadEncryptedFilenow throws aDidwwApiExceptionwith the status, the parsed errors andgetRetryAfter(), where 4.x threw aDidwwClientException.downloadExportanddownloadAndDecompressExportdownload only from the API origin or the environment origin (aDidwwClientExceptionotherwise, without a request), succeed only on a 200 (any other status, a 2xx included, now throws aDidwwApiExceptionwith the status and the parsed errors, where 4.x threw aDidwwClientException), follow no redirects, stream the file instead of reading it into memory, and replace the destination file only once it is complete; a destination file that cannot be written (missing directory, permissions, full disk) now throws anUncheckedIOExceptionwith theIOExceptionas its cause, not aDidwwClientException; new overloads write to anOutputStream. - Exceptions.
DidwwApiExceptionandDidwwClientExceptionnow extend the abstractDidwwException(still aRuntimeException), the base of the newDidwwAuthExceptionandDidwwPricesException.
New in 5.0.0: DidwwApiException#getRetryAfter() for a 429 of the API (see Error Handling), codecs and ICE, RTCP multiplexing and RTCP feedback modes of Voice Out trunks, SMS trunks, SMS trunk groups, Sender ID verifications, DID SMS routing, sms_in and sms_out exports, prices, DidGroup#getIsDemo(), Identity company website, and the apiVersion, scope, tokenStore, logger and service URL methods of the builder.
# Run the tests
./gradlew test
# Build the Javadoc
./gradlew javadoc
# Compile the examples
./gradlew compileExamplesJava
# Run an example (see examples/README.md)
DIDWW_API_KEY=your_api_key ./gradlew runExample -PexampleClass=com.didww.examples.BalanceExample- Update
versioninbuild.gradle.ktsto the new version (e.g."5.0.0") - Commit and push to
main(5.x), or torelease-4.1for a 4.x patch release - Create and push a git tag matching the version (no
vprefix):git tag 5.0.0 git push origin 5.0.0
- JitPack will automatically build and publish the new version from the tag
Bug reports and pull requests are welcome on GitHub at https://github.com/didww/didww-api-3-java-sdk
The package is available as open source under the terms of the MIT License.