Help Center

SFTP File Ingestion

Availability: these features depend on your plan and user role. Contact your Altana account team if they're not visible in your environment.

SFTP File Ingestion lets Altana pull transaction files from an SFTP server you control, screen the transactions in them, and write the results back. It is the inbound path into transaction screening — useful when the system that holds your transactions can drop files on an SFTP server but can't call an API directly.

It pairs with Webhooks and Event Mapping, the outbound side: results can be written back to SFTP, delivered to a webhook, or both.

How it works

  • You register an SFTP endpoint pointing at a server and directory you control.
  • On a schedule (about every 5 minutes), Altana connects to the endpoint and looks in its inbound directory for files matching your pattern.
  • Each new file is parsed into transaction line items and submitted to transaction screening.
  • Results are written to the endpoint's outbound directory. The source file is left in place, or removed, depending on your setting.

Set up an SFTP endpoint

Configure endpoints from Settings → Integrations → SFTP. Each endpoint has:

  • Name — a label to identify the endpoint.
  • Host and Port — the SFTP server address (port defaults to 22).
  • Username and Authentication — a password or an SSH key for Altana to connect with.
  • Inbound path — the remote directory Altana polls for new files.
  • Outbound path — the remote directory Altana writes results to.
  • File pattern — a glob that selects which files to pick up (for example *.json), so unrelated files in the directory are ignored.
  • Data mapping — which parser to apply to the files. Leave it blank to use the standard JSON format described below.
  • Enabled — whether the endpoint is actively polled.
  • Delete source after processing — remove each file once it has been ingested, instead of leaving it in the inbound directory.

File format

With the standard data mapping, Altana reads JSON and JSON Lines (.jsonl, one JSON object per line) files. Each record is a transaction line item to screen:

{ "lineItemId": "po-10481-line-3", /* transaction line-item fields */ }
{ "lineItemId": "po-10481-line-4", /* ... */ }

For the exact line-item fields the standard mapping expects, read the API reference at the /api/nexus/api-docs/ route (see API Documentation). If your files use a different layout, your Altana team can configure a custom data mapping — set the endpoint's Data mapping to that mapping's identifier.

Processing and results

  • One pass per file. A file is picked up once; valid line items are submitted to screening and records that fail to parse are reported so you can correct and re-drop them.
  • Results land in the outbound path as screening completes. The result content matches the transaction screening result described in Webhooks and Event Mapping.
  • For event-driven results, map the Transaction Screening Completed event to a webhook — then you're notified as soon as a run finishes rather than polling the outbound directory.
  • Cadence. Files dropped between polls are picked up on the next cycle, so allow for a few minutes of latency before a file begins processing.

Related