Payer Phone Number Lookup

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.

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.

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`	SuperDial dials its matched number instead of yours, falling back to your number if no match is found.
Neither	No lookup.

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.

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.

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

Don’t nest it under inputs. This is wrong and SuperDial will dial your supplied 2125551234 as-is:

{
  "schemaId": "fWxzG4nqtpHsJxS5Lm3q",
  "inputs": {
    "payerName": "Sample Insurance Co",
    "phoneNumber": "2125551234",
    "useMatchedPayerPhone": true
  }
}

As a full call:

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:

{
  "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, 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:

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

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.

The response

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

{
  "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":

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

The same payerLookup block appears on the read endpoints (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.

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.

Get Started

Requests

Schemas

Payers

Payer Phone Number Lookup

How it works

Choosing which number to dial

Where to put the flag

The response

Tips

When lookup fails

​How it works

​Choosing which number to dial

​Where to put the flag

​The response

​Tips

​When lookup fails

How it works

Choosing which number to dial

Where to put the flag

The response

Tips

When lookup fails