Connection types

Outcome

You pick the right transport for a given partner, configure it correctly on the first try, and know what to expect from each transport when something fails.

Prerequisites

A partner record created (see 2.1 — Onboard a new partner).

The transports at a glance

A partner declares which transport modes it supports per transaction type. The same partner record can carry multiple modes — for example, a clearinghouse offering both BATCH_SFTP for 837/835 and REALTIME_REST for 270/271.

Mode	We initiate	Cadence	Best for
BATCH_SFTP	Outbound write + inbound poll.	One gateway-wide poll interval.	Daily / hourly batch — most common for state Medicaid + clearinghouses.
BATCH_REST	Outbound POST of a batch payload + polled status.	Per submission.	Modern clearinghouses that publish a REST batch endpoint.
BATCH_AS2	Mutual; both sides can push.	Real-time.	Some commercial payers; legacy direct-payer connections.
BATCH_MFT	Outbound to a Managed File Transfer endpoint with receipt verification.	Per submission.	Government / financial-grade MFT counterparties.
REALTIME_REST	Synchronous HTTPS POST.	Per request.	Real-time eligibility (270/271), real-time auth (278).

The partner dialog offers four transport modes: BATCH_SFTP, BATCH_REST, BATCH_AS2 and REALTIME_REST. MFT is chosen as the partner's Protocol, not as a transport mode.

BATCH_SFTP

The most common transport. A partner with Protocol SFTP is edited through Edit on the partner page; the Connection tab shows what is stored, read-only. Every field below is on both.

Server and login — top of the dialog:

Field	Notes
Host	DNS name of the partner's SFTP server.
Port	Blank means 22.
Username	The login the partner provisioned for us. A blank username fails Test connection with MISSING_CONFIG.
Remote path	Read only by Test connection, which lists it (default /). Polling and uploads never read it.

SFTP configuration fieldset. A blank field is left undeclared and the adapter's default applies:

Group	Field	Notes
Inbound	Inbound root directory	Blank is /inbound. Declared directories are relative to it.
Inbound	Inbound sub-folder depth	Single-root walk only, 0–3. Hidden once any inbound directory is declared, because the two are refused together.
Inbound	Add inbound directory → Path, Download extensions, Delete-unread extensions, Remove after ingest	One row per directory. Each declared directory is listed flat and only its download extensions are read; delete-unread extensions are deleted without being read.
Outbound	Default outbound directory	Blank is /outbound. Used for every transaction type unless per-type directories are declared.
Outbound	Add outbound directory → Transaction type, Directory	All or nothing: once one is declared, a type that is not listed is refused, not sent to the default.
Files and batching	Filename mode	default ({txType}_{control}_{timestamp}.edi) or partner-prefix ({partnerCode}_{txType}_{control}_{timestamp}.edi).
Files and batching	Filename prefix (partnerCode)	The prefix partner-prefix uses. Not the registry Partner code at the top of the dialog.
Files and batching	Batch cap (claims per file)	Blank means the default per-file cap, except for envelope profile availity, which has no default: the save is refused without it.
Files and batching	Server key fingerprint	SHA256:…. Blank leaves the host key unpinned, and any key is accepted.
Envelope	Envelope profile	None, claim-md or availity. Decides where the interchange identity on outbound files comes from.
Envelope	Envelope sender ID	The partner-level ISA06, used by the availity profile. The claim-md profile takes ISA06 from each customer's own account and ignores this field.

A refused save shows the refusal at the top of the SFTP fieldset and marks the field it refused. The Connection tab shows the same keys as tables: the inbound policy per directory, the outbound map, the filename mode, the batch cap (or Refused when an availity profile has none), the host-key pin (or Unpinned) and the envelope.

Authentication is not in this dialog. Set an SFTP password or an SFTP private key on the Credentials tab (see 2.3). If the stored row still carries a literal password or private key, the Connection tab shows a warning with Rotate credential; the next save of the connection config drops the literal.

Polling is not configured per partner. The scheduled inbound poll is switched on for the whole gateway by the platform team, and on each tick it lists every active partner whose transport modes include BATCH_SFTP. There is no per-partner schedule, archive directory or outbound trigger field.

Availity

The values for the shared Availity partner (host, directories, envelope profile and sender, batch cap, the open vendor questions) are in the engineering runbook, section RCM-14 of docs/operations/runbook-rcm.md in the repository. Use those, not values copied from an older page.

