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

# Per-Payer Required Inputs

> Some payers require additional inputs on POST /v1/requests.

Some payers ask for more information than the schema requires of every request. When this capability is enabled for your account, a request for one of those payers must include the payer's additional inputs on top of the schema's required fields.

<Note>
  This is an opt-in capability. Ask your account team to enable it. When it's off, a request's required inputs are exactly the fields returned by [`GET /v1/schemas/{schemaId}/required-inputs`](/guides/schemas#look-up-required-and-optional-inputs).
</Note>

## What changes

Which inputs are required can depend on the payer you name in `inputs.payerName`. A field that's optional for one payer may be required for another, so the schema's required-input list is the baseline, not always the complete list for a specific payer.

## How to handle it

If a request is missing an input a payer requires, `POST /v1/requests` returns `INVALID_INPUTS` with the field listed in `details.missingInputs`, the same response as any other missing required input:

```json theme={null}
{
  "error": "INVALID_INPUTS",
  "message": "Required inputs are missing or invalid.",
  "details": {
    "missingInputs": ["claimNumber"]
  }
}
```

* **Add whatever appears in `details.missingInputs` and retry.** That list tells you exactly what the request still needs.
* **Send every input you have.** Populating the optional fields from the [schema lookup](/guides/schemas#look-up-required-and-optional-inputs), not just the required ones, avoids most payer-specific rejections.
* **Ask your account team** which payers have additional requirements if you'd like to supply them up front.

## Look up per-payer required inputs up front

To avoid the reject-and-retry loop entirely, resolve the payers you're about to submit *before* creating requests with [`POST /v1/schemas/{schemaId}/required-payer-inputs`](/api-reference/schemas/resolve-payer-names-against-a-schema-s-required-inputs). Post a batch of payer names and get back the extra inputs each payer requires on top of the schema baseline:

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"payerNames": ["Sample Insurance Co", "Unknown Payer"]}' \
  https://robodialer-service-api-9nc4t1p9.uc.gateway.dev/v1/schemas/fWxzG4nqtpHsJxS5Lm3q/required-payer-inputs
```

```json theme={null}
{
  "schemaId": "fWxzG4nqtpHsJxS5Lm3q",
  "requiredInputs": { "fields": ["memberId", "payerName", "phoneNumber"] },
  "optionalInputs": { "fields": ["cptCode"] },
  "payers": [
    {
      "inputPayerName": "Sample Insurance Co",
      "matchedPayerName": "Sample Insurance Company, Inc.",
      "payerRequiredInputs": { "fields": ["claimNumber"] }
    },
    {
      "inputPayerName": "Unknown Payer",
      "errorCode": "PAYER_NOT_FOUND",
      "message": "No canonical payer matched 'Unknown Payer'."
    }
  ]
}
```

* The top-level `requiredInputs`/`optionalInputs` are the same schema baseline you get from [`GET /v1/schemas/{schemaId}/required-inputs`](/guides/schemas#look-up-required-and-optional-inputs).
* `payerRequiredInputs.fields` lists **only the additional inputs that payer requires** beyond the baseline, not the full set. Union it with `requiredInputs.fields` to get everything a request for that payer needs. In the example, `Sample Insurance Company, Inc.` needs `claimNumber` on top of the schema's `memberId`, `payerName`, and `phoneNumber`.
* Each `payers` entry lines up 1:1 with the names you sent, in order. A matched entry carries `payerRequiredInputs`; an unmatched entry carries an `errorCode` (`INVALID_PAYER_NAME`, `PAYER_NOT_FOUND`, or `PAYER_LOOKUP_FAILURE`) instead. Check for `errorCode` to tell them apart.
* A payer that fails to resolve doesn't fail the whole call: only that entry reports an error.

<Note>
  Same opt-in as above. When the capability is off, this endpoint returns `403 PAYER_REQUIRED_INPUTS_DISABLED`.
</Note>