# Overview Clearout provides a set of **RESTful APIs for email validation, advanced verification, and discovery** at scale. You can verify or discover millions of email addresses in real time, with endpoints covering [email verification](/developers/api/email-verify.md), [email finding](/developers/api/email-finder.md), reverse lookup, remaining credits, company-to-domain [auto-completion](/developers/api/autocomplete.md), and additional [domain](/developers/api/misc-domain-api.md) utilities. ## How to Get Started Getting started with Clearout APIs is quick and straightforward: {% stepper %} {% step %} **Create a free Clearout account** [Sign up](https://app.clearout.io/register) to receive **100 free credits** and instant access to the API. {% endstep %} {% step %} **Generate your API token** Find your API token in the Clearout [developer](https://app.clearout.io/developer/api/list) dashboard and use it to authenticate all API requests. {% endstep %} {% step %} **Set service-level settings** Configure your preferred [settings](https://app.clearout.io/settings/email_verifier), then call the service API endpoint to get the response. {% endstep %} {% step %} **Integrate with your application** Call APIs from your backend or automation workflows to verify or discover email addresses. {% endstep %} {% step %} **Go live and scale** Monitor your usage, manage credits, and upgrade your plan as it grows. {% endstep %} {% endstepper %} ## API Base URL Clearout APIs use a **base URL** to which all endpoint paths are appended. Since the base URL may vary based on your account host region, API users should check it by logging into the [Clearout app](https://app.clearout.io/developer/reference) and navigating to the **Developer** **→ Reference** tab.
Overview of Developer section showcasing API Base URL
## Generating an API Token After signing up and logging in, select the **Developer** tab located at the top-right, and then click on the **API → Create API Token** button. All created tokens are listed under this tab. Use this token as the **Bearer** value in all API requests. Tokens can be reset at any time by clicking the **Reset Token** icon. * Log in to your Clearout dashboard. * Navigate to **Developer → API**. * Click [**Create API Token**](https://app.clearout.io/developer/api/list). * Use the token as the `Authorization: Bearer ` header in all API requests.
Generating an API Token
### Example - Using a CURL Request {% code fullWidth="false" %} ```bash curl -X GET 'https://api.clearout.io/v2/email_verify/getcredits' \ -H 'Authorization: 3ec7egp34f992762fb5cf6a3479e7e34:d43d2e605e94a8c4s9b72be13b37c19c74b41610c3560484e5c422ccb4fb4074' ``` {% endcode %} ## API Response Objects and Status Codes ### HTTP response codes These are the HTTP response codes set by Clearout to indicate the success or failure of a request:
HTTP Status CodeMeaning / Description
200Success
400Bad Request
401Unauthorized
402Payment Required
403Forbidden
415Invalid Content Type (must be application/json)
429Rate Limit Exceeded
500Internal Server Error
503Service Unavailable
524Request Timeout
### Clearout error codes The following Clearout error codes will be included in the error response object:
Error CodeDescription
1001You’ve reached the maximum number of bulk verify requests. Please wait for the existing request to complete or contact us@clearout.io
1002You’ve exhausted your credits. Please add additional credits to continue
1004Unable to determine email addresses in the list. Ensure emails are present or explicitly specified in a header row using Email, Emails, Email address, or Emailaddress
1007List has expired. Contact us@clearout.io
1008You are not authorized to access this resource
1017You’ve reached the daily verify limit. Try again the next day or contact us@clearout.io
1027Email address not found
1028Available credits (AVAILABLE_CREDITS) are insufficient to verify NUMBER_OF_EMAILS emails
1029List is not available
1030API rate limit reached. Retry after [CURRENT TIMESTAMP + 60 seconds] UTC, or upgrade your plan / contact us@clearout.io
1031You have exhausted your credits.
1032You have reached your daily verify limit; please try next day
1074Invalid origin
### Flatten Response Object By adding response=flat as a query parameter to any API request, the nested object will be converted into a flat object. This is helpful when your system does not support nested JSON objects. ## Cross-Origin Resource Sharing (CORS) Clearout does not support API requests directly from web browsers or client apps. This means Clearout APIs can be used only from your **server-side application** ## Limits and Quotas ### API Rate Limit Clearout APIs apply rate limits to ensure platform reliability and fair usage across all plans. Rate-limit details are included in the response headers for every API request. #### Rate Limit Headers
HeaderDescription
x-ratelimit-limitTotal number of requests allowed within a 60-second window
x-ratelimit-remainingNumber of requests remaining in the current 60-second window
x-ratelimit-resetTime remaining (in seconds) before the rate-limit window resets
#### Example Response ``` x-ratelimit-limit: 100 x-ratelimit-remaining: 42 x-ratelimit-reset: 18 ``` #### How It Works * A maximum of **100 requests** can be made per minute * **42 requests** are still available in the current window * The quota resets in **18 seconds** #### When the Limit Is Exceeded If you exceed the allowed request limit: * **HTTP Status Code:** `429 Too Many Requests` * **Clearout Error Code:** `1030` You should wait until the duration specified `x-ratelimit-reset` elapses before retrying.\ To increase your rate limit, upgrade your plan or contact [support](/help-and-support/how-to-work-with-support.md). ### Plan-Specific Limits Clearout offers flexible pay-as-you-go and subscription plans, each with different API limits. Compared to pay-as-you-go plans, subscription plans offer higher limits, which you can increase by selecting an add-on option. Please find below the breakup of plans and API **Request Per Limits (RPM).**

