Skip to main content
GET
/
v1
/
api
/
filesupload
/
{file_id}
Get File Details
curl --request GET \
  --url https://base.sanitizeemail.com/v1/api/filesupload/{file_id} \
  --header 'X-API-KEY: <api-key>'
{
  "id": 123,
  "name": "<string>",
  "file_name": "<string>",
  "file_size": "<string>",
  "user": {
    "id": 123,
    "username": "<string>",
    "email": "jsmith@example.com"
  },
  "file": "<string>",
  "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 detailed information about a previously uploaded file, including processing status, email statistics, and metadata.

​
Path Parameters

The file ID is required in the URL path:
  • file_id: The unique identifier of the uploaded file (obtained from the file upload response)

​
How it Works

1

Get File ID

Obtain the file ID from a previous file upload response or file listing
2

Make Request

Send a GET request to /v1/api/filesupload/{file_id} replacing {file_id} with the actual file ID
3

Receive File Details

Get comprehensive information about the file including processing status and statistics

​
Response Information

The response includes comprehensive file information:

​
File Metadata

  • Basic Info: ID, name, filename, size, status
  • User Info: Owner details (ID, username, email)
  • File URL: Direct link to access the uploaded file
  • Timestamps: Creation and last update dates

​
Processing Statistics

  • Email Counts: Total, billable, duplicate, dropped emails
  • Validation Results: Valid, invalid, clean email counts
  • Quality Metrics: Bounce rate, progress percentage
  • Job IDs: References to cleaning or validation jobs

​
File Status

The status field indicates the current processing state:
  • pending: File uploaded but not yet processed
  • processing: File is currently being processed
  • validated: Email validation completed
  • cleaned: Email cleaning completed
  • failed: Processing failed

​
Example Usage

# Get details for file ID 740
GET /v1/api/filesupload/740/

{
  "id": 740,
  "name": "Customer Email List",
  "file_name": "Book Sheet1.csv",
  "file_size": "328",
  "status": "validated",
  "user": {
    "id": 100,
    "username": "test_user",
    "email": "cool@gmail.com"
  },
  "file": "https://s3.us-east-1.amazonaws.com/sanitizeemail/email_validation_files/Book_Sheet1_wsLgoJw.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-11T16:58:10.078456+05:45",
  "is_file_organised": false,
  "progress_percentage": 100,
  "updated_date": "2025-07-11T16:59:00.456247+05:45",
  "valid_emails_count": 4,
  "invalid_emails_count": 0,
  "clean_email_id": null,
  "validate_email_id": 23990312
}

​
Use Cases

Check Processing Status

Monitor the progress of file processing and validation jobs

Get Email Statistics

Retrieve detailed statistics about email quality and counts

Access File URL

Get the direct URL to download or access the processed file

Track Job References

Find associated cleaning or validation job IDs for further operations
File ID Source: The file ID is returned when you upload a file using the File Upload endpoint. Make sure to save this ID for future reference.
Status Monitoring: Use this endpoint to poll for status updates when processing large files. Check the progress_percentage field for real-time progress updates.

Authorizations

​
X-API-KEY
string
header
required

API key for authentication

Path Parameters

​
file_id
integer
required

Unique identifier of the uploaded file

Response

File details retrieved successfully

​
id
integer

Unique identifier of the file

​
name
string

Display name of the file

​
file_name
string

Original filename

​
file_size
string

File size in bytes

​
status
enum<string>

Current processing status of the file

Available options:
pending,
processing,
validated,
cleaned,
failed
​
user
object
​
file
string<uri>

URL to access the uploaded file

​
file_tag
enum<string>

Tag associated with the file processing type

Available options:
clean,
validate,
analyze
​
total_email
integer

Total number of emails found in the file

​
billable_email
integer

Number of emails that count towards billing

​
duplicate_email
integer

Number of duplicate emails found

​
dropped_email
integer

Number of emails that were dropped during processing

​
clean_email_count
integer

Number of clean/valid emails

​
bounced_email
integer

Number of emails that bounced

​
bounce_rate
number<float>

Bounce rate as a decimal (0.0 to 1.0)

​
created_date
string<date-time>

Date and time when the file was uploaded

​
is_file_organised
boolean

Whether the file was uploaded as organized (with headers)

​
progress_percentage
integer

Processing progress percentage

Required range: 0 <= x <= 100
​
updated_date
string<date-time>

Date and time when the file was last updated

​
valid_emails_count
integer

Number of valid emails

​
invalid_emails_count
integer

Number of invalid emails

​
clean_email_id
integer | null

ID of the clean email list (if cleaning was performed)

​
validate_email_id
integer | null

ID of the validation job (if validation was performed)