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 five transport modes 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.	Cron-scheduled.	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).

BATCH_SFTP

The most common transport. Configuration on the Connection tab:

Field	Notes
Host	DNS name of the partner's SFTP server.
Port	Default 22; partners often use a non-standard port.
Username	The login the partner provisioned for us.
Authentication	Either a password (vaulted) or a private key (vaulted). One only — populated mutually exclusive.
Outbound directory	Remote path we drop submitted files into (e.g. /in, /upload).
Inbound directory	Remote path the partner drops responses into (e.g. /out, /download).
Archive directory	Optional — where we move successfully-fetched files for auditability.
Cron schedule	When to poll the inbound directory. Common: */15 * * * * (every 15 min) or @hourly.
Outbound trigger	Push immediately on submission, or batch on cron.

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 inbound directory.

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: "host key mismatch"	Partner rotated their host key	Confirm with partner; update the known-hosts entry via the gateway admin endpoint.
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