Monthly/Annual Subscription

| Credits | Instant Email Verify (RPM) | Instant Email Finder (RPM) | | ------------------- | :------------------------: | :------------------------: | | 3,000 | 25 | 14 | | 10,000 | 55 | 40 | | 50,000 | 90 | 55 | | 100,000 | 135 | 85 | | 250,000 | 185 | 110 | | 500,000 | 240 | 140 | | 1,000,000 | 300 | 190 | | More than 5,000,000 | 400 | 240 |

Pay-As-You-Go

| Credits | Instant Email Verify (RPM) | Instant Email Finder (RPM) | | -------------------- | :------------------------: | :------------------------: | | 5,000 | 20 | 10 | | 10,000 | 45 | 30 | | 100,000 | 70 | 45 | | 250,000 | 110 | 70 | | 500,000 | 150 | 90 | | 1,000,000 | 190 | 110 | | 5,000,000 | 240 | 150 | | More than 10,000,000 | 320 | 190 | For more details on limits and pricing, please refer to the [pricing page](https://clearout.io/pricing/) here. ## Testing To confirm that your integration works as intended without incurring credits, use the test email addresses listed below for all possible email verification results.
Test Email AddressDescription
invalid@example.comAn invalid email address
valid@example.comA valid email address
catch_all@example.comAccept-all or catch-all email address
unknown@example.comAn unknown email address
safe_to_send_yes@example.comSafe to send email address
safe_to_send_no@example.comNot a safe to send email address
safe_to_send_risky@example.comRisky email address
disposable@example.comDisposable email address
role@example.comRole- or group-based email address
free@example.comFree email provider address
gibberish@example.comGibberish email address
hard_bounce@example.comHard bounce email address
soft_bounce@example.comSoft bounce email address
suggested_email_address@example.comAn auto-suggested email address
syntax_error@example.comSyntax error email address
greylisted@example.comGreylisted email address
spamtrap@example.comSpamtrap email address
blocklist_email_address@example.comFound part of blocklist email address
allowlist_email_address@example.comFound part of allowlist email address
blocklist_domain@example.comFound part of blocklist domain
allowlist_domain@example.comFound part of allowlist domain
domain_not_found@example.comThe domain does not exist for the email address
not_a_mailserver@example.comNot a mail server email address
mailbox_not_found@example.comMailbox not found email address
mailbox_quota_exceeded@example.comMail quota exceeded email address
dns_query_timeout@example.comDNS query timeout email address
unroutable_mailserver@example.comUnroutable mail exchange server email address
overquota_and_inactive@example.comDormant email address
receiving_limit_reached@example.comReceiving limit exceeded email address
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.clearout.io/developers/api/overview.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.