Skip to main content
This guide details how to exchange data with Lead via SFTP, including the steps for file submission, processing, integration testing, and go-live readiness.

​
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.
Details on which files you should submit for your use-case can be found at Program Files.
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.
All header values are case-sensitive. Please ensure you are following the case definitions as described in each file schema. As an example, all Customer File Schema headers are lower-case, meaning client_customer_id as a header value will pass validation, but CLIENT_CUSTOMER_ID will not.

​
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.
Unless the file type requires all entries daily, do not upload your full dataset on a daily basis. Instead, follow the submission pattern for data that corresponds to each file type in the table below.
Submission RequirementFile Types
New records and changes to existing records onlyCustomer, Customer Relationship, Applications, Accounts, Cards, Authorized Users, Collaterals
New entries only (no updates or unchanged records)Transactions, Sales Responses, ACH files
Updates only (no new entries)Transactions Update
All entries dailyBalances (for accounts not in closed status), Non-posted Transactions (until posted)

​
Daily Submission

Most data files are expected daily with a once-per-day paradigm.
  • 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 once-per-day 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.
See use case examples to determine Day 0 so you can begin testing and uploading files.

​
Batch Submission

The Customer and Customer Relationship files follow a batching paradigm, allowing multiple file submissions per day, each with a designated, distinct batch_id denoted in the filename. Batch ID may be any unique string per batch.
  • If you’re 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 you’re configured to only require the Customer file: Each file needs a unique batch ID.
Ensure that the Batch ID is unique for each batch; re-used batch IDs will not be processed.

​
All or Nothing Processing

Both Daily and Batch files follow an all-or-nothing paradigm. When you submit a file, Lead will attempt to process it in its entirety. If any schema or business validation errors are found, 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.
We do not support partial file processing.

​
Workflows

Files submitted to Lead are processed in grouped workflows. Workflows are groups of files that are processed together — within a workflow, for a given day (or batch). Within a workflow, either all files will be processed successfully, or none. Even if errors pertain to a single file, Lead will not successfully process the set of files until the entire workflow can be processed together. File processing is organized into the following workflow categories:
WorkflowFilesFile Naming Convention
CustomerCustomer and Customer Relationship<Batch_id>_<File_Type>_<Version>.csv
ComplianceApplications, Accounts, Cards, Authorized Users<Date>_<File_Type>_<Version>.csv
FinancialBalances, Transactions, Collaterals, Non-posted Transactions, Transactions Update<Date>_<File_Type>_<Version>.csv
SalesSales Request (Lead), Sales Response (Client)<Date>_<File_Type>_<Version>.csv
DocumentsPDF, JPG, JPEG Documents referenced within file data schemas.<Date>_<Unique_Id>_<DocumentType>_<Version>.<FileExtension> Suggested naming convention, but any string file name is sufficient for the Documents directory.
Best practice is to upload all of the files in a given workflow (e.g., Customer and Customer Relationship file), wait for validation of those files, then move on to submitting files in the next workflow.
Consider Your Program Setup
You might be configured for Lead to only expect a subset of files for a given workflow. For example, if your program does not use the Applications or Authorized Users file, then your compliance workflow will only consist of the Accounts and Cards files
A Note About SalesIf your program is a credit-based program where Lead is originating receivables (e.g. a credit card or a term loan product), then we will also perform a sales handshake. This workflow runs after the Financial workflows pass validations for a given day. At that point, Lead then generates a Sales Request file for which you can then submit a Sales Response file accordingly. See this page for more details

​
Workflow Resubmission

Let’s say you submit the Applications, Accounts, Cards, and AU files, each with a V1 version. There is an error in the Cards file, so you receive an alert from Lead, indicating that the cards file needs to be re-submitted. Once you re-submit the Cards file with a V2 version, Lead will wait for a few minutes to see if you will be submitting any additional compliance files, and then begin processing the following set of files as a single workflow: [V1 Applications, V1 Accounts, V1 Authorized Users ,V2 Cards]. If this workflow processes successfully, you will receive a success alert for all four files. Once a workflow is processed successfully, no more submissions for the same Date (or Batch) may be submitted.

​
Resubmitting Files

If a file or workflow receives an Error alert, you must resubmit it for Lead to process the files. Some files are processed as workflows rather than standalone files. If a workflow fails, multiple submitted files may need resubmission. In order to resubmit 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.
Resubmitting 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

File SchemasEach file type you submit has a defined data schema outlining all fields, requirements, and data types. Please consult the specific schema documentation for each file (e.g., Accounts Data Schema, Transactions Data Schema). You should familiarize yourself deeply with the file schemas.
Files in SFTPOnce we’ve provisioned your SFTP access, you may need to submit a first file before you can view the directory.
Escaped JSONWhen a field requires JSON data within a CSV, the JSON string must be enclosed in double quotes, and any internal double quotes must be escaped by doubling them. Refer to the individual data schema pages for fields requiring this format.