> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payer Phone Number Lookup

> How payerName resolves to a phone number on POST /v1/requests.

Payer phone number lookup is an opt-in capability your account team enables. When it's on, you can submit a request with a `payerName` but no `phoneNumber`, and SuperDial will look up the dialing number for you. When it's off, every request must supply `phoneNumber` directly.

<Note>
  Lookup is **off by default**. Ask your account team if you'd like it turned on. Without it, the rest of this page doesn't apply; `phoneNumber` stays in `requiredInputs.fields` and you supply it on every request.
</Note>

## How it works

With lookup enabled on your account:

| What you send in `inputs`                                                                    | What happens                                                                                                                                       |
| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payerName` only                                                                             | SuperDial looks up the dialing number and dials it. The matched payer and number come back under `payerLookup` (`phoneNumberSource: "superdial"`). |
| `payerName` + `phoneNumber`                                                                  | Your number is dialed as-is. Lookup still runs to identify the payer, but your number wins (`phoneNumberSource: "input"`).                         |
| `payerName` + `phoneNumber` + [`useMatchedPayerPhone: true`](#choosing-which-number-to-dial) | SuperDial dials its **matched** number instead of yours, falling back to your number if no match is found.                                         |
| Neither                                                                                      | No lookup.                                                                                                                                         |

<Note>
  `payerLookup` is now returned on **every** created request (and on reads), not only when you omit `phoneNumber`. When no payer number is dialed, its `matched*` fields are `null` and `phoneNumberToUse` echoes the number you supplied.
</Note>

## Choosing which number to dial

By default, a `phoneNumber` you supply is always dialed as-is: SuperDial never overrides a number you provided. Set **`useMatchedPayerPhone: true`** on the request body (a top-level field, alongside `schemaId` and `inputs`) to tell SuperDial to dial its own matched payer number instead, even when you supplied one:

* **Match found:** SuperDial dials the matched number. `payerLookup.phoneNumberToUse` is the matched number and `phoneNumberSource` is `"superdial"` (SuperDial's payer directory) or `"phoneBook"` (a per-client override configured for your account).
* **No match:** SuperDial falls back to the number you supplied and dials it as-is (no error). `phoneNumberSource` is `"input"`.

`useMatchedPayerPhone` requires payer phone number lookup to be enabled on your account; it's ignored otherwise.

### Where to put the flag

`useMatchedPayerPhone` is a **sibling of `schemaId` and `inputs`** — not a field inside `inputs`. Putting it inside `inputs` has no effect.

```json theme={null}
{
  "schemaId": "fWxzG4nqtpHsJxS5Lm3q",
  "inputs": {
    "payerName": "Sample Insurance Co",
    "memberId": "TEST123456789",
    "phoneNumber": "2125551234",
    "providerNpi": "1234567890",
    "dateOfService": "2026-03-15"
  },
  "useMatchedPayerPhone": true,
  "internalId": "claim_internal_456"
}
```

<Warning>
  Don't nest it under `inputs`. This is **wrong** and SuperDial will dial your supplied `2125551234` as-is:

  ```json theme={null}
  {
    "schemaId": "fWxzG4nqtpHsJxS5Lm3q",
    "inputs": {
      "payerName": "Sample Insurance Co",
      "phoneNumber": "2125551234",
      "useMatchedPayerPhone": true
    }
  }
  ```
</Warning>

As a full call:

```bash theme={null}
curl -X POST https://robodialer-service-api-9nc4t1p9.uc.gateway.dev/v1/requests \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "schemaId": "fWxzG4nqtpHsJxS5Lm3q",
    "inputs": {
      "payerName": "Sample Insurance Co",
      "memberId": "TEST123456789",
      "phoneNumber": "2125551234"
    },
    "useMatchedPayerPhone": true,
    "internalId": "claim_internal_456"
  }'
