# Authentication Source: https://developers.debounce.com/api-concepts/authentication How to authenticate your DeBounce API requests All DeBounce API requests require authentication using your account’s API key. This key authorizes your requests and ensures they are associated with your account. ## API Key Overview A DeBounce API key is a unique 13-character alphanumeric token tied to your account. Include your API key in every request using the `api` parameter. To authenticate a request, append your API key to the query string: ``` &api=YOUR_API_KEY ``` This method allows requests to be authenticated without requiring custom headers. Requests missing a valid API key will be rejected. ## How to Get Your API Key Visit your DeBounce dashboard and open the [API Settings](https://app.debounce.io/api) page to generate or manage your API key. ## Example Request ```bash theme={null} curl -X GET "https://api.debounce.io/?api=YOUR_API_KEY&email=example@gmail.com" ``` Store your API key securely and avoid exposing it in client-side code, public repositories, or shared environments. # HTTP Status Codes Source: https://developers.debounce.com/api-concepts/https-codes List of HTTP status codes returned by the DeBounce API DeBounce API responses include standard HTTP status codes to indicate the outcome of each request.\ Use this page as a quick reference when handling errors or building error-recovery logic. ## Status Codes | Code | Name | Description | | ------- | ----------------- | -------------------------------------------------------------------------- | | **200** | OK | The request was successful and the response body contains the result. | | **401** | Unauthorized | The API key is missing, invalid, or not permitted. | | **402** | Payment Required | Your validation credits are exhausted. Add credits to continue validating. | | **403** | Forbidden | The request is not allowed for this API key or operation. | | **429** | Too Many Requests | The rate limit or concurrency limit has been exceeded. | Each endpoint documents additional error details returned inside the JSON `debounce` object. # Rate Limiting Source: https://developers.debounce.com/api-concepts/rate-limiting Rate limits and concurrency restrictions for DeBounce API Rate limiting helps ensure platform stability, fairness, and consistent performance for all users.\ DeBounce applies limits depending on the type of API key and the operation being performed. *** ## Regular API Key All requests made with a regular (private) API key are subject to concurrency limits.\ These limits prevent overload and help ensure fast, reliable validation results. ### Concurrent Request Limit * You may send up to **5 concurrent API calls** at a time. * If the **data enrichment** option is enabled, the limit becomes **2 concurrent calls**. If your application exceeds this limit, the API returns: ```json theme={null} HTTP/429 Too Many Requests { "debounce": { "error": "Maximum concurrent calls reached", "code": "0" }, "success": "0" } ``` ### Recommendations for Developers * Use connection pooling or queueing to control concurrency * Retry failed requests with backoff timing * Cache results when possible * Avoid validating large volumes in parallel without a queue These practices improve performance and help remain within platform limits. Need more validation throughput? Contact our team to request upgraded rate limits. *** ## Public API Key (Client-Side Use) A public API key starts with `public_` and is intended for **JavaScript usage**, such as real-time form validation widgets. ### CORS Requirements You must add your domain to the key’s **approved CORS domain list**. ### Daily Per-IP Limit To protect your account from abuse, each internet IP address may validate up to: * **20 emails per day** If a user exceeds this limit, the widget displays "You performed many validations", and the API returns: ```json theme={null} HTTP/429 Too Many Requests { "debounce": { "error": "Authentication Failed - The maximum number of calls per day reached." }, "success": "0" } ``` You can check your current public IP address using:\ WhatIsMyIP *** ## Bulk Validation Limits Bulk validation jobs are intentionally serialized to ensure system stability. ### Bulk API Rules * Only **one active bulk validation job** is allowed per account * Additional uploads or API bulk jobs are **queued** automatically * When the active job finishes, the next queued job begins This guarantees predictable processing and prevents overload for large lists. *** # Requests – URL Formats Source: https://developers.debounce.com/api-concepts/request Understanding DeBounce API request structure and parameters DeBounce API requests follow a simple URL-based structure.\ Each endpoint uses query parameters to define what data you want to validate or retrieve. ## General URL Structure Most requests follow this format: ``` https://{hostname}/{path}?{parameters} ``` Where each component has a specific role: | Component | Description | | -------------- | -------------------------------------------------------------------------------------------------------------------- | | **hostname** | The service domain handling the request, such as `api.debounce.io`, `bulk.debounce.io`, or `disposable.debounce.io`. | | **path** | The specific API route being called, such as `single`, `bulk/status`, or `free/disposable`. | | **parameters** | Query parameters that define the request, such as the email address, API key, or file token. | ## How DeBounce Uses URL Parameters DeBounce endpoints rely on simple query-string parameters.\ Common examples include: * `api` — your API key * `email` — email address to validate * `task_id` — reference to a bulk validation job * `file` — file token used for retrieving bulk results Each endpoint documents its required and optional parameters individually. # API Responses Source: https://developers.debounce.com/api-concepts/responses Format and structure of DeBounce API responses DeBounce API responses follow a consistent structure.\ Each response includes a `success` field that indicates whether the request was processed successfully. * `success = "1"` → the request was successful * `success = "0"` → the request failed, and an error message may be included When a request succeeds, the main data is returned inside the `debounce` object.\ When a request fails, the `debounce` object contains error details. ## Success Response A typical successful response includes: * The validated email address * A result status such as Safe to Send, Invalid, Disposable, etc. * Metadata fields (role account, free email, did-you-mean suggestions, etc.) * Remaining balance Example: ```json theme={null} HTTP/1.1 200 OK { "debounce": { "email": "mohsen@gmail.com", "code": "5", "role": "false", "free_email": "true", "result": "Safe to Send", "reason": "Deliverable", "send_transactional": "1", "did_you_mean": "" }, "success": "1", "balance": "1725935" } ``` ## Error Response When an error occurs, the `debounce` object contains information about the failure.\ Common reasons include invalid API keys, missing parameters, or malformed requests. Example: ```json theme={null} HTTP/1.1 401 Unauthorized { "debounce": { "error": "Wrong API", "code": "0" }, "success": "0" } ``` ## Notes Each endpoint documents its own additional fields, result codes, and metadata. Use this page as a general reference for the overall response structure. # Validation Status Source: https://developers.debounce.com/api-reference/endpoint/bulk/status GET /v1/status/ The validation status endpoint allows you to check the progress of a list previously uploaded through the bulk validation API. Once processing is complete, the response includes a link to download the results as a `.csv` file. ## When to Use This Endpoint * After uploading a list via the bulk upload API * To monitor validation progress (queued, processing, completed) * To retrieve the final downloadable results file This endpoint works only for lists uploaded through the bulk API.\ Dashboard uploads do not return an API-accessible status. # Bulk Upload Source: https://developers.debounce.com/api-reference/endpoint/bulk/upload GET /v1/upload/ Perform a bulk email validation request via API. The bulk upload endpoint allows you to validate large email lists.\ Only **one bulk validation job** can run at a time per account. * After uploading a file, validation **starts automatically**. * If a job is already running, any new upload will be **queued** and processed afterward. ## File Hosting Requirements To use this endpoint, you must: * Upload the file to **your own server** * Provide the **public HTTPS URL** to the file * Ensure the URL ends with `.csv` or `.txt` Public file-sharing services (Google Drive, Dropbox, OneDrive, etc.) are **not supported**.\ Only direct-file URLs hosted on your own server can be processed. *** ## File Requirements Your uploaded file must meet these conditions: * File size **less than 20MB** * Maximum **200,000 emails** per list * File type: `.csv` or `.txt` * One email per line If your list exceeds the limit, split it into multiple files and upload them one by one. # Data Append (Reverse Email Lookup API) Source: https://developers.debounce.com/api-reference/endpoint/enrichment Retrieve contact information from email addresses Retrieve the full name, avatar, or both from an email address using the DeBounce data enrichment engine. ## Full Name + Avatar To receive enriched contact information (full name and avatar), use the [Single Validation API](/api-reference/endpoint/single-validation) with the following parameter: ``` &append=true ``` This activates the enrichment engine for the request. Pricing
Each successful enrichment request costs 20 extra credits. ## Avatar Only If you only need a profile photo, add: ``` &photo=true ``` This retrieves the avatar (when available) alongside the standard validation response. Pricing
Each successful avatar lookup costs 1 extra credit. ## Demo Try the data enrichment demo here: Data Enrichment Demo # Disposable Detector Source: https://developers.debounce.com/api-reference/endpoint/free/disposible-detector GET / Free API as easy as hitting a URL. Check an email address against a real-time, up-to-date list of disposable domains. The Disposable Detector API checks whether an email address or domain belongs to a known disposable email service.\ This endpoint is **free to use** and can be called directly from client-side applications thanks to full CORS support. ## What this API Helps With * Detecting disposable or temporary email addresses * Improving email list quality * Reducing bounce rates and spam-related risks * Increasing the accuracy of user registrations and submissions This makes the API valuable for developers integrating signup validation, marketers maintaining clean lists, or any workflow where email quality matters. *** ## Rate Limiting The free Disposable Detector API includes rate limits on: * Daily usage * Request speed Exact thresholds are not disclosed for security purposes.\ Typical client-side usage (such as signup validation) will not encounter these limits under normal conditions. # Logo API Source: https://developers.debounce.com/api-reference/endpoint/free/logo-api GET /logo/ Free company logo lookup service The Logo API provides instant access to company logos by domain name. This **completely free** service serves as a drop-in replacement for the deprecated Clearbit Logo API and delivers high-quality logos through our global CDN. You can see more logo demos in action by clicking here. Logo API Featured Image ## What this API Provides * **High-quality PNG logos** for millions of companies * **Automatic fallback** to clean monograms when logos aren't available * **Daily updates** to reflect rebranding and domain changes * **Production-ready** for high-traffic applications * **No attribution required** - use logos freely in your applications ## Use Cases * **Onboarding flows** - Display company logos during user registration * **Job boards** - Show employer logos in listings * **Financial dashboards** - Enhance account views with brand logos * **Internal tools** - Add visual context to company data * **CRM systems** - Enrich contact records with company branding *** ## API Endpoint ``` GET https://logo.debounce.com/{domain} ``` Replace `{domain}` with the company domain you want to retrieve a logo for. ### Example Requests **Get Google's logo:** ``` GET https://logo.debounce.com/google.com ``` **Get Apple's logo:** ``` GET https://logo.debounce.com/apple.com ``` **Get Microsoft's logo:** ``` GET https://logo.debounce.com/microsoft.com ``` *** ## Response Format The API returns logo images directly in PNG format. If a logo is found, you'll receive the high-quality company logo. If no logo is available, a clean grey monogram placeholder will be returned instead. ### Successful Response * **Content-Type:** `image/png` * **Status Code:** `200 OK` * **Image Size:** `128x128px` (square format) * **Body:** PNG image data ### Visual Example Here's what the Google logo looks like when fetched from the API: Google Logo ### Example Usage in HTML ```html theme={null} Google Logo ``` ### Example Usage in JavaScript ```javascript theme={null} // Simple image loading const img = new Image(); img.onload = () => console.log('Logo loaded successfully'); img.onerror = () => console.log('Logo failed to load'); img.src = 'https://logo.debounce.com/google.com'; // React component example function CompanyLogo({ domain, size = 128 }) { return ( {`${domain} { // Optional: handle fallback locally e.target.style.display = 'none'; }} /> ); } ``` *** ## Rate Limiting The free Logo API includes rate limits for fair usage: * **Request frequency** limits apply * **Daily usage** quotas may apply during peak usage These limits are designed to prevent abuse while allowing normal production usage. High-traffic applications should consider caching logos locally. *** ## Best Practices **Caching Recommendations:** Store logos locally or in your CDN to reduce API calls and improve performance. Logos are updated daily, so refresh your cache periodically. **Error Handling:** Always implement proper error handling. While the API provides fallbacks, network issues can still occur. **Image Optimization:** Consider resizing logos on your end for consistent display across your application. *** ## Migration from Clearbit If you're migrating from Clearbit Logo API, the transition is simple: **Before (Clearbit):** ``` https://logo.clearbit.com/{domain} ``` **After (DeBounce):** ``` https://logo.debounce.com/{domain} ``` No other changes to your implementation are required. The DeBounce Logo API maintains the same simple interface while being completely free and actively maintained. *** ## Supported Formats * **PNG format** - High-quality, scalable logos * **Automatic fallback** - Clean monograms for missing logos * **Consistent sizing** - All logos delivered at 128x128px (square format) The API automatically handles logo discovery, formatting, and delivery, making integration effortless for developers. # Account Balance Source: https://developers.debounce.com/api-reference/endpoint/miscellaneous/balance GET /v1/balance/ Check your remaining validation credits The Account Balance endpoint returns the number of remaining validation credits in your DeBounce account. Use this endpoint to: * Check available credits before running validations * Monitor credit usage programmatically * Prevent interruptions in automated workflows ## Response The response is a simple JSON object containing only your current credit balance. Example: ```json theme={null} { "balance": "1087306" } ``` This endpoint is read-only and always returns the balance as a string value. # API Usage History Source: https://developers.debounce.com/api-reference/endpoint/miscellaneous/usage GET /v1/usage/ Track your daily API usage and credit consumption The Usage History endpoint returns your validation activity for a specified date range.\ This allows you to track how many credits were consumed on each day. ## Date Requirements When specifying dates for this endpoint: * Use the **YY-MM-DD** format (two digits for year, month, and day). * The **earliest allowed start date** is **20-08-14**. * The **end date** cannot be later than **today’s date**. Requests that do not follow these rules will return an error. ## Usage Provide a start and end date in the query parameters to retrieve daily usage within that range. Example: ``` /v1/usage/?start=24-01-01&end=24-01-31&api=YOUR_API_KEY ``` This returns the number of validations performed on each day of the selected period. # Single Email Validation Source: https://developers.debounce.com/api-reference/endpoint/single-validation GET /v1/ Single email validation options and parameters You can enhance single email validation results by enabling additional options in the request. ## Profile Photo To include a profile photo (when available), add: ``` &photo=true ``` This option adds **1 extra credit** for each successful profile photo returned. *** ## Data Enrichment (Full Name & Avatar) To retrieve enriched contact details such as the user’s full name and avatar, include: ``` &append=true ``` This option costs **20 extra credits** for each successful enrichment response. *** ### Important Usage Guidance When using this API on a **signup form**, the following statuses should be treated as valid: * **Deliverable** * **Accept-all** * **Unknown** This prevents rejecting legitimate new users. You may also rely on the `send_transactional` parameter: * If `send_transactional = 1`, the email is considered acceptable for user registration. # Overview Source: https://developers.debounce.com/index Technical overview of the DeBounce email validation API. The DeBounce API enables accurate email validation, verification, and enrichment at scale. It is built for developers who need reliable email quality checks inside applications, CRMs, signup flows, and automated workflows. Get up and running in 5 minutes Complete endpoint documentation Secure API access guide Understand usage limits ## What you can do with this API > **Validate a single email**\ > Check if an email is deliverable, risky, disposable, or part of a catch-all domain. > **Process bulk lists**\ > Upload large lists and retrieve validation results asynchronously. > **Enrich contact data**\ > Retrieve metadata such as name, gender, and email attributes when available. > **Monitor usage**\ > Access account usage, credit balance, and validation statistics programmatically. ## How it works Log in to your DeBounce dashboard to access your private API key. Use the appropriate API endpoint for single email validation, bulk processing, or enrichment. Each API call returns a structured JSON response containing status details and metadata. ## Quick Example ```bash theme={null} curl "https://api.debounce.io/v1/?email=user@example.com&api_key=YOUR_API_KEY" ``` **Response:** ```json theme={null} { "debounce": { "email": "testemail@gmail.com", "code": "5", "role": "false", "free_email": "true", "result": "Safe to Send", "reason": "Deliverable", "send_transactional": "1", "did_you_mean": "" }, "success": "1", "balance": "14999" } ``` ## Before you start * You will need an API key tied to your DeBounce account * Each feature has its own endpoint and response structure * Validation speed depends on usage tier and selected methods * Bulk processing workflows operate asynchronously ## Next steps * Learn about **Authentication** * Explore **Single Email Validation** * Review **Bulk Upload** processing * Check **Enrichment** features