Validation events

Validation events fire for every support file that makes it past the classification stage — both v1 uploads (where you sent support_file_code explicitly) and v2 uploads (where DVS classified it first).

There are two terminal outcomes today:

Event	validation_status	Meaning
DOCUMENT_VALIDATION_COMPLETED	APPROVED	Content evaluated as compliant with all applicable rules.
DOCUMENT_VALIDATION_REJECTED	REJECTED	Content evaluated, but one or more rules failed. The errors array carries the detail.

The envelope is the same for all events (see the envelope). For validation events, entity_type is support_file and entity_id is the support file id.

The two events share the same payload shape — they differ in validation_status and whether errors is populated.

---

DOCUMENT_VALIDATION_COMPLETED

The support file passed every applicable rule (validation_status: APPROVED). errors is an empty array.

Header

Header	Value
X-RCM-Event-Type	DOCUMENT_VALIDATION_COMPLETED

Payload

{
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event_type": "DOCUMENT_VALIDATION_COMPLETED",
  "entity_type": "support_file",
  "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "payload": {
    "document_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "support_file_code": "SF-2025-001234",
    "document_level": "ACCOUNT",
    "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "provider_slug": "clinica-del-norte",
    "origin_event_id": "evt-0001-abcd-1234",
    "validation_status": "APPROVED",
    "precision_percentage": 99.1,
    "analysis_type_applied": "OCR_FULL",
    "document_type_code": "INVOICE",
    "errors": [],
    "validated_at": "2026-06-25T15:34:38.456-06:00"
  },
  "metadata": {},
  "created_at": "2026-06-25T15:34:42.000-06:00"
}

---

DOCUMENT_VALIDATION_REJECTED

The support file was evaluated and one or more rules failed (validation_status: REJECTED). The errors array lists what failed — show these to the end user, they're the actionable feedback.

Header

Header	Value
X-RCM-Event-Type	DOCUMENT_VALIDATION_REJECTED

Payload

{
  "event_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "event_type": "DOCUMENT_VALIDATION_REJECTED",
  "entity_type": "support_file",
  "entity_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "payload": {
    "document_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "support_file_code": "SF-2025-005678",
    "document_level": "CHARGE",
    "account_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "charge_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "provider_slug": "hospital-central",
    "origin_event_id": "evt-0002-efgh-5678",
    "validation_status": "REJECTED",
    "precision_percentage": 42.3,
    "analysis_type_applied": "OCR_PARTIAL",
    "document_type_code": "CLAIM_FORM",
    "errors": [
      {
        "field": "patientName",
        "value": "JHN DOE",
        "reason": "NAME_MISMATCH",
        "subreason": "POSSIBLE_OCR_ERROR",
        "reason_key": "error.document.patient-name-mismatch",
        "precision_percentage": 38.5
      }
    ],
    "validated_at": "2026-06-25T15:35:14.789-06:00"
  },
  "metadata": {},
  "created_at": "2026-06-25T15:35:18.000-06:00"
}

---

Field reference

Both events share this payload:

Path	Type	Optional	Description
payload.document_id	string (UUID)	No	ID of the analyzed document. Same value as entity_id.
payload.support_file_code	string	No	Code of the support file (e.g. SF-2025-001234).
payload.document_level	string	No	Scope of the document: ACCOUNT or CHARGE.
payload.account_id	string (UUID)	No	Account associated with the document.
payload.charge_id	string (UUID)	Yes	Charge; omitted for account-level validations.
payload.provider_slug	string	No	Slug of the provider.
payload.origin_event_id	string	Yes	Identifier of the inbound event that originated the validation.
payload.validation_status	string	No	APPROVED (COMPLETED) or REJECTED (REJECTED).
payload.precision_percentage	number	Yes	Global confidence of the analysis (0–100).
payload.analysis_type_applied	string	No	Type of analysis applied (e.g. OCR_FULL, OCR_PARTIAL).
payload.document_type_code	string	No	Document type code (e.g. INVOICE, CLAIM_FORM).
payload.errors	array	No	List of validation errors; [] when there are none.
payload.validated_at	string (ISO-8601)	No	When DVS produced the verdict.

Each element of errors:

Path	Type	Optional	Description
errors[].field	string	No	Field in the document where the error was detected.
errors[].value	string	Yes	Value read/detected that caused the error.
errors[].reason	string	No	Error reason code (e.g. NAME_MISMATCH). Match against this, not the message.
errors[].subreason	string	Yes	Additional detail sub-reason (e.g. POSSIBLE_OCR_ERROR).
errors[].reason_key	string	Yes	i18n message key for the error.
errors[].precision_percentage	number	Yes	Confidence for this specific field (0–100).

Fields with a null value are omitted from the JSON.