---
title: "Check Subscriber Match"
method: POST
path: "/network/subscriber-match"
tags: ["network > subscriberMatch"]
---

# Check Subscriber Match

`POST /network/subscriber-match`

## Request

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

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.

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

## Request body

- SubscriberMatchRequest
  - `phoneNumber` string, required: Phone number in E.164 format, including country code.
  - `attributes` SubscriberMatchAttributes, required: User-provided subscriber details to compare with the carrier record. Provide at least one non-empty field.
    - `idDocument` string: Government-issued ID number, such as a national ID, passport number, or driver's license number when supported by the carrier. Do not send an image or file.
    - `givenName` string: Subscriber's first or given name.
    - `familyName` string: Subscriber's last or family name.
    - `streetName` string: Street name from the subscriber's address.
    - `streetNumber` string: Street number from the subscriber's address.
    - `postalCode` string: Postal or ZIP code from the subscriber's address.
    - `locality` string: City or locality from the subscriber's address.
    - `region` string: State, province, or region from the subscriber's address.
    - `country` string: Country from the subscriber's address.
    - `streetNumberSuffix` string: Suffix attached to the street number, such as the A in 123A Main Street.
    - `birthdate` string: Subscriber's date of birth in YYYY-MM-DD format.

## Response `200`

Returns match strength for each evaluated subscriber attribute.

- 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.

## 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)