Check Subscriber Match | Pinnacle

import { PinnacleClient } from "rcs-js";
async function main() {
    const client = new PinnacleClient({
        apiKey: "YOUR_API_KEY_HERE",
    });
    await client.network.subscriberMatch.check({
        phoneNumber: "+14155550123",
        attributes: {
            givenName: "Jane",
            familyName: "Doe",
            streetName: "Market Street",
            streetNumber: "123",
            postalCode: "94105",
            locality: "San Francisco",
            region: "CA",
            country: "US",
            birthdate: "1990-01-31",
        },
    });
}
main();

{
  "requestId": "nar_1234567890ABCDEF",
  "status": "available",
  "matches": {
    "givenName": "exact",
    "familyName": "high",
    "streetName": "high",
    "streetNumber": "exact",
    "postalCode": "exact",
    "locality": "exact",
    "region": "exact",
    "country": "exact",
    "birthdate": "exact"
  }
}

Compare user-provided identity details against the carrier’s subscriber record. Results return match strength per attribute, so you can use partial signals without receiving carrier PII.

Limited availability. Contact founders@pinnacle.sh to request access.

Authentication

PINNACLE-API-KEYstring

API Key authentication via header

Request

This endpoint expects an object.

phoneNumberstringRequiredformat: "^\+[1-9]\d{9,14}$"

Phone number in E.164 format, including country code.

attributesobjectRequired

User-provided subscriber details to compare with the carrier record. Provide at least one non-empty field.

Response

Returns match strength for each evaluated subscriber attribute.

requestIdstringformat: "^nar_[A-Za-z0-9]{16}$"

Unique Pinnacle ID for a Network API request.

statusenum

Availability of the carrier-backed insight.

Allowed values:

matchesobject

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.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

500

Internal Server Error