API Controller Documentation

Overview

The `ApiController` manages core API operations including email verification, file processing, and API key authentication.

All endpoints require an API key unless otherwise specified.

Endpoint Specifications

API Reference

Bulk Operations & Files

POST /verifApiFile

Description: Verify a file of email addresses.

Parameters

Name	Type	Description
secret	string	API key
file	multipart/form-data	Email list file

Responses

Status	Body
200 OK	`10998`
401 Unauthorized	`Invalid key`
402 Payment Required	`Insufficient credit`

POST /bulk

Description: Upload a bulk file for processing.

Parameters

Name	Type	Description
secret	string	API key
file	multipart/form-data	File to upload

Responses

Status	Body
200 OK	`{ "success": true, "id": 10952, "job_id": 1751481492, "message": "", "filename": "5kphones.csv" }`
401 Unauthorized	`Invalid key`
402 Payment Required	`Insufficient credit`

GET /file

Description: Download a processed file.

Parameters

Name	Type	Description
secret	string	API key
id	string	File ID
type	string	File type

Responses

Status	Body
200 OK	`File content (binary)`
401 Unauthorized	`Invalid key`
404 Not Found	`File not found`

GET /fileOld

Description: Legacy endpoint for downloading processed files.

Parameters

Name	Type	Description
secret	string	API key
id	string	File ID
type	string	File type

Responses

Status	Body
200 OK	`{ "status": "success", "message": "File downloaded successfully", "file_url": "https://example.com/file.zip" }`
400 Bad Request	`Missing parameters`
401 Unauthorized	`Invalid key`
404 Not Found	`File not found`

Zapier Integration Endpoints

GET /zapier-auth

Description: Authenticates API keys for Zapier integration.

Parameters

Parameter	Type	Required	Description
api_key	string	Yes	User’s API key

Responses

Status	Body
200 OK	`{ "status": "success", "message": "API Key is valid", "user_id": 12345, "key_name": "My Production Key" }`
401 Unauthorized	`{ "error": "Invalid API Key", "message": "The provided API Key is not valid" }`

POST /verify-single-email-zap

Description: Verifies a single email address via Zapier.

Parameters

Parameter	Location	Type	Required	Description
api_key	Query	string	Yes	User’s API key
email	Body	string	Yes	Email to verify

Responses

Status	Body
200 OK	`{ "status": "success", "verification_result": "valid", "timestamp": 1678901234 }`
400 Bad Request	`{ "status": "error", "code": 400, "error": "missing_parameters", "message": "Parameters \"api_key\" and \"email\" are required" }`
401 Unauthorized	`{ "status": "error", "code": 401, "error": "invalid_key", "message": "API key is not valid" }`
402 Payment Required	`{ "status": "error", "code": 402, "error": "insufficient_credit", "message": "Not enough credits" }`
500 Server Error	`{ "status": "error", "code": 500, "error": "verification_service_unavailable", "message": "Email verification service is currently unavailable" }`

Verification Result Codes

Code	Description
valid	Email address is valid
invalid	Email address is invalid
unknown	Verification status could not be determined
catch-all	Domain accepts all emails
disposable	Temporary/disposable email address

Status Code Reference

API Reference

Bulk Operations & Files

POST /verifApiFile

Description: Verify a file of email addresses.

Parameters

Name	Type	Description
secret	string	API key
file	multipart/form-data	Email list file

Responses

Status	Body
200 OK	`10998`
401 Unauthorized	`Invalid key`
402 Payment Required	`Insufficient credit`

POST /bulk

Description: Upload a bulk file for processing.

Parameters

Name	Type	Description
secret	string	API key
file	multipart/form-data	File to upload

Responses

Status	Body
200 OK	`{"success":true,"id":10952,"job_id":1751481492,"message":"","filename":"5kphones.csv"}`
401 Unauthorized	`Invalid key`
402 Payment Required	`Insufficient credit`

GET /file

Description: Download a processed file.

Parameters

Name	Type	Description
secret	string	API key
id	string	File ID
type	string	File type

Responses

Status	Body
200 OK	`File content (binary)`
401 Unauthorized	`Invalid key`
404 Not Found	`File not found`

GET /fileOld

Description: Legacy endpoint for downloading processed files.

Parameters

Name	Type	Description
secret	string	API key
id	string	File ID
type	string	File type

Responses

Status	Body
200 OK	`{"status":"success","message":"File downloaded successfully","file_url":"https://example.com/file.zip"}`
400 Bad Request	`Missing parameters`
401 Unauthorized	`Invalid key`
404 Not Found	`File not found`

Bulk Operations section formatting complete and styled consistently.

Status Codes

The following status codes may be returned by the API:

Code	Description	Common Endpoints
200	Success	All endpoints
400	Missing/invalid parameters	All endpoints
401	Invalid API key	Authenticated endpoints
402	Insufficient credit	Email verification endpoints
404	Resource not found	`/file`, `/fileOld`

Usage Guidelines

API Reference

Bulk Operations & Files

POST /verifApiFile

Description: Verify a file of email addresses.

Parameters

Name	Type	Description
secret	string	API key
file	multipart/form-data	Email list file

Responses

Status	Body
200 OK	`10998`
401 Unauthorized	`Invalid key`
402 Payment Required	`Insufficient credit`

POST /bulk

Description: Upload a bulk file for processing.

Parameters

Name	Type	Description
secret	string	API key
file	multipart/form-data	File to upload

Responses

Status	Body
200 OK	`{"success":true,"id":10952,"job_id":1751481492,"message":"","filename":"5kphones.csv"}`
401 Unauthorized	`Invalid key`
402 Payment Required	`Insufficient credit`

GET /file

Description: Download a processed file.

Parameters

Name	Type	Description
secret	string	API key
id	string	File ID
type	string	File type

Responses

Status	Body
200 OK	`File content (binary)`
401 Unauthorized	`Invalid key`
404 Not Found	`File not found`

GET /fileOld

Description: Legacy endpoint for downloading processed files.

Parameters

Name	Type	Description
secret	string	API key
id	string	File ID
type	string	File type

Responses

Status	Body
200 OK	`{"status":"success","message":"File downloaded successfully","file_url":"https://example.com/file.zip"}`
400 Bad Request	`Missing parameters`
401 Unauthorized	`Invalid key`
404 Not Found	`File not found`

Bulk Operations section formatting complete and styled consistently.

Additional Notes

Authentication: Standard endpoints use secret parameter. Zapier endpoints use api_key parameter.
Credit System: Email verification consumes credit; 402 indicates insufficient balance.
File Downloads: Use /file for current files, /fileOld for legacy files.
Zapier Integration: Endpoints with Zap suffix (/zapierAuth, /verifySingleEmailZap) are Zapier-optimized.

Status Codes

The following status codes may be returned by the API:

Code	Description	Common Endpoints
200	Success	All endpoints
400	Missing/invalid parameters	All endpoints
401	Invalid API key	Authenticated endpoints
402	Insufficient credit	Email verification endpoints
404	Resource not found	`/file`, `/fileOld`

↑ Back to Top