Introduction
DVS (Document Validation Service) is OSIGU's API for automating the lifecycle of medical-administrative documents: classifying them by type, extracting structured data, and validating them against configurable business rules per payer agreement.
This documentation is for engineers integrating their hospital, clinic or billing system directly with DVS.
What you can do with DVS
Send a PDF or image and get the document type back — SADT, Pedido Médico, Anatomia Patológica, OPME, and more.
Run the full extraction + validation pipeline. Get an APPROVED / REJECTED verdict with detailed errors per rule.
Async processing with HMAC-signed callbacks. Verify the signature in any language with our copy-paste snippets.
Standard OAuth2 client credentials grant. One token, multiple endpoints.
Core ideas
Two complementary endpoints
Use classification when you don't know what type of document you have. Use validation when you already know the type (your HIS tagged it) and want to verify it meets the payer's rules. You can also chain both with a single call by passing auto_validate=true to the classifier.
Always async on validation, sync available on classification
Validation includes OCR + structured extraction and rule evaluation — it takes 15-60 seconds. Always returns 202 Accepted immediately and delivers the result via signed webhook. Classification supports both sync (interactive UX) and async modes.
Per-tenant access control by document type and agreement
OSIGU grants each provider explicit access to specific combinations of (document_type, country_code, agreement_code). Default-deny: you can't validate anything until OSIGU configures your access during onboarding.
HMAC-signed webhooks
DVS signs every webhook with HMAC-SHA256 using a secret shared at onboarding. You verify the signature in your receiver before processing. Same mechanism for classification and validation events.
API is versioned with /v1/
All public endpoints live under /v1/. Additive changes won't bump the version; breaking changes get /v2/ with a 6-month coexistence window.
Who this is for
DVS is built for providers who need any of the following:
- Hospitals and clinics that want to validate medical documents (TISS guides, medical orders, pathology reports, OPME requests, etc.) before submitting to a payer.
- Billing systems that want to flag documents with missing or invalid fields before triggering reimbursement.
- HIS integrations that already classify documents internally but want OSIGU's extraction + validation engine without rebuilding it.
If you're consuming DVS through RCM or another OSIGU product, this documentation is not the entry point — it's intended for direct API integration.
Environments
DVS provides two independent environments. Build and validate against sandbox first — every code sample in this documentation defaults to sandbox.
DVS API: https://dvs-ingestion-api.sandbox.osigu.com
OAuth token: https://sandbox.osigu.com/v1/oauth/token
Integration testing. Non-billable. Use while building.
DVS API: https://dvs-ingestion-api.osigu.com
OAuth token: https://api.osigu.com/v1/oauth/token
Live traffic. Real validations, real billing. Switch after sandbox is green.
Each environment has its own DVS host and its own OAuth token endpoint. Credentials are also environment-scoped — your sandbox client_id will not work against the production OAuth endpoint, and vice versa.
Getting started
- 1Sign an integration agreement with OSIGU
OSIGU's commercial team will provision your
client_id,client_secret, webhook secret, and configure your access to specific document types. - 2Implement OAuth2 token retrieval
Use the client credentials grant to get an access token. Cache it for ~50 minutes (default token TTL is 1 hour).
- 3Send your first request
Follow the quickstart to classify or validate your first document in under 5 minutes.
- 4Implement a webhook receiver
For async flows, expose an HTTPS endpoint and verify HMAC signatures. Test locally with ngrok.
Support
For onboarding, secret rotation or production incidents: support@osigu.com.