From 013b0c647a7e84c986258b96442eee7c2e093dc6 Mon Sep 17 00:00:00 2001
From: Igor Fedoronchuk <fedoronchuk@gmail.com>
Date: Fri, 8 May 2026 14:27:42 +0200
Subject: [PATCH] docs: add FILTERS.md server-side filter reference
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document every `filter[KEY]` query parameter accepted by each list endpoint
at API version 2026-04-16. The SDK passes filters through as an untyped
string map, so users currently have to read Postman or trial-and-error to
discover valid keys; this file makes the canonical list discoverable in the
SDK repo itself, and is linked from the README near the existing filter
usage examples.

Every entry was verified live against the DIDWW API at version 2026-04-16.

Documentation-only — no code changes, no behavior change.
---
 FILTERS.md | 258 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md  |   2 +
 2 files changed, 260 insertions(+)
 create mode 100644 FILTERS.md

diff --git a/FILTERS.md b/FILTERS.md
new file mode 100644
index 00000000..0865a85e
--- /dev/null
+++ b/FILTERS.md
@@ -0,0 +1,258 @@
+# DIDWW 2026-04-16 — Server-side filter reference
+
+This is the canonical list of `filter[KEY]` query parameters accepted by each list endpoint of the DIDWW API at version `2026-04-16` — the default API version targeted by this SDK.
+
+The SDK passes filters through as untyped string→string maps (e.g. `QueryParams.builder().filter("country.id", uuid).build()`), so this document is the authoritative source for which keys actually do something on the server.
+
+Every key listed here was verified live against the DIDWW API at version `2026-04-16`.
+
+Pass values URL-encoded as strings. Where the server accepts arrays, comma-separate the values.
+
+## AddressRequirement — `GET /v3/address_requirements`
+
+- `filter[country.id]`
+- `filter[did_group_type.id]`
+
+## Address — `GET /v3/addresses`
+
+- `filter[address]`
+- `filter[address_contains]`
+- `filter[area.id]`
+- `filter[city.id]`
+- `filter[city_name]`
+- `filter[city_name_contains]`
+- `filter[country.id]`
+- `filter[description]`
+- `filter[description_contains]`
+- `filter[external_reference_id]`
+- `filter[identity.external_reference_id]`
+- `filter[identity.id]`
+- `filter[postal_code]`
+- `filter[postal_code_contains]`
+
+## AddressVerification — `GET /v3/address_verifications`
+
+- `filter[address.id]`
+- `filter[address.identity.id]`
+- `filter[external_reference_id]`
+- `filter[reference]`
+- `filter[reference_in]`
+- `filter[status]`
+
+## Area — `GET /v3/areas`
+
+- `filter[country.id]`
+- `filter[name]`
+
+## AvailableDid — `GET /v3/available_dids`
+
+- `filter[city.id]`
+- `filter[country.id]`
+- `filter[did_group.features]`
+- `filter[did_group.id]`
+- `filter[did_group.needs_registration]`
+- `filter[did_group_type.id]`
+- `filter[nanpa_prefix.id]`
+- `filter[number_contains]`
+- `filter[region.id]`
+
+## CapacityPool — `GET /v3/capacity_pools`
+
+- `filter[country.id]`
+- `filter[has_unassigned_channels]`
+- `filter[name]`
+
+## City — `GET /v3/cities`
+
+- `filter[area.id]`
+- `filter[country.id]`
+- `filter[is_available]`
+- `filter[name]`
+- `filter[region.id]`
+
+## Country — `GET /v3/countries`
+
+- `filter[is_available]`
+- `filter[iso]`
+- `filter[name]`
+- `filter[prefix]`
+
+## DidGroup — `GET /v3/did_groups`
+
+- `filter[allow_additional_channels]`
+- `filter[area_name]`
+- `filter[available_dids_enabled]`
+- `filter[city.id]`
+- `filter[country.id]`
+- `filter[did_group_type.id]`
+- `filter[features]`
+- `filter[is_available]`
+- `filter[is_metered]`
+- `filter[meta.total_count_gteq]`
+- `filter[nanpa_prefix.id]`
+- `filter[nanpa_prefix.npanxx]`
+- `filter[needs_registration]`
+- `filter[prefix]`
+- `filter[region.id]`
+
+## DidGroupType — `GET /v3/did_group_types`
+
+- `filter[name]`
+
+## DidHistory — `GET /v3/did_history`
+
+- `filter[action]`
+- `filter[created_at_gteq]`
+- `filter[created_at_lteq]`
+- `filter[did_number]`
+- `filter[method]`
+
+## DidReservation — `GET /v3/did_reservations`
+
+- `filter[description]`
+
+## Did — `GET /v3/dids`
+
+- `filter[address_verification.id]`
+- `filter[awaiting_registration]`
+- `filter[billing_cycles_count]`
+- `filter[blocked]`
+- `filter[capacity_pool.id]`
+- `filter[city.id]`
+- `filter[country.id]`
+- `filter[description]`
+- `filter[did_group.features]`
+- `filter[did_group.id]`
+- `filter[emergency_calling_service.id]`
+- `filter[emergency_enabled]`
+- `filter[number]`
+- `filter[order.id]`
+- `filter[order.reference]`
+- `filter[region.id]`
+- `filter[shared_capacity_group.id]`
+- `filter[terminated]`
+- `filter[voice_in_trunk.id]`
+- `filter[voice_in_trunk_group.id]`
+
+
+## EmergencyCallingService — `GET /v3/emergency_calling_services`
+
+- `filter[address.id]`
+- `filter[country.id]`
+- `filter[did_group_type.id]`
+- `filter[identity.id]`
+- `filter[name]`
+- `filter[reference]`
+- `filter[status]`
+
+## EmergencyRequirement — `GET /v3/emergency_requirements`
+
+- `filter[country.id]`
+- `filter[did_group_type.id]`
+
+## EmergencyVerification — `GET /v3/emergency_verifications`
+
+- `filter[emergency_calling_service.id]`
+- `filter[external_reference_id]`
+- `filter[status]`
+
+## Export — `GET /v3/exports`
+
+- `filter[external_reference_id]`
+
+## Identity — `GET /v3/identities`
+
+- `filter[birth_date]`
+- `filter[company_name]`
+- `filter[company_name_contains]`
+- `filter[company_reg_number]`
+- `filter[company_reg_number_contains]`
+- `filter[country.id]`
+- `filter[description]`
+- `filter[description_contains]`
+- `filter[external_reference_id]`
+- `filter[first_name]`
+- `filter[first_name_contains]`
+- `filter[id_number]`
+- `filter[id_number_contains]`
+- `filter[identity_type]`
+- `filter[last_name]`
+- `filter[last_name_contains]`
+- `filter[personal_tax_id]`
+- `filter[personal_tax_id_contains]`
+- `filter[phone_number]`
+- `filter[phone_number_contains]`
+- `filter[vat_id]`
+- `filter[vat_id_contains]`
+
+## NanpaPrefix — `GET /v3/nanpa_prefixes`
+
+- `filter[country.id]`
+- `filter[did_group.features]`
+- `filter[did_group.is_available]`
+- `filter[npa]`
+- `filter[npanxx]`
+- `filter[nxx]`
+- `filter[region.id]`
+
+## Order — `GET /v3/orders`
+
+- `filter[created_at_gteq]`
+- `filter[created_at_lteq]`
+- `filter[external_reference_id]`
+- `filter[reference]`
+- `filter[status]`
+
+## PermanentSupportingDocument — `GET /v3/permanent_supporting_documents`
+
+- `filter[external_reference_id]`
+
+## Proof — `GET /v3/proofs`
+
+- `filter[external_reference_id]`
+
+## ProofType — `GET /v3/proof_types`
+
+- `filter[entity_type]`
+
+## Region — `GET /v3/regions`
+
+- `filter[country.id]`
+- `filter[iso]`
+- `filter[name]`
+
+## SharedCapacityGroup — `GET /v3/shared_capacity_groups`
+
+- `filter[capacity_pool.id]`
+- `filter[external_reference_id]`
+- `filter[name]`
+
+## SupportingDocumentTemplate — `GET /v3/supporting_document_templates`
+
+- `filter[name]`
+- `filter[name_contains]`
+- `filter[permanent]`
+
+## VoiceInTrunkGroup — `GET /v3/voice_in_trunk_groups`
+
+- `filter[external_reference_id]`
+
+## VoiceInTrunk — `GET /v3/voice_in_trunks`
+
+- `filter[configuration.type]`
+- `filter[external_reference_id]`
+- `filter[name]`
+
+## VoiceOutTrunk — `GET /v3/voice_out_trunks`
+
+- `filter[allow_any_did_as_cli]`
+- `filter[authentication_method.type]`
+- `filter[default_did.id]`
+- `filter[default_dst_action]`
+- `filter[external_reference_id]`
+- `filter[media_encryption_mode]`
+- `filter[name]`
+- `filter[name_contains]`
+- `filter[on_cli_mismatch_action]`
+- `filter[status]`
+- `filter[threshold_reached]`
diff --git a/README.md b/README.md
index 2300a915..c9d44695 100644
--- a/README.md
+++ b/README.md
@@ -527,6 +527,8 @@ client.voiceInTrunks().update(trunk);
 
 ## Filtering, Sorting, and Pagination
 
+> See [`FILTERS.md`](FILTERS.md) for the canonical list of `filter[KEY]` keys accepted by every list endpoint, verified live against the DIDWW API at version `2026-04-16`.
+
 ```java
 import com.didww.sdk.http.QueryParams;