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 three transports at a glance
| Transport | Direction we initiate | Cadence | Best for |
|---|---|---|---|
SFTP | We connect to the partner (outbound poll). Partner or we initiate (inbound poll). | Cron-scheduled. | Daily / hourly batch — most common for state Medicaid + clearinghouses. |
AS2 | Mutual; both sides can push. | Real-time. | Some commercial payers; legacy direct-payer connections. |
REAL_TIME | We HTTP POST to the partner. | Per request. | Real-time eligibility (270/271), real-time auth (278). |
Each partner record carries exactly one connection type. A partner that serves real-time eligibility and batch claims gets two registrations.
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. |
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.
Real-time HTTP
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 SFTP — every partner supports it and it's 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 (SFTP); within seconds (AS2 push, REAL_TIME response). |
Outbound submission produces a submitted record | Yes — visible on /transactions filtered to this partner. |
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| SFTP probe fails: "host key mismatch" | Partner rotated their host key | Confirm with partner; update the known-hosts entry via the gateway admin endpoint. |
| AS2 probe fails: "MDN not received" | Partner is not sending the ack within the timeout | Lengthen timeout; or switch to async MDN. |
| Real-time times out repeatedly on one transaction shape | Partner is slow on full-set 270s | Use service-type-specific 270s; or raise timeout. |
| SFTP works for inbound but not outbound | Outbound directory permissions or path mismatch | Confirm the partner expects files in the path you configured. |