---
title: "List Network Requests"
method: POST
path: "/network/requests/list"
tags: ["network > requests"]
---

# List Network Requests

`POST /network/requests/list`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/network/requests/list`
- Auth: API key in header `PINNACLE-API-KEY`

List Network API request records for your team, sorted newest first. Use filters to audit recent checks by type, status, or your own `clientRef`.

<Note>
  Limited availability. Contact [founders@pinnacle.sh](mailto:founders@pinnacle.sh) to request access.
</Note>

## Request body

- ListNetworkRequestsRequest
  - `pageIndex` integer: Zero-based page index. Use 0 for the first page.
  - `pageSize` integer: Number of records to return, from 1 to 100.
  - `type` 'silent-auth' | 'sim-swap' | 'subscriber-match': Type of Network API check.
  - `status` 'started' | 'challenge-issued' | 'completed' | 'failed' | 'expired': Lifecycle status of a Network API request. `started` and `challenge-issued` are in-progress states; `completed`, `failed`, and `expired` are terminal states.
  - `clientRef` string: Filter by your correlation ID. Must be 1 to 40 characters when provided.

## Response `200`

Returns a paginated list of Network API request summaries.

- ListNetworkRequestsResponse
  - `data` NetworkRequestSummary[], required
    - `requestId` string, required: Unique Pinnacle ID for a Network API request.
    - `type` 'silent-auth' | 'sim-swap' | 'subscriber-match', required: Type of Network API check.
    - `status` 'started' | 'challenge-issued' | 'completed' | 'failed' | 'expired', required: Lifecycle status of a Network API request. `started` and `challenge-issued` are in-progress states; `completed`, `failed`, and `expired` are terminal states.
    - `clientRef` string, nullable, required: Your correlation ID from the original request.
    - `createdAt` string, date-time, required: Timestamp when the request record was created.
    - `updatedAt` string, date-time, required: Timestamp when the request record was last updated.
    - `completedAt` string, date-time, nullable, required: Timestamp when the request reached a terminal state.
    - `expiresAt` string, date-time, nullable, required: Expiration timestamp for short-lived request flows, when applicable.
    - `errorMessage` string, nullable, required: Error message for failed requests.
    - `result` union, required: Result from the original check, or null while the request is still pending or no result is available.
      - SimSwapResponse
        - `requestId` string, required: Unique Pinnacle ID for a Network API request.
        - `status` 'available' | 'unavailable' | 'unsupported' | 'failed', required: Availability of the carrier-backed insight.
        - `simSwapped` boolean, nullable, required: Whether the SIM changed during the requested window. Null means the carrier insight was unavailable, unsupported, or failed.
        - `latestSimSwapAt` string, date-time, nullable, required: Timestamp of the latest SIM change in the requested window, when the carrier provides it.
      - SubscriberMatchResponse
        - `requestId` string, required: Unique Pinnacle ID for a Network API request.
        - `status` 'available' | 'unavailable' | 'unsupported' | 'failed', required: Availability of the carrier-backed insight.
        - `matches` SubscriberMatchResponseMatches, required: Match strength for each evaluated subscriber attribute. - `exact`: Carrier record matches the submitted value exactly. - `high`: Strong match with minor formatting or normalization differences. - `partial`: Some parts match, but the value is not a strong match. - `low`: Weak match. - `none`: Carrier record does not match the submitted value. - `unavailable`: Carrier could not evaluate this attribute. - `included-with-address-match`: Attribute was evaluated as part of the overall address match. - `unknown`: Carrier returned a match value Pinnacle does not recognize yet.
          - `idDocument` 'exact' | 'high' | 'partial' | 'low' | 'none' | 'unavailable' | 'included-with-address-match' | 'unknown': Carrier match strength for one submitted subscriber attribute.
          - `givenName` 'exact' | 'high' | 'partial' | 'low' | 'none' | 'unavailable' | 'included-with-address-match' | 'unknown': Carrier match strength for one submitted subscriber attribute.
          - `familyName` 'exact' | 'high' | 'partial' | 'low' | 'none' | 'unavailable' | 'included-with-address-match' | 'unknown': Carrier match strength for one submitted subscriber attribute.
          - `address` 'exact' | 'high' | 'partial' | 'low' | 'none' | 'unavailable' | 'included-with-address-match' | 'unknown': Carrier match strength for one submitted subscriber attribute.
          - `streetName` 'exact' | 'high' | 'partial' | 'low' | 'none' | 'unavailable' | 'included-with-address-match' | 'unknown': Carrier match strength for one submitted subscriber attribute.
          - `streetNumber` 'exact' | 'high' | 'partial' | 'low' | 'none' | 'unavailable' | 'included-with-address-match' | 'unknown': Carrier match strength for one submitted subscriber attribute.
          - `postalCode` 'exact' | 'high' | 'partial' | 'low' | 'none' | 'unavailable' | 'included-with-address-match' | 'unknown': Carrier match strength for one submitted subscriber attribute.
          - `locality` 'exact' | 'high' | 'partial' | 'low' | 'none' | 'unavailable' | 'included-with-address-match' | 'unknown': Carrier match strength for one submitted subscriber attribute.
          - `region` 'exact' | 'high' | 'partial' | 'low' | 'none' | 'unavailable' | 'included-with-address-match' | 'unknown': Carrier match strength for one submitted subscriber attribute.
          - `country` 'exact' | 'high' | 'partial' | 'low' | 'none' | 'unavailable' | 'included-with-address-match' | 'unknown': Carrier match strength for one submitted subscriber attribute.
          - `streetNumberSuffix` 'exact' | 'high' | 'partial' | 'low' | 'none' | 'unavailable' | 'included-with-address-match' | 'unknown': Carrier match strength for one submitted subscriber attribute.
          - `birthdate` 'exact' | 'high' | 'partial' | 'low' | 'none' | 'unavailable' | 'included-with-address-match' | 'unknown': Carrier match strength for one submitted subscriber attribute.
      - SilentAuthCheckResponse
        - `requestId` string, required: Unique Pinnacle ID for a Network API request.
        - `status` 'completed' | 'failed', required: Terminal verification result after exchanging a device flow code. `completed` means the phone number was verified; `failed` means the verification did not complete successfully. To inspect pending lifecycle states, use [Get Network Request](/api-reference/network/get-network-request).
  - `hasMore` boolean, required: Whether another page exists after this one.
  - `count` integer, required: Total number of matching request records.

## Other responses

- `400`: The request was unacceptable, often due to providing an invalid update. <br> Errors may originate from invalid payload or from Pinnacle's additional validation checks. For example, providing an URL that cannot be accessed, updating a campaign that is currently being reviewed, updating data that you cannot access, sending a malformed message, and so on. <br> For `Pinnacle Validation Error` inspect the `error` payload to determine the source of the failure. These errors are likely due to additional validation and business logic checks.<br> For `Request Validation Error` inspect the `description` and `errors` payload to determine the source of failure. These errors are likely due to invalid payload inside the request.
- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `403`: Your subscription does not include access to this feature. <br> This occurs when attempting to use functionality that requires a higher subscription tier. Please upgrade your subscription to access this feature.
- `500`: An unexpected error occurred on Pinnacle's servers while processing your request. <br> If this error persists, please contact support with the request details.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)