Probing an SFTP partner exercises:

Common failures:

Failure	Cause
connection refused	Wrong host or port; or partner firewall has not allowed our outbound IP.
authentication failed	Credentials wrong or expired.
permission denied (path)	Username does not have read on the remote path.

BATCH_REST

For clearinghouses and payers that publish a modern REST batch endpoint instead of SFTP. Configuration:

Field	Notes
Base URL	Partner's REST root (e.g. https://api.partner.example/v1).
Auth method	bearer, basic, oauth2_client_credentials, mTLS.
Credentials	Vaulted bearer / client secret / client cert.
Submission endpoint	Path for the outbound batch POST.
Status endpoint	Path for polling submission status.
Cron schedule	When to poll for inbound responses (response files often surface via the same status endpoint).

BATCH_MFT

For Managed File Transfer counterparties — common in state Medicaid gateways and federal exchanges. Adds a partner-signed receipt step on top of the file delivery. Configuration:

Field	Notes
Endpoint URL	Partner's MFT submission URL.
Auth method	oauth2_client_credentials is the most common.
Client credentials	Client ID + vaulted client secret, or a JWT private key.
Receipt verification key	Partner's published public key — vaulted. The platform refuses to mark a submission complete until the signed receipt verifies.
Outbound directory / endpoint	Where we drop submitted files.
Cron schedule	Polling cadence for receipts and inbound responses.

BATCH_AS2

Less common in modern integrations but still used by some commercial payers. Configuration:

Field	Notes
Endpoint URL	Partner's AS2 receiver URL.
Our certificate	Our public certificate for partner-side encryption.
Partner certificate	Partner's public certificate we use to encrypt.
MDN	Whether we request a Message Disposition Notification (acknowledgment). Default: synchronous.
Compression	none / gzip; per partner agreement.
Encryption algorithm	Negotiated; commonly aes256-cbc.

AS2 has more failure modes than SFTP because of the certificate handshake. Probing exercises a HEAD or GET against the endpoint plus a small encrypted ping payload.

REALTIME_REST

Used for synchronous transactions — primarily 270/271 eligibility and real-time 278 authorization. Configuration:

Field	Notes
Endpoint URL	The partner's HTTPS endpoint.
Auth method	bearer, basic, mTLS.
Bearer token / username+password / client cert	Vaulted.
Request format	EDI (raw X12 in the request body) or JSON-wrapped (a thin envelope around the X12). Per partner.
Timeout	Default 30s; sometimes raised for slow partners.
Retry policy	Per-request retry count + backoff.

Probing a real-time partner runs a synthetic minimal request (a 270 with a known never-existed member) and confirms a 271 with AAA*N*…*72*… comes back — the partner exists and is responding.

Choosing the transport

When in doubt, use BATCH_SFTP — every partner supports it and it is the most forgiving when one side has an outage.

Validation

Check	Expected
Test connection succeeds for the chosen transport	Yes.
First inbound file appears in /transactions within one cadence cycle	Yes (BATCH_SFTP / BATCH_REST / BATCH_MFT); within seconds (BATCH_AS2 push, REALTIME_REST response).
Outbound submission produces a submitted record	Yes — visible on /transactions filtered to this partner.

Troubleshooting

Symptom	Cause	Fix
BATCH_SFTP probe fails after a host-key pin is set	Partner rotated their host key, or the pin was mistyped	Confirm the fingerprint with the partner; update Server key fingerprint in Edit.
BATCH_AS2 probe fails: "MDN not received"	Partner is not sending the ack within the timeout	Lengthen timeout; or switch to async MDN.
BATCH_MFT submit succeeds but stays awaiting-receipt	Partner's signed receipt has not arrived, or our verification key is stale	Confirm the partner's published receipt-signature public key; re-vault.
BATCH_REST returns 401 after a working period	Bearer token expired, or OAuth2 client credentials rotated	Rotate via Credentials tab.
REALTIME_REST times out repeatedly on one transaction shape	Partner is slow on full-set 270s	Use service-type-specific 270s; or raise timeout.
BATCH_SFTP works for inbound but not outbound	Outbound directory permissions or path mismatch	Confirm the partner expects files in the path you configured.

Next

2.3 — Credential vault & rotation