Network APIs | Pinnacle | Documentation

Network APIs help you make higher-confidence trust decisions for phone numbers. Use them during onboarding, account verification, account protection, or fraud review.

Limited availability

Network APIs are currently available only to select customers. To request access, contact founders@pinnacle.sh.

Capabilities

SIM Swap

Check whether a phone number’s SIM changed recently.

Subscriber Match

Compare user-provided identity attributes against the carrier record.

Silent Auth

Verify device possession using the user’s cellular data path.

Input constraints

Input constraints keep requests valid for carrier-backed checks and make request history predictable. Validate these fields before calling the API to avoid rejected requests.

All phone numbers must use E.164 format, for example +14155550123.

Field	Description and constraint
`requestId`	Pinnacle-generated Network API request ID used to retrieve a prior request. It starts with `nar_` followed by 16 letters or numbers.
`periodHours`	SIM Swap lookback window, in hours. Use a shorter window for recent-risk checks or a longer window for broader account review. Must be an integer from `1` to `2400`; defaults to `240`.
`clientRef`	Your optional correlation ID, such as a user ID, session ID, or case ID. It is returned in request history to help reconcile checks with your own systems. Must be `1` to `40` characters when provided.
`attributes`	Subscriber Match fields to compare against the carrier record. Provide at least one non-empty attribute; more attributes can improve the usefulness of the match result.
`birthdate`	Subscriber date of birth for Subscriber Match. Format as `YYYY-MM-DD`, for example `1990-01-31`.
`pageIndex`	Zero-based page number for listing request history. Use `0` for the first page, `1` for the second page, and so on. Must be `0` or greater; defaults to `0`.
`pageSize`	Number of request records to return per page. Use smaller values for quick UI loads and larger values for back-office review. Must be from `1` to `100`; defaults to `20`.

SIM Swap

Call POST /network/sim-swap with an E.164 phone number and an optional periodHours window. The response tells you whether the SIM was swapped during that window.

{
  "phoneNumber": "+14155550123",
  "periodHours": 240
}

Subscriber Match

Call POST /network/subscriber-match with an E.164 phone number and at least one subscriber attribute. The response returns match strength for each attribute that can be evaluated.

{
  "phoneNumber": "+14155550123",
  "attributes": {
    "givenName": "Jane",
    "familyName": "Doe",
    "postalCode": "94105"
  }
}

Silent Auth

Silent Auth verifies that the user controls the device attached to the phone number. Your server starts the session, then the user’s device completes the carrier check.

SDKs coming soon

Native SDKs for iOS, Android, and React Native are coming soon to simplify embedding the JSON flow and code capture in mobile applications.

Start the session

Your server calls POST /network/silent-auth with the user’s phone number. Omit format for the hosted HTML flow, or set format: "json" for the JSON flow. The response includes expiresAt for the initial device handoff.

Run the device check

Open browserUrl for hosted sessions, or fetch jsonUrl for JSON sessions. Do not call either URL server-side.

Finish or read the result

The HTML flow completes the request in the browser. The JSON flow returns a code from your app’s fetch call; send that code to your server, then call POST /network/silent-auth/{requestId}/check.

Open Silent Auth URLs immediately

Silent Auth URLs expire 60 seconds after creation because the carrier device check must start promptly. If expiresAt has passed, start a new Silent Auth session before asking the user to try again.

{
  "phoneNumber": "+14155550123",
  "clientRef": "user_123"
}

HTML flow

Use browserUrl when you want Pinnacle to handle the device-check page.

Open the URL on the user’s phone in a browser, mobile WebView, or app redirect. Pinnacle serves a hosted page that runs the carrier challenge and completes the Silent Auth request.

{
  "requestId": "nar_1234567890ABCDEF",
  "format": "hosted",
  "browserUrl": "https://verify.pinnacle.sh/silent-auth/nar_1234567890ABCDEF?sessionToken=...",
  "expiresAt": "2026-06-12T18:30:00Z"
}

JSON flow

Use jsonUrl when you are building a native mobile flow and do not want to open a browser. Your app fetches the URL directly from the user’s cellular device and controls the UI itself.

Start the session with format: "json" so the device check redirects back to a JSON response instead of the hosted verification page.

{
  "phoneNumber": "+14155550123",
  "clientRef": "user_123",
  "format": "json"
}

The start response includes only the URL for the requested flow:

{
  "requestId": "nar_1234567890ABCDEF",
  "format": "json",
  "jsonUrl": "https://api.pinnacle.sh/public/network/silent-auth/nar_1234567890ABCDEF?sessionToken=...&format=json",
  "expiresAt": "2026-06-12T18:30:00Z"
}

Fetch jsonUrl from the user’s phone with redirects enabled. Pinnacle validates the session, redirects through the carrier challenge, and the final response is JSON containing a verification code. Send that code to your server, then call POST /network/silent-auth/{requestId}/check.

{
  "code": "abc123"
}

Do not proxy jsonUrl through your backend. Silent Auth depends on the request leaving from the user’s cellular data path.

Run on the user's cellular device

browserUrl and jsonUrl must be opened or fetched from the user’s device, not server-side. The device must be using its cellular network. Wi-Fi-only paths, VPNs, iCloud Private Relay, and similar proxying products can prevent Silent Auth from working.

Request history

Every Network API call creates a request record scoped to your team. Use POST /network/requests/list to page through recent requests, or GET /network/requests/{requestId} to retrieve one request.

Request summaries include lifecycle timestamps, the request status, your clientRef, and the result fields returned by the original check.

{
  "pageIndex": 0,
  "pageSize": 20,
  "type": "silent-auth",
  "status": "completed",
  "clientRef": "user_123"
}