{ "swagger": "2.0", "info": { "description": "Listclean APIs. For API reference doc at [https://api.listclean.xyz](https://api.listclean.xyz).

You can also try these APIs at --> [API Playground](https://api.listclean.xyz/try)

", "version": "0.1.0", "title": "Listclean API (Beta)", "contact": { "email": "support@listclean.xyz" } }, "host": "api.listclean.xyz", "basePath": "/v1/", "tags": [ { "name": "verifications", "description": "APIs for verifying emails" }, { "name": "uploads", "description": "APIs for uploading large lists (csv files)" }, { "name": "lists", "description": "APIs for fetching list informations" }, { "name": "accounts", "description": "User account related APIs" } ], "schemes": [ "https" ], "paths": { "/verify/email/{email}": { "get": { "summary": "Verify single email address at a time", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "verifications" ], "parameters": [ { "in": "path", "name": "email", "required": true, "type": "string", "example": "test@example.com" } ], "x-code-samples": [ { "lang": "cURL", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.listclean.xyz/v1/verify/email/test@example.com' \\\n --header 'X-Auth-Token: YOUR_API_KEY'" }, { "lang": "PHP", "label": "PHP", "source": " $url,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'X-Auth-Token: ' . $apiKey,\n 'Accept: application/json'\n ],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\n\nif ($response === false) {\n throw new RuntimeException('cURL error: ' . curl_error($ch));\n}\n\ncurl_close($ch);\n\n$result = json_decode($response, true);\n\nif ($httpCode !== 200) {\n throw new RuntimeException('API request failed. HTTP status: ' . $httpCode . '. Response: ' . $response);\n}\n\nprint_r($result);\n" } ], "responses": { "200": { "description": "Response on success", "schema": { "type": "object", "required": [ "success", "error_code", "message", "data" ], "properties": { "success": { "type": "integer", "enum": [ 0, 1 ], "description": "Success status, 0 for failed 1 for success", "example": 1 }, "message": { "type": "string", "example": "Email verification completed!" }, "error_code": { "type": "integer", "format": "int32", "example": 0 }, "data": { "type": "object", "required": [ "email", "status", "remarks", "disposable", "role_based", "mx_found", "mx_records", "msp", "email_user", "email_domain" ], "properties": { "datetime": { "type": "string", "example": "2026-09-09T17:11:58+05:30" }, "email": { "type": "string", "format": "email", "example": "myselfi.itba@gmail.com", "description": "Provided email address" }, "status": { "type": "string", "enum": [ "clean", "dirty", "unknown", "error" ], "example": "dirty" }, "remarks": { "type": "string", "example": "Email does not exists" }, "disposable": { "type": "boolean", "example": false }, "role_based": { "type": "boolean", "example": false }, "mx_found": { "type": "boolean", "example": true }, "mx_records": { "type": "string", "example": "gmail-smtp-in.l.google.com:5,alt1.gmail-smtp-in.l.google.com:10,alt2.gmail-smtp-in.l.google.com:20,alt3.gmail-smtp-in.l.google.com:30,alt4.gmail-smtp-in.l.google.com:40" }, "msp": { "type": "string", "example": "GMAIL" }, "email_user": { "type": "string", "example": "myselfi.itba" }, "email_domain": { "type": "string", "example": "gmail.com" }, "free_email": { "type": "boolean", "example": true } } } } } }, "400": { "description": "List name is required" }, "401": { "description": "Auth Failed" } }, "security": [ { "api_key": [] } ], "description": "Verify a single email address and get its validation status." } }, "/verify/email/batch": { "post": { "summary": "Verify batch of emails (max 3000 emails)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "verifications" ], "parameters": [ { "in": "body", "name": "body", "description": "The body of the API call", "schema": { "type": "object", "required": [ "emails" ], "example": { "emails": [ "user1@example.com", "user2@example.com" ] }, "properties": { "filename": { "type": "string", "description": "Optional source filename. If omitted, the API generates a UTC filename in the format batch_upload-DD-MM-YYYY-HHMMSS-utc.csv (for example, batch_upload-05-10-2026-143025-utc.csv). A .csv extension is added when a supplied filename has no extension.", "example": "october-leads.csv" }, "emails": { "type": "array", "description": "Email addresses to verify. The default limit is 3,000 addresses per request.", "items": { "type": "string" }, "example": [ "user1@example.com", "user2@example.com" ] } } } } ], "x-code-samples": [ { "lang": "cURL", "label": "Custom filename (cURL)", "source": "curl --request POST \\\n --url 'https://api.listclean.xyz/v1/verify/email/batch/' \\\n --header 'Content-Type: application/json' \\\n --header 'X-Auth-Token: YOUR_API_KEY' \\\n --data '{\n \"filename\": \"october-leads.csv\",\n \"emails\": [\n \"user1@example.com\",\n \"user2@example.com\"\n ]\n }'" } ], "responses": { "200": { "description": "Response on success", "schema": { "type": "object", "properties": { "success": { "type": "integer", "enum": [ 0, 1 ], "description": "Success status, 0 for failed 1 for success", "example": 1 }, "message": { "type": "string" }, "error_code": { "type": "integer", "format": "int32" }, "data": { "type": "object", "properties": { "list_id": { "type": "integer", "example": 370124, "description": "List ID (request ID) for tracking the batch job." } } } } } }, "400": { "description": "Parameter emails is required" }, "401": { "description": "Auth Failed" } }, "security": [ { "api_key": [] } ] } }, "/verify/email/logs": { "get": { "summary": "Get logs for all the single email verified", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "verifications" ], "parameters": [], "responses": { "200": { "description": "Response on success", "schema": { "type": "object", "properties": { "success": { "type": "integer", "enum": [ 0, 1 ], "description": "Success status, 0 for failed 1 for success", "example": 1 }, "message": { "type": "string" }, "error_code": { "type": "integer", "format": "int32" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 21, "description": "log id" }, "entered": { "type": "string", "example": "2022-09-29 18:23:43", "description": "datetime of log entry" }, "email": { "type": "string", "example": "test@example.com", "description": "provided email" }, "status": { "type": "string", "enum": [ "clean", "dirty", "unknown", "error" ], "example": "dirty" }, "remarks": { "type": "string", "example": "Disposable Email", "description": "description of the status" }, "credits_deducted": { "type": "integer", "example": 1, "description": "credits deducted for verifying single email. It is usually 1 credit for 1 email verification" }, "error_code": { "type": "string", "example": "0", "description": "Error Code, if in case error comes" } } } } } } }, "400": { "description": "List name is required" }, "401": { "description": "Auth Failed" } }, "security": [ { "api_key": [] } ] } }, "/uploads/": { "get": { "summary": "Get the list of uploads (csv upload)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "uploads" ], "parameters": [], "responses": { "200": { "description": "Response on success", "schema": { "type": "object", "properties": { "success": { "type": "integer", "enum": [ 0, 1 ], "description": "Success status, 0 for failed 1 for success", "example": 1 }, "message": { "type": "string" }, "error_code": { "type": "integer", "format": "int32" }, "data": { "type": "array", "items": { "type": "object", "properties": { "upload_id": { "type": "integer", "example": 1327 }, "status": { "type": "string", "example": "COMPLETED" }, "progress": { "type": "string", "example": "100%" } } } } } } }, "400": { "description": "List name is required" }, "401": { "description": "Auth Failed" } }, "security": [ { "api_key": [] } ] }, "post": { "summary": "Start the Upload (csv upload)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "uploads" ], "parameters": [ { "in": "body", "name": "body", "description": "The body of the API call", "schema": { "type": "object", "required": [ "filename", "file_type", "total_chunk_count", "max_chunk_size" ], "properties": { "filename": { "type": "string", "example": "My file.csv" }, "file_type": { "type": "string", "example": "csv" }, "total_chunk_count": { "type": "integer", "example": 24 }, "max_chunk_size": { "description": "max size of a chunk in bytes", "type": "integer", "example": 64000 }, "separator_char": { "description": "character separator for csv file format", "type": "string", "example": "," }, "enclosure_char": { "description": "The optional enclosure parameter sets the field enclosure character (one single-byte character only).", "type": "string", "example": "\"" }, "escape_char": { "description": "The optional escape parameter sets the escape character (at most one single-byte character). An empty value disables the escape mechanism.", "type": "string", "example": "" }, "fast_process": { "description": "Option to process list as fast as possible by avoiding slow opertions like SMTP validation, etc and instead only use fast operation like db lookup from cache, dns validation, format validation, etc. Default value is 0 which means off", "type": "integer", "example": "0" } } } } ], "responses": { "200": { "description": "Response on success", "schema": { "type": "object", "properties": { "success": { "type": "integer", "enum": [ 0, 1 ], "description": "Success status, 0 for failed 1 for success", "example": 1 }, "message": { "type": "string", "example": "Upload created successfully" }, "error_code": { "type": "integer", "format": "int32" }, "data": { "type": "object", "properties": { "upload_id": { "type": "integer", "example": 1327 } } } } } }, "400": { "description": "List name is required" }, "401": { "description": "Auth Failed" } }, "security": [ { "api_key": [] } ] } }, "/uploads/{upload_id}": { "post": { "summary": "Upload a Chunk [CHUNKS] (csv upload)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "uploads" ], "parameters": [ { "in": "body", "name": "body", "description": "The body of the API call", "schema": { "type": "object", "required": [ "chunk_sequence_number", "content" ], "properties": { "chunk_sequence_number": { "type": "integer", "example": 24 }, "content": { "description": "The base64-encoded contents of the file", "type": "string", "example": "====DYscs...==" }, "md5_checksum": { "description": "md5 hash of file to check the integrity of the file", "type": "string", "example": "0a52067b38f4485d42eb5f7040d476b3" } } } }, { "in": "path", "name": "upload_id", "required": true, "type": "integer" } ], "responses": { "200": { "description": "Response on success", "schema": { "type": "object", "properties": { "success": { "type": "integer", "enum": [ 0, 1 ], "description": "Success status, 0 for failed 1 for success", "example": 1 }, "message": { "type": "string", "example": "Chunk uploaded successfully" }, "error_code": { "type": "integer", "format": "int32" } } } }, "400": { "description": "List name is required" }, "401": { "description": "Auth Failed" } }, "security": [ { "api_key": [] } ] }, "get": { "summary": "Get status of a Upload", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "uploads" ], "parameters": [ { "in": "path", "name": "upload_id", "required": true, "type": "integer" } ], "responses": { "200": { "description": "Response on success", "schema": { "type": "object", "properties": { "success": { "type": "integer", "enum": [ 0, 1 ], "description": "Success status, 0 for failed 1 for success", "example": 1 }, "message": { "type": "string" }, "error_code": { "type": "integer", "format": "int32" }, "data": { "type": "object", "properties": { "status": { "description": "Status of a upload. Note, the value of status is enum (list). It can be the following - inprocess, success, error", "type": "string", "example": "inprocess" }, "progress": { "description": "completion percentage", "type": "integer", "example": 21 }, "chunk_details": { "type": "object", "properties": { "total_chunk_count": { "description": "Total numbers of chunk in a upload", "type": "integer", "example": "2" }, "uploaded_chunk_count": { "description": "Total numbers of successfully uploaded chunks", "type": "integer", "example": 0 } } }, "request_id": { "description": "Listcleaner request_id for the upload", "type": "integer", "example": 312 } } } } } }, "400": { "description": "List name is required" }, "401": { "description": "Auth Failed" } }, "security": [ { "api_key": [] } ] } }, "/lists/": { "get": { "summary": "Get the all list info", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "lists" ], "parameters": [], "responses": { "200": { "description": "Response on success", "schema": { "type": "object", "properties": { "success": { "type": "integer", "enum": [ 0, 1 ], "description": "Success status, 0 for failed 1 for success", "example": 1 }, "message": { "type": "string", "example": "List info successfully extracted" }, "error_code": { "type": "integer", "format": "int32" }, "data": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32", "example": 7 }, "cursor": { "type": "integer", "format": "int32", "example": 1 }, "lists": { "type": "array", "items": { "type": "object", "properties": { "list_id": { "type": "integer", "format": "int32", "example": 1 }, "filename": { "type": "string", "description": "Filename of list uploaded", "example": "sample-list.csv" }, "size_in_bytes": { "type": "integer", "format": "int32", "example": 229 }, "request_time": { "type": "string", "description": "Uploaded time", "example": "2021-11-06 22:37:19" }, "status": { "type": "string", "description": "List status", "enum": [ "COMPLETED", "INPROCESS", "SUBMITTED" ], "example": "COMPLETED" }, "upload_id": { "type": "string", "example": "Q1636218416-991025" }, "analytics": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32", "description": "Total Email contacts", "example": 12 }, "duplicate": { "type": "integer", "format": "int32", "description": "Duplicate Email contacts", "example": 1 }, "dirty": { "type": "object", "properties": { "count": { "type": "integer", "format": "int32", "description": "Dirty Count", "example": "8" }, "perc": { "type": "number", "description": "Dirty Rate", "example": "66.67" } } }, "clean": { "type": "object", "properties": { "count": { "type": "integer", "format": "int32", "description": "Clean Count", "example": "8" }, "perc": { "type": "number", "description": "Clean Rate", "example": "66.67" } } } } }, "dirty_summary": { "type": "array", "items": { "type": "object", "properties": { "count": { "type": "integer", "format": "int32", "description": "Dirty analytic count", "example": "5" }, "perc": { "type": "number", "description": "Dirty analytic Rate", "example": "55.56" }, "dirty_type": { "type": "string", "description": "Dirtiness category", "example": "Disposable Email" } } } }, "clean_summary": { "type": "array", "items": { "type": "object", "properties": { "count": { "type": "integer", "format": "int32", "description": "Clean analytic Count", "example": "1" }, "perc": { "type": "number", "description": "Clean analytic Rate", "example": "100" }, "clean_type": { "type": "string", "description": "Clean category(e.g. High Quality, Low Quality, Medium Quality)", "example": "High Quality" } } } } } }, "cost": { "type": "object", "properties": { "rate": { "type": "object", "properties": { "INR": { "type": "number", "description": "Amount in INR", "example": "1" }, "USD": { "type": "number", "description": "Amount in US Dollar", "example": "0.07" } } }, "cost": { "type": "object", "properties": { "INR": { "type": "number", "description": "Amount in INR", "example": "7090.4" }, "USD": { "type": "number", "description": "Amount in US Dollar", "example": "95" } } } } } } } } } } } } }, "400": { "description": "List name is required" }, "401": { "description": "Auth Failed" } }, "security": [ { "api_key": [] } ] } }, "/lists/{list_id}": { "get": { "summary": "Get the single list info", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "lists" ], "parameters": [ { "in": "path", "name": "list_id", "required": true, "type": "integer" } ], "responses": { "200": { "description": "Response on success", "schema": { "type": "object", "properties": { "success": { "type": "integer", "enum": [ 0, 1 ], "description": "Success status, 0 for failed 1 for success", "example": 1 }, "message": { "type": "string", "example": "List info successfully extracted" }, "error_code": { "type": "integer", "format": "int32" }, "data": { "type": "array", "items": { "type": "object", "properties": { "list_id": { "type": "integer", "format": "int32", "example": 1 }, "filename": { "type": "string", "description": "Filename of list uploaded", "example": "sample-list.csv" }, "size_in_bytes": { "type": "integer", "format": "int32", "example": 229 }, "request_time": { "type": "string", "description": "Uploaded time", "example": "2021-11-06 22:37:19" }, "status": { "type": "string", "description": "List status", "enum": [ "COMPLETED", "INPROCESS", "SUBMITTED" ], "example": "COMPLETED" }, "upload_id": { "type": "string", "example": "Q1636218416-991025" }, "analytics": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32", "description": "Total Email contacts", "example": 12 }, "duplicate": { "type": "integer", "format": "int32", "description": "Duplicate Email contacts", "example": 1 }, "dirty": { "type": "object", "properties": { "count": { "type": "integer", "format": "int32", "description": "Dirty Count", "example": "8" }, "perc": { "type": "number", "description": "Dirty Rate", "example": "66.67" } } }, "clean": { "type": "object", "properties": { "count": { "type": "integer", "format": "int32", "description": "Clean Count", "example": "8" }, "perc": { "type": "number", "description": "Clean Rate", "example": "66.67" } } } } }, "dirty_summary": { "type": "array", "items": { "type": "object", "properties": { "count": { "type": "integer", "format": "int32", "description": "Dirty analytic count", "example": "5" }, "perc": { "type": "number", "description": "Dirty analytic Rate", "example": "55.56" }, "dirty_type": { "type": "string", "description": "Dirtiness category", "example": "Disposable Email" } } } }, "clean_summary": { "type": "array", "items": { "type": "object", "properties": { "count": { "type": "integer", "format": "int32", "description": "Clean analytic Count", "example": "1" }, "perc": { "type": "number", "description": "Clean analytic Rate", "example": "100" }, "clean_type": { "type": "string", "description": "Clean category(e.g. High Quality, Low Quality, Medium Quality)", "example": "High Quality" } } } } } }, "cost": { "type": "object", "properties": { "rate": { "type": "object", "properties": { "INR": { "type": "number", "description": "Amount in INR", "example": "1" }, "USD": { "type": "number", "description": "Amount in US Dollar", "example": "0.07" } } }, "cost": { "type": "object", "properties": { "INR": { "type": "number", "description": "Amount in INR", "example": "7090.4" }, "USD": { "type": "number", "description": "Amount in US Dollar", "example": "95" } } } } } } } } } } }, "400": { "description": "List name is required" }, "401": { "description": "Auth Failed" } }, "security": [ { "api_key": [] } ] }, "delete": { "summary": "Delete the single list", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "lists" ], "parameters": [ { "in": "path", "name": "list_id", "required": true, "type": "integer" } ], "responses": { "200": { "description": "Response on success", "schema": { "type": "object", "properties": { "success": { "type": "integer", "enum": [ 0, 1 ], "description": "Success status, 0 for failed 1 for success", "example": 1 }, "message": { "type": "string", "example": "Lists deleted successfully" }, "error_code": { "type": "integer", "format": "int32" } } } }, "400": { "description": "List name is required" }, "401": { "description": "Auth Failed" } }, "security": [ { "api_key": [] } ] } }, "/downloads/{list_id}/{type}": { "get": { "summary": "Download lists results as a csv file", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "lists" ], "parameters": [ { "in": "path", "name": "list_id", "required": true, "type": "integer" }, { "in": "path", "name": "type", "required": true, "type": "string", "enum": [ "clean", "dirty", "unknown" ], "description": "A type can be clean, dirty, unknown" }, { "in": "query", "name": "X-Auth-Token", "required": false, "type": "string" } ], "responses": { "200": { "description": "Response is stream octet" }, "400": { "description": "List name is required" }, "401": { "description": "Auth Failed" } }, "security": [ { "api_key": [] } ] } }, "/downloads/json/{list_id}/{type}": { "get": { "summary": "Download lists results as a json", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "lists" ], "parameters": [ { "in": "path", "name": "list_id", "required": true, "type": "integer" }, { "in": "path", "name": "type", "required": true, "type": "string", "enum": [ "clean", "dirty", "unknown" ], "description": "A type can be clean, dirty, unknown" }, { "in": "query", "name": "X-Auth-Token", "required": false, "type": "string" } ], "responses": { "200": { "description": "Response is stream octet" }, "400": { "description": "List name is required" }, "401": { "description": "Auth Failed" } }, "security": [ { "api_key": [] } ] } }, "/account/profile/": { "get": { "summary": "Get account profile details", "description": "", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "accounts" ], "responses": { "200": { "description": "Response on success", "schema": { "type": "object", "properties": { "success": { "type": "integer", "enum": [ 0, 1 ], "description": "Success status, 0 for failed 1 for success" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "name": { "type": "string", "description": "First name of the user", "example": "Joe" }, "address": { "type": "string", "example": "245, Highway Street" }, "city": { "type": "string", "example": "New York" }, "country": { "type": "string", "example": "USA" }, "phone_number": { "type": "string", "example": "1111 2222 3333" }, "skype_id": { "type": "string", "example": "mime_post" }, "company_name": { "type": "string", "example": "Your Company, LLP" }, "website": { "type": "string", "example": "example.com" }, "twitter_handle": { "type": "string", "example": "@mime_post", "default": "" }, "linkedin": { "type": "string" }, "billing_name": { "type": "string" }, "billing_company_name": { "type": "string" }, "billing_address": { "type": "string" } } } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Auth Failed" } }, "security": [ { "api_key": [] } ] }, "post": { "summary": "Update account profile details", "description": "", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "accounts" ], "parameters": [ { "in": "body", "name": "body", "description": "", "required": true, "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "First name of the user", "example": "Joe" }, "address": { "type": "string", "example": "245, Highway Street" }, "city": { "type": "string", "example": "New York" }, "country": { "type": "string", "example": "USA" }, "phone_number": { "type": "string", "example": "1111 2222 3333" }, "skype_id": { "type": "string", "example": "mime_post" }, "company_name": { "type": "string", "example": "Your Company, LLP" }, "website": { "type": "string", "example": "example.com" }, "twitter_handle": { "type": "string", "example": "@mime_post", "default": "" }, "linkedin": { "type": "string" }, "billing_name": { "type": "string" }, "billing_company_name": { "type": "string" }, "billing_address": { "type": "string" } } } } ], "responses": { "200": { "description": "Response on success", "schema": { "$ref": "#/definitions/ApiResponse" } }, "400": { "description": "Invalid input" }, "401": { "description": "Auth Failed" } }, "security": [ { "api_key": [] } ] } }, "/credits": { "get": { "summary": "Get credits", "description": "", "produces": [ "application/json" ], "tags": [ "credits" ], "responses": { "200": { "description": "Response on success", "schema": { "type": "object", "properties": { "success": { "type": "integer", "enum": [ 0, 1 ], "description": "Success status, 0 for failed 1 for success", "example": 1 }, "message": { "type": "string", "example": "credit details extracted successfuly" }, "data": { "type": "object", "properties": { "credits": { "type": "integer", "description": "credits left", "example": 99 } } } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Auth Failed" } }, "security": [ { "api_key": [] } ] } } }, "securityDefinitions": { "api_key": { "type": "apiKey", "name": "X-Auth-Token", "in": "header" } }, "definitions": { "ApiResponse": { "type": "object", "properties": { "success": { "type": "integer", "enum": [ 0, 1 ], "description": "Success status, 0 for failed 1 for success", "example": 1 }, "message": { "type": "string" }, "error_code": { "type": "integer", "format": "int32" } } } }, "externalDocs": { "description": "Find out more about listclean.xyz", "url": "https://listclean.xyz" } }