What this request does
The XLSX list validation request sends an email list to ListCleaner as multipart form data. It is intended for CRM exports, newsletter databases, lead files and other structured datasets that contain one column of email addresses. The API preserves the uploaded dataset for the cleaning workflow while the mapping field identifies which column should be validated.
An XLSX workbook must contain exactly one worksheet; multi-sheet workbooks are rejected rather than partially processed. A successful upload returns a list UID. Store that UID with your own job record because it is the stable reference used to inspect processing status and download the cleaned results. Uploading creates an asynchronous job: the initial response confirms acceptance, not completion.
How to use /upload_list
Export a valid XLSX file and make sure the email column has a recognizable header.
Send the file, the __auto__ mapping value and an optional human-readable reference.
Poll the list-status endpoint and download results only after processing has completed.
Headers, parameters and fields
| Name | Location | Required | Description |
|---|---|---|---|
X-User-Email | Header | Yes | Email address belonging to the ListCleaner API account. |
X-Api-Key | Header | Yes | Secret API key for the authenticated ListCleaner account. |
file | Multipart body | Yes | XLSX file containing the email list. Maximum 100 MB and 1,000,000 data rows. |
mapping | Multipart body | Yes | Email column header. Use __auto__ to let the XLSX normalizer detect the email column. |
reference | Multipart body | No | A label such as a campaign, source or month that helps identify the job later. |
Response behavior
- The response confirms that the job was created.
- The uid value identifies the list in later status and download calls.
- records_total reports the accepted data-row count when available.
Execute this request
Edit the request values, then send a live authenticated request to ListCleaner. The HTTP status and duration appear in the response bar, with the actual API response body directly below. File endpoints provide a download link instead of printing binary data.
The live API response will appear here.
Code examples in 10 languages
After credentials are entered above, every example includes the actual account email and API key so the copied request can run immediately. Clear the credentials to return to placeholders.
Use cases and best practices
Common use cases
- Validate a XLSX export before importing it into an email platform.
- Clean CRM contacts before a migration or re-engagement campaign.
- Automate recurring list-quality checks from a backend data pipeline.
Recommended implementation practices
- Upload from a trusted backend instead of exposing API credentials in browser code.
- Retain the returned UID and your own reference together.
- Do not treat upload acceptance as cleaning completion.
- Validate the file structure before consuming credits on a large production upload.
Upload an XLSX email list questions
Answers to common implementation, security and response-handling questions for this specific request.
How should the email column be selected for an XLSX file?
Use __auto__ for supported email-column detection, or provide the email header when your integration controls the workbook structure. The mapping value must resolve to the column that contains the addresses to clean.
What happens after the XLSX upload succeeds?
ListCleaner creates an asynchronous cleaning job and returns its UID. Use the status request to follow the job before requesting result files.
Can I upload an XLSX file directly from frontend JavaScript?
The API accepts the request, but production integrations should proxy uploads through a trusted backend so the API key is not exposed to website visitors.
What are the bulk upload limits?
The documented limit is 100 MB and up to 1,000,000 data rows per upload. Validate limits and file structure before submission.