Overview

​

Connectivity for File Delivery

Lead uses SFTP with key-based authentication to ensure the secure transfer of all data.

​

File Formats and Delimiters

Files are typically submitted in CSV format. Use a pipe (|) delimiter to separate data elements, and do not use a comma (,) or semicolon (;) delimiter. Specific data schemas define the required fields, data types, and formatting for each file. To minimize file processing errors, we recommend using an open source CSV parser to confirm the CSV formatting is valid before submitting it to Lead.

​

Data Patterns

• ID Semantics: The client_ prefix denotes a partner-generated unique ID for records being created or updated in Lead. To reference an existing record, use its ID without this prefix. Schema fields for such references may use semantic names (e.g., replaced_by expecting an existing card’s ID) or names indicating the object type (like account_id referencing an account originally defined via client_account_id).
• Updating Data Records may be updated via file. Updating records via file submission means a complete overwrite. Ensure each submission for an existing client_id contains the entire updated record.

​

File Submission and Processing

​

Data Requirements

Depending on the nature of the file, files have differing expectations on what kind of data Lead expects.

​

All or Nothing Processing

All files submitted to Lead follow an all-or-nothing paradigm at the file level. When you submit a file, Lead will attempt to process it in its entirety. If any schema or business validation errors are found within the rows of that file, the entire file will be rejected. Each file type’s data schema page and overview pages outlines a non-exhaustive list of which specific schema and business validations are run for that file type.

​

Workflows

Files submitted to Lead are processed in grouped workflows. Workflows are logical groups of files that are processed together based on their functional category. File processing is organized into the following workflow categories: * For partners onboarded prior to Q2, 2026, the Compliance workflow follow a once-per-day convention, mirroring the Financial workflow. Best practice is to upload all of the files in a given workflow, wait for a Slack Alert with Lead’s processing results for those files, then proceeding with either a version bump and resubmission of the workflow or an upload of your next workflow.

​

Ingestion Paradigms

All files within a workflow are grouped together under specific Ingestion Paradigms, which dictate how the files are validated, processed, and resubmitted. Different file types and program configurations follow different rules for submission frequency and processing logic.

​

Daily Submission

Applies to:

• Financial Workflow
• Sales Workflow
• Compliance Workflow for partners onboarded prior to Q2, 2026

How It Works:

• On any given day T, our system expects a file containing activity for day T-1.
• The filename will reflect date T, but the data inside corresponds to activity from the previous day (T-1).
• Activity is expected to cover the full calendar day: 12:00 a.m. to 11:59:59 p.m. CT on T-1.
• Since the Central Time timezone can change between CST and CDT, we recommend having your code build the calendar day based on the “America/Chicago”. When processing your files, Lead will parse the timestamp with the current “America/Chicago” timezone, and extract the date from the timestamp. We then check that dates included are from T-1 (i.e., the date before the file’s date).

Files following the Daily Submission paradigm follow a sequential submission rule:

• You may only submit Day T+1’s file after Day T’s file has been successfully validated.
• This rule applies even if the file for a given day contains headers only with no activity.

​

Batch Submission

Once you submit a file with a batch_id, Lead will wait five minutes for other files to be delivered with the same batch_id and then begin processing the full batch. Under Batch Submission, files within a workflow are grouped together. Files with no errors or dependencies on erroneous files will be processed successfully. For example - an Accounts file submission within a Compliance workflow may return a success message, even when an error exists in a Cards file uploaded with the same batch_id because no changes to the Accounts file are required. Batch Submission will only return a cross-file validation failure when a file includes a reference to an object that Lead cannot find, either within the same batch, a previous batch, or an API submission. Applies to:

• Compliance Workflow (Applications, Accounts, and Cards files) for programs onboarded from Q2 2026 onward.

Once a workflow is processed successfully, no more submissions for the same Batch may be submitted.

​

Strict Batch Submission

Applies to:

• Customer Workflow (Customer, Customer Relationship)
  • If your program is configured to require the Customer Relationship file: Both files must be submitted with the same batch ID before a batch will begin to process.
  • If your program is configured to only require the Customer file: Each file needs a unique batch ID.

How It Works: Strict Batching allows multiple file submissions per day, distinct by a unique batch_id. In this semantic, the workflow is atomic: all files required for the workflow must pass validation together. Strict Batching differs from Batching in that, if either file has any failures, the entire batch will fail to process, requiring resubmission of the full batch.

• Batching: All files in the workflow must be submitted with the same batch_id to trigger processing.
• Validation: If any file in the batch fails validation, the entire batch is rejected. No data from the batch is persisted.

​

Resubmitting Files

If a file or workflow receives an Error alert, that indicates that Lead has not saved any information contained within the file. You must resubmit it for Lead to process the files.

1. Correct the errors based on the Slack alert.
2. Increment the <Version> in the filename, keeping the same date or batch ID designator from the file name.
3. Resubmit the corrected file to the appropriate SFTP folder.

Restrictions on Resbumitting Successful Files: For Daily file submission workflows, Lead is not able to accept multiple successful submissions for one day. If a success alert is delivered for a day, subsequent submissions for the same date will not be processed. If, for any reason, a record was missed in a daily file’s aggregation, and that file processes successfully, the missed record would need to be included in the subsequent day’s file submission.

​

Reminders