File based integration vs API: when your clients cannot integrate

A file based integration is when a client's system exports a file on a schedule and you turn it into records in your product. An API integration is when the two systems exchange JSON directly over HTTP. For implementation and integration leads at B2B software companies, the practical answer is: ask for the API when the client has an integration team and a budget for it, and accept a recurring file feed in the other four out of five cases, because the scheduled export already exists and the API integration does not. This post explains both, gives a five factor decision table, and shows how a file feed delivers API quality data without the client building anything.

To see what a client's export looks like after mapping and validation, drop one real client file here and watch it become clean JSON in your browser.

What each one is

API integration

The client's system calls your endpoint, or yours calls theirs, with JSON in a shape both sides agreed on. Changes arrive as they happen or on a short interval. Authentication is a token, errors are HTTP status codes, the contract is a schema document. When it exists on both sides, it is the cleanest way to move data. Your API existing is not enough. The client has to build and run the code that calls it.

File based integration

The client's system produces a file, usually CSV or Excel, on a schedule: nightly, weekly, every pay period. The file reaches you over SFTP or as an email attachment. Your side parses it, maps the client's columns to your schema, validates every row, and loads the result. The contract is whatever the client's export produces, which is why mapping is done per client. When it is done well, the output is identical to what an API would deliver: JSON in your schema, arriving at your endpoint. The long form is in Recurring client file feeds: the complete guide.

Why enterprise clients default to scheduled exports

"Just use our API" sounds reasonable from inside a software company. From the client's side it means: find an engineer, read your documentation, build and test an integration, get it through security review and change control, and then own it when it breaks. In most enterprise clients that request joins a backlog that is measured in quarters. The scheduled export, by contrast, is already there.

• HRIS. Workday, ADP, UKG, BambooHR, Paylocity and most custom HR systems ship with scheduled report exports to SFTP. An HR analyst can set one up without IT. An outbound integration to your product needs a project.
• Payroll. Pay period files are the standard interface between payroll providers and everything downstream. They are produced on the payroll calendar and nobody wants to change that calendar for one vendor.
• Benefits. Carriers, TPAs and benefits administrators exchange eligibility and census files. The file formats are old, well understood and approved by compliance. An API, where one exists, is often behind a partnership agreement.
• Inventory and retail. Suppliers and distributors send price lists and stock files. The ERP exports them; the person sending them is in operations, not engineering.
• Carriers and logistics. Shipment and tracking files move between partners on schedules set years ago. The carrier's integration team has bigger partners than you.

In each case the export is built, scheduled and already approved by the client's security team. A file over SFTP to a known host is a pattern their IT department has signed off a hundred times. A new outbound API call from an internal system to a vendor is a new review. The path of least resistance for the client is the path you receive.

Decision table: API or file feed for this client

Use these five factors on each new client at kickoff. Most clients land clearly on one side after two questions. The point of the table is to make the choice explicit instead of defaulting to a request for the API and discovering three months later that the file was always the answer.

Score it simply. Integration team with a date and no export: ask for the API. Export and no team: accept the file. Both: start with the file so go live does not wait, and let the API follow if change frequency ever demands it. The one factor that overrides the others is real time need. If your product is wrong when the data is six hours old, you need an API or an event stream, and the file is a stopgap.

How a file feed gives you API quality data

The objection to files is usually about quality, not transport. Engineers remember the CSV that broke the import, the date column with three formats, the status code nobody recognised. Those are real, and three parts of a recurring feed exist to handle them and make the output as trustworthy as an API response.

Mapping, once per client

The client's Employee ID, EmpID or Worker_ID maps to your employeeId. The mapping is suggested from the header row and a sample of values, confirmed by your implementation team on the first file, and saved against that client. Every file after that uses it with nobody in the loop. A required field with no source column blocks the feed before it goes live, which is the file equivalent of a schema validation error at integration time. Compare that to an API integration, where the same mapping work happens inside the client's code, where you cannot see it or fix it.

Validation and transforms on every row

Every row is checked against your schema: required fields present, emails valid, dates parse, IDs unique, enum values from your list. Values that are correct but in the wrong shape are fixed by named transforms attached to the field: trim, formatEmail, toNumber, date normalisation. Rows that fail land in an error report with the row number, field, value and reason. That report goes to the client so they fix the export, or your team adjusts the mapping and reprocesses the same file. An API gives you a 400 response with one error; a feed gives you the full list for 4,000 rows at once.

A signed JSON webhook into your API

This is the part that makes the two styles converge. When a file has been processed, your endpoint receives an HMAC signed webhook. Your backend verifies the signature, reads the run, and loads the clean records in your schema as JSON. From your application's point of view, this is an API integration: JSON arrives at an endpoint you own, authenticated, with a delivery id for deduplication and retries on failure. The fact that the data started life as an Excel attachment is invisible to your code. The SFTP to webhook guide shows the payload and the signature check line by line.

