Per-Payer Required Inputs

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.

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.

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:

{
  "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, 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. Post a batch of payer names and get back the extra inputs each payer requires on top of the schema baseline:

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

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

Same opt-in as above. When the capability is off, this endpoint returns 403 PAYER_REQUIRED_INPUTS_DISABLED.

Get Started

Requests

Schemas

Payers

Per-Payer Required Inputs

What changes

How to handle it

Look up per-payer required inputs up front

​What changes

​How to handle it

​Look up per-payer required inputs up front

What changes

How to handle it

Look up per-payer required inputs up front