```

With a match found, the response reports the matched number as the one that will be dialed — your `2125551234` is echoed back under `inputPhoneNumber` but not used:

```json theme={null}
{
  "requestId": "8bF7xK2mP9qR4sT6uV0w",
  "requestBatchId": "pH9kJ2lM4nB6vC8xZ7Qr",
  "internalId": "claim_internal_456",
  "payerLookup": {
    "inputPayerName": "Sample Insurance Co",
    "inputPhoneNumber": "2125551234",
    "matchedPayerName": "Sample Insurance Company, Inc.",
    "matchedPayerPhone": "8005551234",
    "phoneNumberToUse": "8005551234",
    "phoneNumberSource": "superdial"
  }
}
```

In a [batch](/guides/creating-a-request#batch), the flag goes **inside each request entry** — it is not a batch-level setting, so set it on every entry you want it to apply to:

```json theme={null}
{
  "requests": [
    {
      "schemaId": "fWxzG4nqtpHsJxS5Lm3q",
      "inputs": { "payerName": "Sample Insurance Co", "memberId": "TEST123456789", "phoneNumber": "2125551234" },
      "useMatchedPayerPhone": true,
      "internalId": "claim_001"
    },
    {
      "schemaId": "fWxzG4nqtpHsJxS5Lm3q",
      "inputs": { "payerName": "Sample Insurance Co", "memberId": "TEST987654321", "phoneNumber": "2125551234" },
      "internalId": "claim_002"
    }
  ]
}
```

Here `claim_001` dials SuperDial's matched number (falling back to `2125551234` if there's no match), while `claim_002` dials `2125551234` as-is.

<Note>
  You only need `useMatchedPayerPhone` when you're **also** sending `phoneNumber`. If you omit `phoneNumber` entirely, SuperDial already dials its matched number and the flag changes nothing.
</Note>

## The response

`payerLookup` is a six-field block, always present on the `POST /v1/requests` response (and on [reads](/guides/reading-requests)). When SuperDial dials a matched payer number, it looks like this:

```json theme={null}
{
  "requestId": "8bF7xK2mP9qR4sT6uV0w",
  "requestBatchId": "pH9kJ2lM4nB6vC8xZ7Qr",
  "internalId": "claim_internal_456",
  "payerLookup": {
    "inputPayerName": "Sample Insurance Co",
    "inputPhoneNumber": null,
    "matchedPayerName": "Sample Insurance Company, Inc.",
    "matchedPayerPhone": "8005551234",
    "phoneNumberToUse": "8005551234",
    "phoneNumberSource": "superdial"
  }
}
```

| Field               | Meaning                                                                                                                                                                                          |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `inputPayerName`    | The `payerName` you sent. `null` if you sent none.                                                                                                                                               |
| `inputPhoneNumber`  | The `phoneNumber` you sent, before any lookup. `null` if you sent none.                                                                                                                          |
| `matchedPayerName`  | The canonical payer SuperDial matched. Populated **only when the matched payer's number was dialed**; otherwise `null`.                                                                          |
| `matchedPayerPhone` | The matched payer's phone. Populated only when it was dialed; otherwise `null`.                                                                                                                  |
| `phoneNumberToUse`  | The number that will actually be dialed. `null` when nothing is dialable.                                                                                                                        |
| `phoneNumberSource` | Where `phoneNumberToUse` came from: `"superdial"` (SuperDial's payer directory), `"phoneBook"` (a per-client override), or `"input"` (the number you supplied). `null` when nothing is dialable. |

The `matched*` fields are populated **only when SuperDial dials its own matched number**: when you omit `phoneNumber`, or when you set `useMatchedPayerPhone: true` and a match is found. If your supplied number is dialed instead, `matchedPayerName` / `matchedPayerPhone` are `null`, `phoneNumberToUse` echoes your number, and `phoneNumberSource` is `"input"`:

```json theme={null}
{
  "payerLookup": {
    "inputPayerName": "Sample Insurance Co",
    "inputPhoneNumber": "2125551234",
    "matchedPayerName": null,
    "matchedPayerPhone": null,
    "phoneNumberToUse": "2125551234",
    "phoneNumberSource": "input"
  }
}
```

The same `payerLookup` block appears on the [read endpoints](/guides/reading-requests) (`GET /v1/requests` and `GET /v1/requests/{requestId}`), so you can read the lookup back later rather than capturing it from the POST response.

## Tips

* **Include `memberId` for Blue Cross Blue Shield (BCBS) lookups.** It affects which regional plan gets dialed.
* **You don't need an exact-string match.** Common variants and acronyms (e.g. `"BCBS"`, `"BCBSMA"`, `"Blue Cross Blue Shield"`) all work.
* **Supply `phoneNumber` to dial a specific number.** By default a supplied number is dialed as-is, regardless of what lookup would pick. To have SuperDial dial its matched number instead while still supplying your own as a fallback, set [`useMatchedPayerPhone: true`](#choosing-which-number-to-dial).

## When lookup fails

| HTTP  | `error` code           | What to do                                                                                                                             |
| ----- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `PAYER_NOT_FOUND`      | The name didn't match any payer. Try a more canonical spelling, or supply `phoneNumber` directly.                                      |
| `500` | `PAYER_LOOKUP_FAILURE` | We matched a payer but couldn't get a phone number, or a temporary lookup error. Retry with backoff, or supply `phoneNumber` directly. |

The `message` field describes what went wrong.