Hellora, an employee referral platform (formerly EQORefer), onboards clients from more than 30 HR systems this way with FileFeed. Each HR system exports differently; each client is mapped once; the platform receives one schema.

When to insist on an API

Files are not always the right answer, and a good implementation lead knows when to hold the line.

• Your product needs changes in minutes. If a terminated employee must lose access now, or a stock level must update before the next order, a nightly file is wrong by design. Ask for the API or an event feed, and use a file only for the initial load.
• The data is transactional and bidirectional. If you write back to the client's system and need confirmation per record, you need request and response semantics. Files can carry results back, but the loop is slow.
• The client is a platform with a published API and no export. Some modern systems expose everything through an API and have no scheduled export. Then the file would be something they build for you, which is the same project as the integration.
• The client already has an integration team on your project. If they are building, let them build to the API. A file feed is for clients who are not.

Even then, the first load is usually a file. The full roster or history exists as an export today; the API carries changes from go live onwards. Treat them as initial load and ongoing sync, not as competitors.

How to offer both without doubling the work

Supporting files and an API does not mean two integrations to maintain, if you design one schema and put both paths in front of it.

1. Define the schema once. Field names, types, required fields, allowed values, uniqueness. This is the contract for both the API and the feed. Keep it as small as the product needs.
2. Build one ingestion endpoint. Your API accepts records in that schema. The file feed delivers records in that schema to the same endpoint, or to a webhook that calls the same code. One upsert, one set of business rules.
3. Put the translation layer outside your codebase. Per client mapping, validation and transforms live in the feed platform's configuration, not in your application. Your engineers never write a parser for a client.
4. Give clients the choice at kickoff. Use the decision table. Clients with an integration team get the API documentation. Clients with an export get SFTP credentials or an inbound email address with a sender allow list, and a request for one real file.
5. Operate from one view. Whether a record came by API or by file, the implementation team should see when it arrived, what passed and what failed. For files that is the feed's run history with reprocess.

In FileFeed the file side of that design is the product: hosted SFTP, client hosted SFTP or email intake for CSV and Excel, mapping suggested and confirmed once per client, per row validation with error reports, built in transforms, an HMAC signed JSON webhook, and a full run history with reprocess. It costs $700 per month, flat, for up to 20 client connections, billed monthly, with no per row pricing, so a client that sends a bigger file does not change the bill. Your API stays exactly as it is.

Frequently asked questions about file based integration vs API

What is file based integration?

File based integration is when one system exports data as a file, usually CSV or Excel, on a schedule, and another system reads that file and loads the records. The file moves over SFTP or email. Done properly it includes mapping the sender's columns to the receiver's schema, validating every row, and delivering the result to the receiving application, so the output is clean records rather than a raw file.

Is an API always better than a file transfer integration?

No. An API is better when both sides have built to it and the data needs to move in near real time. A file is better when the client already has a scheduled export, has no integration team available, moves thousands of rows at a time, and nightly freshness is enough. Most enterprise onboarding fits the second description.

Can a file feed deliver data to our API?

Yes. A recurring file feed ends in a signed JSON webhook to an endpoint you own. Your backend verifies the HMAC signature and loads the records in your schema. From the application's side it looks like any other authenticated API call, and your existing ingestion code can be reused. FileFeed delivers this way for every processed file.

How do we handle a client whose export format changes?

With a mapping confirmed per client, a renamed or missing required column fails validation with a clear message and nothing is delivered. Your implementation team updates the mapping for that client and reprocesses the same file. Optional columns that change show up in the error report so you can decide. The client does not need to resend anything and your engineers do not deploy anything.

What should we ask the client for at kickoff?

Three things. One real file from their system, not a template or a sample made for you. The schedule: how often it is produced, at what time, and what late means. A named contact who can change the export if a required field is missing. With those you can confirm the mapping, test the webhook and run the first file within the kickoff week. If they have an integration team with a date for your API instead, send the documentation and skip the file.

Do clients need to change their export to match our template?

No, and asking them to is the most common way to lose weeks. The mapping and transform layer exists so the client keeps sending the export their system already produces. Column names, date formats and status codes are absorbed on your side, once per client. The only time you go back to the client is when a required field is not in their export at all, and the validation report tells you exactly which one.

Decide with one real file

Before the next kickoff, run the decision table on the client, and if it points to a file, ask for one real export. Drop it into the browser demo to see the suggested mapping, the failing rows and the clean JSON in about a minute, with no account. When you are ready to run it on their schedule, Automated FileFeeds is the product version of this post, at $700 per month, flat, for up to 20 client connections, billed monthly. Or book a demo and bring the file.