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

<Note>
  **`phoneNumberToUse` is the field to read for the dialed number.** The separate `to` field on a read is present only when the number was one you supplied, that is when `phoneNumberSource` is `"input"`. When SuperDial dialed a number from its own directory (`"superdial"` or `"phoneBook"`), `to` is omitted, and so is the per-call `contributingCalls[].to`. `phoneNumberToUse` is populated in every case and is available as soon as the request is created, before any call completes.
</Note>

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.