Requests a pre-signed S3 URL to upload a bulk pre-qualification data file. Once you have the upload URL, PUT your file bytes directly to S3 — no API key is needed for the S3 upload itself.
File size:
- Files under 100 MB: a single
uploadUrlis returned (uploadType: single) - Files 100 MB–200 MB: multipart upload URLs are returned (
uploadType: multipart). Upload each part to its correspondinguploadUrl, collect theETagfrom each S3 response header, then callPOST /prequalification/bulk/multipart/complete.
Accepted file types: CSV, XLS, XLSX
Maximum file size: 200 MB
File format: one row per merchant, with a header row. CSV, XLS and XLSX files use the same columns. For XLS/XLSX, the first sheet is read. A CSV can be UTF-8 or Windows-1252 (the Excel default for CSV). The file is not limited to the columns below: any other columns are kept and returned unchanged in the results file. If the header row is unusable (a required column is missing, there are no month columns, or the same month appears twice) the whole file is rejected. A problem with a value in a row only declines that row, with an explanation, and processing continues with the next row.
| Column | Required | Description |
|---|---|---|
External Reference | Yes | Your own identifier for the merchant. Returned unchanged so you can match results back to your records. |
CurrencyIsoCode | Yes | GBP. Only GBP is supported. |
CountryCode | Yes | ISO 3166-1 alpha-3 country code of the merchant. Currently only GBR (UK) is supported. A merchant with any other value, including UK, GB or a blank, is declined, the same as on the real-time endpoint. |
TypeOfEntity | Yes | For example Limited Company, Ltd, Partnership, LLP, Sole Trader. Case, spaces, hyphens and underscores are ignored. An unrecognised entity type is declined as unsupported_entity_type. |
| One column per month | Yes | Monthly card sales in GBP. See Month columns below. |
NumberOfTransactions-<month> | No | Number of card transactions in that month. Its <month> part must be written exactly like the month column it belongs to. |
MCCCodes | No | Merchant category codes, comma-separated (for example 5812,5814). |
Month columns: there is one column per month of card sales, and a file can contain any number of months. Each month header is written in one of these formats, in any letter case (JAN-2026 and january-2026 are fine):
Jan-2026(three-letter month name)01-2026(two-digit month number,01to12)January-2026(full month name)
In an Excel file a month header can also be a real date: Excel often converts a typed Jan-2026 into one (shown as Jan-26), and it is read as that month. A header typed as the text Jan-26 is not recognised. Formats can be mixed within a file, and the columns can be in any order. The same month must not appear twice, in any format or letter case (for example Jan-2026 and 01-2026): the file is rejected. Other formats, such as Sept-2026 or 1-2026, are not recognised as month columns.
How months are used:
- A merchant's trading history starts at its first month with sales above zero. Blank or
0months before that month are ignored, so you can leave them empty or zero-fill them. - From that first month onwards every month counts. A blank or
0month after trading started is counted as a month with no sales, which lowers the average. This includes blank months at the end of the file. - The average monthly sales is taken over the months that count.
- The current calendar month is ignored, because it is incomplete.
- Enter sales and transaction counts as plain numbers, for example
12450.50. Do not include currency symbols, thousands separators or spaces:12,450.50,£12450.50and12 450.50are all wrong. A row with a value like this is declined with an explanation, and processing continues with the next row.
A sample file is provided in bulk-prequalification-sample.xlsx; its second sheet, Instructions, repeats these rules. Please use it as the template: the same columns apply whether you send CSV, XLS or XLSX. Header row and first row of its first sheet:
External Reference,company_id,Jan-2026,Feb-2026,Mar-2026,Apr-2026,May-2026,Jun-2026,NumberOfTransactions-Jan-2026,NumberOfTransactions-Feb-2026,NumberOfTransactions-Mar-2026,NumberOfTransactions-Apr-2026,NumberOfTransactions-May-2026,NumberOfTransactions-Jun-2026,CurrencyIsoCode,TypeOfEntity,MCCCodes,SICCodes,CountryCode,BusinessAgeMonths
SAMPLE-001,00000000-0000-0000-0000-000000000001,12450.50,13120.00,14010.75,13580.20,14925.00,15210.40,162,171,180,176,190,194,GBP,Limited Company,"5812,5814",56101,GBR,48
After you upload: processing starts automatically once the upload completes. You find out the outcome in either of two ways:
- Webhook, if you have one registered:
file_processedwhen the results are ready, orfile_failedif the file could not be processed (see the callbacks of this operation). - Polling:
GET /prequalification/bulk/status/{fileId}. Afailedfile includes anerrorMessagesaying why. Download the results withGET /prequalification/bulk/download/{fileId}.
A file is rejected as a whole when its header row is unusable (see above): the error_message / errorMessage says what to fix, and you upload the corrected file as a new request. A bad value in a row only declines that row.
Results file: a UTF-8 CSV with every column you sent, followed by OfferId (unique for each row) and these columns:
| Column | Meaning |
|---|---|
Status | qualified or declined |
DeclineReason | Why a row was declined: insufficient_trading_history, insufficient_monthly_sales, unsupported_mcc, insufficient_transaction_volume, unsupported_entity_type, non_gb_country, non_gbp_currency, ineligible_combination or invalid_value. Empty when qualified. |
DeclineDetail | An explanation in words, for example which cell was not a plain number (invalid_value). Empty otherwise. |
AmountAdvanced, RepaymentAmount, FactorRate, HoldbackPercentage | The offer. Empty when declined. |
ExpiryDate | When the offer expires: 30 days after the file was processed. Empty when declined. |
MonthsOfHistory, AvgMonthlySales | The trading history the decision was based on. |
400Invalid request — missing required fields, unsupported file type, or file too large
401Unauthorized - Missing or invalid API key
403Forbidden - Invalid or deactivated API key
500Internal server error. Please contact support if the issue persists.
