Skip to main content
GET
/
v1
/
api
/
filesupload
/
List Uploaded Files
curl --request GET \
  --url https://base.sanitizeemail.com/v1/api/filesupload/ \
  --header 'X-API-KEY: <api-key>'
{
  "count": 123,
  "next": "<string>",
  "previous": "<string>",
  "results": [
    {
      "id": 123,
      "name": "<string>",
      "file_name": "<string>",
      "file_size": "<string>",
      "status": "pending",
      "user": {
        "id": 123,
        "username": "<string>",
        "email": "jsmith@example.com"
      },
      "file": "<string>",
      "file_tag": "clean",
      "total_email": 123,
      "billable_email": 123,
      "duplicate_email": 123,
      "dropped_email": 123,
      "clean_email_count": 123,
      "bounced_email": 123,
      "bounce_rate": 123,
      "created_date": "2023-11-07T05:31:56Z",
      "is_file_organised": true,
      "progress_percentage": 50,
      "updated_date": "2023-11-07T05:31:56Z",
      "valid_emails_count": 123,
      "invalid_emails_count": 123,
      "clean_email_id": 123,
      "validate_email_id": 123
    }
  ]
}
This endpoint retrieves a paginated list of uploaded files with optional filtering capabilities. You can filter by file purpose and control pagination through query parameters.

​
Query Parameters

All parameters are optional and can be combined:
  • file_tag: Filter files by their processing purpose (clean, validate, analyze)
  • size: Number of files to return per page (1-100, default: 10)
  • page: Page number for pagination (starts from 1)

​
How it Works

1

Set Filter Criteria (Optional)

Choose a file_tag to filter by processing purpose, or omit to see all files
2

Configure Pagination (Optional)

Set size and page parameters to control how many files are returned and which page to view
3

Make Request

Send a GET request with your chosen parameters
4

Navigate Results

Use the next/previous URLs in the response for easy pagination

​
Response Structure

The response follows a standard pagination format:

​
Pagination Meta

  • count: Total number of files matching your query
  • next: URL for the next page (null if on last page)
  • previous: URL for the previous page (null if on first page)

​
File Results

Each file in the results array contains the same detailed information as the individual file endpoint.

​
Example Usage

  • All Files
  • Filter by Purpose
  • Custom Pagination
  • Combined Filters
Get all files with default pagination: bash GET /v1/api/filesupload/

​
File Tag Filtering

Use the file_tag parameter to filter files by their processing purpose:

Clean Files

file_tag=clean Files uploaded for email cleaning and removal of invalid addresses

Validate Files

file_tag=validate Files uploaded for email validation and deliverability checking

Analyze Files

file_tag=analyze Files uploaded for detailed email analysis and insights

​
Response Example

{
  "count": 7,
  "next": "https://base.sanitizeemail.com/v1/api/filesupload/?file_tag=validate&page=3&size=6",
  "previous": "https://base.sanitizeemail.com/v1/api/filesupload/?file_tag=validate&page=1&size=6",
  "results": [
    {
      "id": 745,
      "name": "Customer Email List",
      "file_name": "customers.csv",
      "file_size": "328",
      "status": "validated",
      "user": {
        "id": 100,
        "username": "asim",
        "email": "cool@gmail.com"
      },
      "file": "https://s3.us-east-1.amazonaws.com/sanitizeemail/email_validation_files/customers_uJWaJWs.csv",
      "file_tag": "validate",
      "total_email": 8,
      "billable_email": 4,
      "duplicate_email": 4,
      "dropped_email": 0,
      "clean_email_count": 4,
      "bounced_email": 0,
      "bounce_rate": 0,
      "created_date": "2025-07-13T10:35:04.351377+05:45",
      "is_file_organised": false,
      "progress_percentage": 100,
      "updated_date": "2025-07-13T10:35:07.923638+05:45",
      "valid_emails_count": 4,
      "invalid_emails_count": 0,
      "clean_email_id": null,
      "validate_email_id": 23990312
    }
  ]
}

​
Use Cases

File Management

Browse and manage all your uploaded files in one place

Status Monitoring

Check the processing status of multiple files at once

Filtered Views

View files by their processing purpose (clean, validate, analyze)

Batch Operations

Prepare for batch operations by getting file IDs and URLs
Pagination: The API uses cursor-based pagination. Use the next and previous URLs provided in the response for seamless navigation between pages.
Performance: For large file collections, use filtering and pagination to improve response times and reduce bandwidth usage.

Authorizations

​
X-API-KEY
string
header
required

API key for authentication

Query Parameters

​
file_tag
enum<string>

Filter files by their processing purpose/tag

Available options:
clean,
validate,
analyze
​
size
integer
default:10

Number of results to return per page.

Required range: 1 <= x <= 100
​
page
integer
default:1

Page number for pagination.

Required range: x >= 1

Response

List of files retrieved successfully

​
count
integer

Total number of files matching the query

​
next
string<uri> | null

URL for the next page of results

​
previous
string<uri> | null

URL for the previous page of results

​
results
object[]

Array of file objects for the current page