Validate a Document

Use this endpoint when you already know what type of document you have (your HIS tagged it, your operator selected it manually, etc.) and you want DVS to:

1. Extract structured data from the file.
2. Apply the validation rule set configured for (document_type, country_code, agreement_code).
3. Optionally call external validators (CRM lookup, CID validation, eligibility).
4. Return APPROVED / REJECTED with detailed errors.

Always async. Result delivered via signed webhook.

Step 1: Discover what you can validate

Call GET /v1/document-types to list the combinations your tenant is authorized for:

curl https://dvs-ingestion-api.sandbox.osigu.com/v1/document-types \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response:

{
  "items": [
    { "document_type_slug": "PM", "display_name": "Pedido Médico", "country_code": "BR", "agreement_code": "BRADESCO_xxx" },
    { "document_type_slug": "SADT", "display_name": "Guia SP/SADT", "country_code": "BR", "agreement_code": null }
  ],
  "total": 2
}

A null agreement_code means wildcard — you can validate that type with any agreement of that country.

Step 2: Send the validation request

curl

curl -X POST https://dvs-ingestion-api.sandbox.osigu.com/v1/provider-validation-requests \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: val-$(uuidgen)" \
  -d "{
    \"file\": {
      \"content_base64\": \"$BASE64\",
      \"mime_type\": \"application/pdf\"
    },
    \"document_type\": \"PM\",
    \"country_code\": \"BR\",
    \"agreement_code\": \"BRADESCO_xxx\",
    \"external_ref_id\": \"ORDER-12345\"
  }"

Python

import httpx, uuid

def validate_document(access_token, base64_content, doc_type, agreement_code, external_ref_id):
    response = httpx.post(
        "https://dvs-ingestion-api.sandbox.osigu.com/v1/provider-validation-requests",
        headers={
            "Authorization": f"Bearer {access_token}",
            "Idempotency-Key": f"val-{uuid.uuid4()}",
        },
        json={
            "file": {"content_base64": base64_content, "mime_type": "application/pdf"},
            "document_type": doc_type,
            "country_code": "BR",
            "agreement_code": agreement_code,
            "external_ref_id": external_ref_id,
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

Step 3: Handle agreement_code resolution

If your tenant has...	And you...	Result
One access for the doc type	Omit agreement_code	DVS auto-resolves to that single agreement. agreement_resolution: "auto_unique" in response.
Multiple accesses for the doc type	Omit agreement_code	422 with available_agreements in additional_information. Resubmit with explicit value.
Wildcard access (null)	Omit agreement_code	DVS uses the wildcard rule set. agreement_resolution: "wildcard" in response.
No access for the doc type	Any	403 071-403-document-type-not-allowed.

Step 4: Wait for the webhook

{
  "event_type": "validation.completed",
  "data": {
    "validation_request_id": "660e8400-...",
    "final_status": "APPROVED",
    "summary": {
      "total_validations": 13,
      "validations_passed": 12,
      "validations_failed": 0,
      "validations_skipped": 1
    },
    "errors": [],
    "external_validations": [...]
  }
}

See validation.completed for the full payload schema and how to interpret final_status.

Common patterns

Don't double-classify

If you already have a validation_request_id from auto_validate=true chaining, don't also call this endpoint with the same document. You'd pay extraction + validation twice.

Set available_fields_for_ai_analysis only if needed

By default DVS runs all rules. The available_fields_for_ai_analysis parameter is an opt-in filter to restrict which fields are extracted and validated. Use sparingly — if you exclude critical fields, the validation can miss real issues.

REJECTED ≠ error

final_status=REJECTED is a successful operation that gives you a negative verdict. Treat it as actionable information, not a failure.