Skip to main content
A schema defines the structured output fields a request returns and which inputs are required to submit one — pass its schemaId on POST /v1/requests to invoke it. Two endpoints make request creation self-service: discover the schemas your account is provisioned for, and look up the input keys each one needs.
EndpointPurpose
GET /v1/schemasList the schemas owned by the account associated with your API key.
GET /v1/schemas/{schemaId}/required-inputsReturn the input keys required to submit a request against a given schema.
Both endpoints use the same bearer-token authentication as the rest of the API. All non-2xx responses use the uniform {error, message, [details]} envelope (see Errors).

​
List your schemas

curl -H "Authorization: Bearer <token>" \
  https://robodialer-service-api-9nc4t1p9.uc.gateway.dev/v1/schemas

​
Response

{
  "schemas": [
    {
      "schemaId": "fWxzG4nqtpHsJxS5Lm3q",
      "name": "Claim Status (Commercial)",
      "requestType": "claim-status"
    },
    {
      "schemaId": "qP2bN8rT6mK1xC3vW9aL",
      "name": "Verification of Benefits",
      "requestType": "vob"
    }
  ]
}
FieldTypeNotes
schemaIdstringPass to POST /v1/requests as schemaId.
namestringHuman-readable label. Falls back to the schemaId when no name is set.
requestTypestringThe kind of extraction this schema produces (e.g. claim-status, vob). Server-derived — useful for filtering the list, but you don’t pass it on POST /v1/requests. It surfaces on RequestResponse.requestType after the request runs.
Schemas that are no longer accessible for your account are filtered out of this list.

​
Look up required and optional inputs

Once you have a schemaId, fetch the input keys it accepts. The response carries two sorted, disjoint lists: requiredInputs.fields (must be supplied or you get INVALID_INPUTS) and optionalInputs.fields (accepted but not required — useful for “build a request” forms that want to surface every accepted key). 
curl -H "Authorization: Bearer <token>" \
  https://robodialer-service-api-9nc4t1p9.uc.gateway.dev/v1/schemas/fWxzG4nqtpHsJxS5Lm3q/required-inputs

​
Response

{
  "schemaId": "fWxzG4nqtpHsJxS5Lm3q",
  "requiredInputs": {
    "fields": [
      "beginningDateOfService",
      "billingProviderName",
      "billingProviderTaxId",
      "claimChargeAmount",
      "memberId",
      "patientDateOfBirth",
      "patientFirstName",
      "patientLastName",
      "payerName",
      "phoneNumber",
      "renderingProviderName",
      "renderingProviderNpi"
    ]
  },
  "optionalInputs": {
    "fields": [
      "memberId2"
    ]
  }
}
Field-name keys are returned verbatim — the same names the POST /v1/requests validator expects in inputs. If SuperDial updates the schema, call this endpoint again (or refresh your cache) before relying on a fixed list in code.
If your account is enabled for payer-phone resolution, phoneNumber moves out of requiredInputs.fields and into optionalInputs.fields for this endpoint — because you can omit it and let SuperDial fill it in from payerName. With resolution off (the default), phoneNumber stays required.
If your account is enabled for per-payer required inputs, some payers require additional inputs that aren’t listed here. Treat this list as the baseline — a request for one of those payers may need more.

​
End-to-end discovery flow

import requests

BASE = "https://robodialer-service-api-9nc4t1p9.uc.gateway.dev"

def list_schemas(token):
    r = requests.get(f"{BASE}/v1/schemas", headers={"Authorization": f"Bearer {token}"})
    r.raise_for_status()
    return r.json()["schemas"]

def schema_inputs(token, schema_id):
    r = requests.get(
        f"{BASE}/v1/schemas/{schema_id}/required-inputs",
        headers={"Authorization": f"Bearer {token}"},
    )
    r.raise_for_status()
    body = r.json()
    return body["requiredInputs"]["fields"], body["optionalInputs"]["fields"]

# Use it
schemas = list_schemas(token)
schema = next(s for s in schemas if s["requestType"] == "claim-status")
required, optional = schema_inputs(token, schema["schemaId"])
print("required:", required)
# ['beginningDateOfService', 'billingProviderName', ..., 'phoneNumber']
print("optional:", optional)
# ['memberId2']
After this you have everything you need to call POST /v1/requests — pass the schemaId and populate every key in required inside the inputs object. The requestType is server-derived; you’ll see it on the response.

​
Errors

Every non-2xx response uses the uniform envelope: 
{
  "error": "MACHINE_CODE",
  "message": "Human-readable description.",
  "details": { /* optional, only on INVALID_INPUTS */ }
}
HTTP codeerror codeWhen
400INVALID_REQUESTThe schemaId path parameter was empty, contained /, started with _ or ., or exceeded 1500 characters. Only applies to the required-inputs endpoint.
401(gateway envelope)Bearer token missing, malformed, or expired. The gateway uses {code, message}, not the envelope above.
404SCHEMA_NOT_FOUNDNo schema with that ID exists for your account, or it has been retired and is no longer accessible.
404ACCOUNT_NOT_FOUNDThe API key resolves to an account that no longer exists. Contact support.
500INTERNAL_ERRORUnexpected server failure. Retry once; escalate if persistent.

​
Example error responses

// 400 — invalid schemaId path parameter
{
  "error": "INVALID_REQUEST",
  "message": "The provided schemaId is invalid."
}

// 404 — schema not found, or has been retired
{
  "error": "SCHEMA_NOT_FOUND",
  "message": "No schema with that ID exists for your account."
}

// 404 — API key doesn't resolve to a provisioned account
{
  "error": "ACCOUNT_NOT_FOUND",
  "message": "No account is associated with this API key. Contact support if you believe this is an error."
}

// 500 — unexpected server failure
{
  "error": "INTERNAL_ERROR",
  "message": "An internal error occurred. Please try again or contact support if the problem persists."
}
For the full response and parameter schemas, see the API Reference → Schemas.