Caller-Owned IDs and Validate-First Guard for Faster Integrations

Integrators asked a practical question: "How should we populate payer_id, provider_id, patient_id, and place_of_service on score requests?"

The answer is now explicit in docs and examples: these are caller-owned identifiers and codes from your own source systems.

What changed

1) Added mapping templates for common data shapes:

• 837 / clearinghouse style rows
• EHR encounter + charge exports
• internal work-queue rows with tokenized patient IDs

2) Added a default integration guard:

• GET /v1/workflows/{workflow}/schema
• POST /v1/workflows/{workflow}/validate
• only then POST /v1/score

3) Added a funnel metric to track adoption quality:

• % of first successful scores that had a successful validate call first

Why this matters

• Teams can onboard without guessing identifier semantics.
• Agents and SDK clients catch payload issues before consuming scoring calls.
• Operators can measure integration quality instead of just traffic volume.

Recommended rollout pattern

1. Map source columns to the four caller-owned fields once.
2. Make validate-before-score the default path in clients.
3. Alert when preflight-before-first-score drops, then inspect onboarding flows.

References

• Docs home: /portal/docs-home
• Workflow schema + validate: /portal/docs-home#workflow-concept
• Full API docs: /docs