list_dids_in_country_city
Retrieve available Direct Inward Dialing (DID) numbers in a specific city and country. Filter by SMS capability, view pricing, activation details, and required documents for purchase. Returns structured JSON data with pagination support.
Instructions
List of available DID in a city of a country
Args: country_id: ID of country for search city_id: ID of city in a country sms_enabled: search for DID with SMS functionality page: page of result starting with 1 per_page: how many results should be on per page
Returns a JSON object with available DIDs where: dids: Array of DID available for purchasing where: id: ID of DID country: Country name city: City name sms_enabled: Is number capable of receiving SMS channels: How many parallel channels have DID free_min: How many free minutes per month DID have activation: Activation cost for DID in USD monthly: Monthly fee for DID per_minute: Per minute cost for DID origination_per_min: per minute cost if origin based rate applied required_documents: required documents for activating number, where: 1 = Any form of ID 2 = Proof of address 3 = Proof of local address number: DID Number in E164 format pagination: Pagination details for results page: current page of results total_pages: total pages results total: total query records
403 error indicates disabled API calls for purchase.
Example:
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| city_id | Yes | City ID | |
| country_id | Yes | Country ID | |
| page | No | Search page | |
| per_page | No | Search per page | |
| sms_enabled | No | Filter for sms enabled numbers |
Implementation Reference
- The core handler function implementing the 'list_dids_in_country_city' tool. It validates inputs using Pydantic Fields (serving as schema), constructs query parameters, calls the shared base.call_didlogic_api helper to fetch available DIDs from the DIDLogic /v2/buy/countries/{country_id}/cities/{city_id}/dids endpoint, and returns the JSON response.@mcp.tool() async def list_dids_in_country_city( ctx: Context, country_id: int = Field(description="Country ID"), city_id: int = Field(description="City ID"), sms_enabled: Optional[bool] = Field( description="Filter for sms enabled numbers", default=None ), page: Optional[int] = Field(description="Search page", default=None), per_page: Optional[int] = Field( description="Search per page", default=None ) ) -> str: """ List of available DID in a city of a country Args: country_id: ID of country for search city_id: ID of city in a country sms_enabled: search for DID with SMS functionality page: page of result starting with 1 per_page: how many results should be on per page Returns a JSON object with available DIDs where: dids: Array of DID available for purchasing where: id: ID of DID country: Country name city: City name sms_enabled: Is number capable of receiving SMS channels: How many parallel channels have DID free_min: How many free minutes per month DID have activation: Activation cost for DID in USD monthly: Monthly fee for DID per_minute: Per minute cost for DID origination_per_min: per minute cost if origin based rate applied required_documents: required documents for activating number, where: 1 = Any form of ID 2 = Proof of address 3 = Proof of local address number: DID Number in E164 format pagination: Pagination details for results page: current page of results total_pages: total pages results total: total query records 403 error indicates disabled API calls for purchase. Example: ``` { "dids": { "pagination": { "total": 52, "total_pages": 1, "current_page": 1 }, "dids": [ { "id": 112370, "country": "Canada", "city": "Edmonton, AB", "sms_enabled": false, "no_local_cli": false, "channels": 4, "free_min": 0, "cnam": null, "activation": 1.0, "monthly": 1.0, "per_minute": 0.01, "origination_per_min": null, "required_documents": [], "state": "Alberta", "country_short_name": "CA", "number": "17806999999" } ] } } ``` """ params = {} if sms_enabled is not None: params["sms_enabled"] = int(sms_enabled) if page is not None: params["page"] = page if per_page is not None: params["per_page"] = per_page response = await base.call_didlogic_api( ctx, "GET", f"/v2/buy/countries/{country_id}/cities/{city_id}/dids", params=params ) return response.text
- src/didlogic_mcp/server.py:103-103 (registration)Registers all tools from the purchase module (including list_dids_in_country_city) by invoking the module's register_tools function on the FastMCP server instance.tools.purchase.register_tools(mcp)
- src/didlogic_mcp/tools/base.py:9-53 (helper)Shared utility function called by the handler to perform authenticated HTTP requests to the DIDLogic API, handling auth based on transport mode (stdio or http/sse).async def call_didlogic_api( ctx: Context, method: str, path: str, params: Optional[Dict] = None, data: Optional[Dict] = None, json: Optional[Dict] = None ) -> httpx.Response: """ Make a call to the Didlogic API. In HTTP/SSE mode, extracts Bearer token from request context and adds it to the Authorization header for each API call. In STDIO mode, uses the API key already configured in the client headers. """ client = ctx.request_context.lifespan_context.client # In HTTP/SSE mode, get API key from request.state (set by middleware) extra_headers = {} # Check if we have a request object (indicates HTTP/SSE mode) request = getattr(ctx.request_context, "request", None) if request and hasattr(request, 'state') and hasattr(request.state, 'didlogic_api_key'): # HTTP/SSE mode: extract API key from request state api_key = request.state.didlogic_api_key if api_key: extra_headers["Authorization"] = f"Bearer {api_key}" logger.debug(f"Using API key from request state: {api_key[:8]}...") else: logger.warning("No API key found in request state") else: # STDIO mode: API key already in client headers from lifespan logger.debug("Using API key from client headers (STDIO mode)") response = await client.request( method=method, url=path, params=params, data=data, json=json, headers=extra_headers ) response.raise_for_status() return response