Skip to content

API reference

Every public resource operation is listed below with its typed signature. Request and response models are exported from the top-level questblue package and documented in their resource modules.

Clients

questblue.QuestBlue

Synchronous client for the QuestBlue API.

paginate(path, *, method='GET', params=None, start_page=1, max_pages=10000, item_parser=None, item_selector=None)

Lazily iterate a paginated endpoint while retaining raw page access.

request(method, path, *, params=None, json=None, headers=None, timeout=None, max_retries=None, raw_response=False)

Issue an authenticated request with safe, request-level overrides.

Retries apply only to GET, HEAD, and OPTIONS. Mutating methods are always attempted once because QuestBlue does not document idempotency guarantees.

questblue.AsyncQuestBlue

Asynchronous client for the QuestBlue API.

paginate(path, *, method='GET', params=None, start_page=1, max_pages=10000, item_parser=None, item_selector=None)

Lazily iterate a paginated endpoint while retaining raw page access.

request(method, path, *, params=None, json=None, headers=None, timeout=None, max_retries=None, raw_response=False) async

Issue an authenticated request with sync-client-equivalent behavior.

Resource operations

questblue._resources.Account

Bases: Resource

questblue._resources.AsyncAccount

Bases: Resource

questblue._resources.DIDs

Bases: Resource

questblue._resources.AsyncDIDs

Bases: Resource

questblue._resources.InternationalDIDs

Bases: Resource

questblue._resources.AsyncInternationalDIDs

Bases: Resource

questblue._resources.SIPTrunks

Bases: Resource

questblue._resources.AsyncSIPTrunks

Bases: Resource

questblue._resources.SMS

Bases: Resource

questblue._resources.AsyncSMS

Bases: Resource

questblue._resources.DLC

Bases: Resource

questblue._resources.AsyncDLC

Bases: Resource

questblue._resources.Fax

Bases: Resource

questblue._resources.AsyncFax

Bases: Resource

questblue._resources.EnterpriseFax

Bases: Resource

questblue._resources.AsyncEnterpriseFax

Bases: Resource

questblue._resources.Reports

Bases: Resource

questblue._resources.AsyncReports

Bases: Resource

questblue._resources.LNP

Bases: Resource

questblue._resources.AsyncLNP

Bases: Resource

questblue._resources.Servers

Bases: Resource

questblue._resources.AsyncServers

Bases: Resource

Models

questblue.models

Shared public models and validation primitives for QuestBlue resources.

BinaryResponse dataclass

Binary response content plus useful transport metadata.

ErrorResponse

Bases: QuestBlueModel

Common application-error body, including QuestBlue HTTP 206 responses.

OpenStringEnum

Bases: str, Enum

String enum that preserves unknown values introduced by QuestBlue.

PageMetadata

Bases: QuestBlueModel

Pagination metadata shared by collection endpoints.

next_page(item_count)

Return the next page number, or None when this is the final page.

ParsedResponse dataclass

Bases: Generic[DataT]

Validated data paired with the exact decoded upstream payload.

QuestBlueModel

Bases: BaseModel

Base model that remains compatible with fields QuestBlue adds later.

extra_fields property

Fields not yet known to this SDK release.

to_request_params()

Serialize a request model using API aliases and JSON-compatible values.

ResponseEnvelope

Bases: QuestBlueModel, Generic[DataT]

Common QuestBlue response shape containing a data field.

TimestampRange

Bases: QuestBlueModel

Inclusive Unix timestamp range used by reporting endpoints.

WarningResponse

Bases: QuestBlueModel

QuestBlue's non-fatal HTTP 202 warning shape.

model_parser(model)

Create an item parser suitable for a paginator.

parse_model(model, payload)

Validate a payload while retaining the exact decoded response.

questblue.account

Typed models and validation for QuestBlue User Account operations.

AccountActionResponse

Bases: ResponseEnvelope[str]

Success envelope returned by account alert mutations.

AccountToggle

Bases: str, Enum

Validated on/off value accepted by account mutations.

CallbackSection

Bases: str, Enum

Inventory area accepted by account callback configuration.

PaymentMethod

Bases: OpenStringEnum

Payment method reported by QuestBlue.

PaymentMode

Bases: str, Enum

Legacy refill payment mode retained by the upstream contract.

parse_account_response(model, payload)

Validate an account response while retaining upstream warning semantics.

parse_empty_account_response(payload)

Validate an operation documented to return an empty success body.

questblue.did

Typed models and validation for QuestBlue Voice DID operations.

questblue.international_did

Typed models for QuestBlue International DID operations.

InternationalCountriesRequest

Bases: QuestBlueModel

Country discovery parameters.

The upstream contract marks did required but describes it as a DID to move, which is inconsistent with a country-list operation. It remains optional until QuestBlue confirms that behavior.

InternationalDIDInventoryResponse

Bases: DIDInventoryResponse

Paged international DID inventory and configuration values.

InternationalDIDListRequest

Bases: DIDListRequest

Wildcard and page controls for international DID inventory.

questblue.sip_trunk

Typed models for QuestBlue SIP Trunk operations.

questblue.sms

Typed models and validation for QuestBlue SMS, MMS, and carrier operations.

SMSModel

Bases: QuestBlueModel

Messaging model that suppresses PII values in validation diagnostics.

questblue.dlc

Typed models and validation for QuestBlue 10DLC brand and campaign operations.

DLCModel

Bases: QuestBlueModel

10DLC model that suppresses registration data in validation diagnostics.

questblue.fax

Typed models, file helpers, and validation for QuestBlue Fax.Pro operations.

FaxModel

Bases: QuestBlueModel

Fax model that suppresses document and account values in validation errors.

questblue.enterprise_fax

Typed models and file helpers for QuestBlue iFax Enterprise operations.

questblue.reports

Typed models and export helpers for QuestBlue reporting operations.

FaxDownloadData

Bases: ReportModel

iter_bytes(chunk_size=64 * 1024)

Incrementally decode base64 without duplicating it as one bytes object.

export_rows(response)

Return standard dictionaries suitable for csv.DictWriter or pandas.DataFrame.

questblue.lnp

Typed models and bill helpers for QuestBlue number portability.

questblue.servers

Typed models for QuestBlue VoIP server operations.

questblue.webhooks

Framework-neutral models and parsing for QuestBlue messaging webhooks.

InboundMessageEvent

Bases: WebhookEvent

An inbound SMS or MMS callback.

MessageStatusEvent

Bases: WebhookEvent

An outbound message delivery-status callback.

UnknownWebhookEvent

Bases: WebhookEvent

A forward-compatible callback whose shape is not yet published.

WebhookEnvelope dataclass

A parsed event plus content-free processing metadata.

WebhookEvent

Bases: QuestBlueModel

Base callback model that preserves fields added by QuestBlue.

WebhookKind

Bases: str, Enum

Webhook shapes published in the QuestBlue 2.3.2 contract.

WebhookMessageType

Bases: OpenStringEnum

Published inbound message types, open to future provider values.

WebhookVerificationRequired

Bases: ValueError

Raised when a framework helper is used without an explicit verifier.

WebhookVerifier

Bases: Protocol

Application-defined callback verifier.

QuestBlue does not publish a callback signature scheme. Implementations can enforce a reverse-proxy secret, mTLS identity, IP policy, or another control owned by the receiving application. They must raise on verification failure.

__call__(headers, body)

Verify the exact request bytes or raise an exception.

parse_webhook(body, *, headers=None, verifier=None, kind=None)

Verify and parse a QuestBlue callback without discarding unknown fields.

The returned verified flag is true only when the supplied verifier completes successfully. Parsing alone makes no authenticity claim.