From de26cf53a3ce36272a5cef6237220df0a2ec99b5 Mon Sep 17 00:00:00 2001 From: Igor Fedoronchuk Date: Fri, 8 May 2026 14:27:37 +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 0000000..d9b4d24 --- /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().filter("country.id", uuid)`), 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 8b55b19..1e94303 100644 --- a/README.md +++ b/README.md @@ -518,6 +518,8 @@ client.download_export(created.url, "/tmp/export.csv") ## 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`. + ```python from didww.query_params import QueryParams