Request an upload URL for a bulk pre-qualification file

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 uploadUrl is returned (uploadType: single)
  • Files 100 MB–200 MB: multipart upload URLs are returned (uploadType: multipart). Upload each part to its corresponding uploadUrl, collect the ETag from each S3 response header, then call POST /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.

ColumnRequiredDescription
External ReferenceYesYour own identifier for the merchant. Returned unchanged so you can match results back to your records.
CurrencyIsoCodeYesGBP. Only GBP is supported.
CountryCodeYesISO 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.
TypeOfEntityYesFor 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 monthYesMonthly card sales in GBP. See Month columns below.
NumberOfTransactions-<month>NoNumber of card transactions in that month. Its <month> part must be written exactly like the month column it belongs to.
MCCCodesNoMerchant 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, 01 to 12)
  • 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 0 months 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 0 month 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.50 and 12 450.50 are 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_processed when the results are ready, or file_failed if the file could not be processed (see the callbacks of this operation).
  • Polling: GET /prequalification/bulk/status/{fileId}. A failed file includes an errorMessage saying why. Download the results with GET /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:

ColumnMeaning
Statusqualified or declined
DeclineReasonWhy 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.
DeclineDetailAn explanation in words, for example which cell was not a plain number (invalid_value). Empty otherwise.
AmountAdvanced, RepaymentAmount, FactorRate, HoldbackPercentageThe offer. Empty when declined.
ExpiryDateWhen the offer expires: 30 days after the file was processed. Empty when declined.
MonthsOfHistory, AvgMonthlySalesThe trading history the decision was based on.
Body Params

File metadata for generating the upload URL

Request body for generating a pre-qualification file upload URL

string
required

Name of the file to upload (including extension)

string
enum
required

MIME type of the file

Allowed:
integer

Size of the file in bytes. Required for files over 100 MB to trigger multipart upload mode. Maximum 200 MB.

Headers
string
required

Your API key for authentication.

Responses

400

Invalid request — missing required fields, unsupported file type, or file too large

401

Unauthorized - Missing or invalid API key

403

Forbidden - Invalid or deactivated API key

500

Internal server error. Please contact support if the issue persists.

Callbacks
Language
Credentials
Header
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json