Support files

A support file in RCM is a document that backs a charge or an account. The payer requires these as evidence that the services billed actually happened and meet the rules of the negotiated agreement. Without the right support files in the right shape, the payer can refuse to pay.

RCM doesn't interpret these documents itself — it hands them to DVS (Document Validation Service), which classifies the document type (if needed), extracts the structured data, and runs the document content against the rule set configured for the (country, agreement_code) of the account.

What can be a support file

The specific catalogue varies per country and agreement, but typical document types include:

support_file_code	What it is	Where it's commonly used
TISS_GUIDE	TISS standard insurance guide	Brazil (almost every charge)
MEDICAL_ORDER	Medical order / referral	Brazil, LATAM
OPME_REQUEST	Request for special materials (OPME)	Brazil (surgical procedures)
ANATOMIA_PATOLOGICA	Pathology report	Brazil (oncology)
LAB_RESULT	Lab test result	Various
QUIMIO_REQUEST	Chemotherapy authorisation	Brazil (oncology)

Your contract dictates which document types you're authorised to upload, and the agreement-level configuration dictates which are required per charge type before invoicing.

How it gets uploaded

There are two paths, depending on whether your system knows the document type ahead of time:

Path 1 — you know the document type (v1)

This is the canonical flow today. Use POST /v1/support-files/upload with support_file_code explicitly set:

The request is a multipart with two parts — file (binary) and request_data (JSON):

// request_data part — application/json
{
  "support_file_code": "TISS_GUIDE",
  "events": [
    {
      "origin_event_id": "EVT-12345",
      "agreement_code": "DEFAULT",
      "charge_codes": ["CHG-001"]
    }
  ]
}

Notes on the shape:

• events is an array — one upload can back several events at once.
• charge_codes inside each event is optional. Omit to attach at event level (the file supports the whole encounter rather than a specific procedure).
• Don't pass account_id — RCM resolves the account from the event automatically.

RCM stores the file in S3, then immediately sends it to DVS for validation (skipping classification — it already knows what type it is).

A DOCUMENT_VALIDATION_COMPLETED / DOCUMENT_VALIDATION_REJECTED webhook follows in 10–30 seconds.

Path 2 — you don't know the document type (v2)

If your system is grabbing files from a generic inbox (email attachments, scanner uploads, etc.) and doesn't know what type each one is, use POST /v2/support-files/upload with support_file_code omitted from the request_data:

// request_data part — application/json
{
  "events": [
    {
      "origin_event_id": "EVT-12345",
      "agreement_code": "DEFAULT"
    }
  ]
}

RCM hands the file to DVS for classification first:

1. DOCUMENT_CLASSIFICATION_COMPLETED webhook arrives → RCM persists the detected support_file_code on the support file record.
2. RCM then submits it to DVS for content validation.
3. DOCUMENT_VALIDATION_* webhook arrives with the final verdict.

In this mode the endpoint returns 202 Accepted with a document_id you use to correlate the classification and validation webhooks.

You can pass support_file_code to v2 if you do know it — in that case v2 behaves exactly like v1: it skips classification, processes the file synchronously, and returns 204 No Content (no body). The v2 endpoint exists to unify the two paths under a single contract.

Lifecycle

Webhook events

Every state transition that matters for integrators produces a webhook:

Event	Fired by	Means
DOCUMENT_CLASSIFICATION_COMPLETED	v2 upload	DVS detected the document type and associated it. RCM persisted support_file_code.
DOCUMENT_CLASSIFICATION_FAILED	v2 upload	DVS could not classify (low confidence, unsupported type, corrupt file, etc.). File sits in UNCLASSIFIED until manual action.
DOCUMENT_VALIDATION_COMPLETED	v1 + v2 upload	Content passed every applicable rule (validation_status: APPROVED). Charge is now eligible to advance.
DOCUMENT_VALIDATION_REJECTED	v1 + v2 upload	One or more rules failed (validation_status: REJECTED). The errors array lists each failure (field, reason, subreason, reason_key, precision_percentage).

See Webhook events → Validation for the full payload shape and the per-locale error messages.

Storage and retrieval

Once uploaded, support files are stored in private S3. You can fetch them back via:

• GET /v1/accounts/sent-accounts-statuses-details/{accountId} — returns the list of files for an account, each entry with a presigned S3 URL valid for ~10 minutes.

Files are immutable — there's no "update support file" endpoint. To replace a file you upload a new one; the old one stays in S3 for audit but is marked superseded.

Common pitfalls

• Uploading without charge_codes when the agreement requires per-charge documentation. The validation will succeed at the file level but the affected charges will be flagged as missing required documents at invoice time. Always pass charge_codes when the document specifically supports one or more charges (TISS guide for a surgery, OPME request for materials).
• Very low-quality scans. DVS needs readable content. Files that are essentially blank, severely cropped, or scanned at too low a resolution come back with UNREADABLE_FILE. Re-upload a cleaner copy.
• Wrong support_file_code in v1 — DVS validates against rules specific to that type, so misclassifying gives misleading rejections. If you're not sure, use v2 with support_file_code omitted and let DVS classify.
• File too large — the upload endpoint accepts up to 200 MB. Larger files return 406 Not Acceptable.