--- title: "Search for Results" method: POST path: "/search_results" tags: ["Requests"] --- # Search for Results `POST /search_results` ## Request - Base URL: `https://api.commpeak.com/lookup` - URL: `https://api.commpeak.com/lookup/search_results` - Auth: API key in header `Authorization` Search per-number lookup results across past tasks. Filter by phone number (exact, prefix or substring), task IDs, task creation date range, lookup type, validation outcome, number type, country, and ported / roaming flags. Paginate with `limit` and `skip`; set `with_totals=1` to also get `total`, `unique`, `invalid` and `mobile` counts. ## Request body - SearchRequest: Filter payload for `POST /lookup/search_results`. All fields are optional — supply only the ones you want to filter on. - `key` string, nullable: Exact-match phone number (E.164 without leading "+"). - `key_start` string, nullable: Phone-number prefix match (e.g. "1212" for New York). - `key_contains` string, nullable: Substring match anywhere in the phone number. - `job_ids` string[], nullable: Restrict the search to results produced by these task ids. - `keys` string[], nullable: Restrict the search to this set of phone numbers. - `search_from` string, nullable: Lower bound on task creation time (ISO 8601). - `search_till` string, nullable: Upper bound on task creation time (ISO 8601). - `search_date` string, nullable: Filter for a single calendar date (YYYY-MM-DD). - `result` string, nullable: Filter by top-level result string (e.g. "Active", "valid"). - `request_type` integer, nullable: Filter by lookup type id (1 = hlr, 2 = validate). - `valid` boolean, nullable: Filter by validation outcome. - `number_type` string, nullable: Filter by detected number type ("mobile", "fixed_line", etc.). - `limit` integer, nullable: Maximum number of rows to return (page size). - `skip` integer, nullable: Offset into the result set (for pagination). - `with_totals` integer, nullable: Set to 1 to include the aggregate counts (`total`, `unique`, `invalid`, `mobile`) in the response. - `country` string, nullable: Filter by ISO 3166-1 alpha-2 country code (e.g. "US"). - `is_ported` boolean, nullable: Filter by port-status flag. - `is_roaming` boolean, nullable: Filter by roaming-status flag. ## Response `200` Successful Response - SearchResultResponse: Response from `POST /lookup/search_results` — paginated results plus optional aggregate counts (when `with_totals=1`). - `results` AsyncResultItem[], required - `request_key` string, nullable: The looked-up number (E.164 without leading "+"). - `request_uuid` string, nullable: Per-number request identifier assigned by upstream. - `request_time` string, date-time, nullable: Timestamp when the per-number lookup was performed. - `request_type` string, nullable: Lookup type that was performed: "hlr" or "validate". - `meta` object, nullable: Upstream metadata bag. - `extended` object, nullable: Extended provider-specific fields. - `hlr` HlrResult: HLR (Home Location Register) lookup result — line state on the carrier network. - `hlr_status` string, required: Line status (e.g. "Active", "Absent Subscriber", "Unknown"). - `description` string, nullable: Free-form description from the HLR provider. - `mcc` string, nullable: Mobile Country Code (ITU E.212), e.g. "310" for United States. - `mnc` string, nullable: Mobile Network Code (ITU E.212), identifies the operator within the country. - `country_name` string, nullable: Country name resolved from MCC. - `network_name` string, nullable: Operator network name resolved from MCC+MNC. - `is_ported` boolean, nullable: True when the number has been ported to a different network. - `is_roaming` boolean, nullable: True when the subscriber is currently roaming (may be null if unknown). - `validation` ValidationResult: Validation lookup result — number parseability and US LERG/DNC enrichment. - `valid` boolean, nullable: True when the number is syntactically valid for its country. - `possible` boolean, nullable: True when the number could plausibly be a phone number (less strict than `valid`). - `mobile` boolean, nullable: True when the number is identified as mobile. - `reason` string, nullable: Human-readable reason when `valid` is false; null otherwise. - `number_type` string, nullable: Detected number type ("mobile", "fixed_line", "fixed_line_or_mobile", "toll_free", "voip", etc.). - `e164` string, nullable: Number normalized to E.164 (no leading "+"). - `lrn` string, nullable: Local Routing Number (US LNP). String "False" when no LRN is published. - `dnc` boolean, nullable: True when the number appears in a Do-Not-Call registry (US DNC). - `lerg` object, nullable: US LERG row (state, operator, ocn, ratecenter, linetype, country). Present for US numbers only. - `dno` string, nullable: Do-Not-Originate (DNO) code; "0" when not flagged. - `dno_description` string, nullable: Human-readable DNO description (e.g. "Missing", "Confirmed"). - `national` string, nullable: Number formatted nationally for its country (e.g. "(212) 555-1234"). - `international` string, nullable: Number formatted internationally (e.g. "+1 212-555-1234"). - `country_code` string, nullable: ITU dialing code (e.g. "1" for North America). - `country_iso2` string, nullable: ISO 3166-1 alpha-2 country code (e.g. "US"). - `corrections` CorrectionResult[], nullable: Suggested corrections when the input could not be parsed cleanly. - `e164` string, nullable: Corrected number in E.164 format (no leading "+"). - `country_iso2` string, nullable: ISO 3166-1 alpha-2 country code (e.g. "US"). - `number_type` string, nullable: Number type: "mobile", "fixed_line", "fixed_line_or_mobile", "toll_free", etc. - `total` integer, nullable: Total matching numbers across the result set. - `unique` integer, nullable: Distinct numbers among the matches. - `invalid` integer, nullable: Count of matches where validation failed. - `mobile` integer, nullable: Count of matches identified as mobile. ## Other responses - `404`: Not Found - `422`: Validation Error --- [API](https://skmtc.dev/commpeak/apis/commpeak-lookup-api.md) - [All operations](https://skmtc.dev/commpeak/apis/commpeak-lookup-api/llms.txt) - [OpenAPI document](https://skmtc.dev/commpeak/apis/commpeak-lookup-api/revisions/34bfa2798a03?raw)