# 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](https://docs.clearout.io/developers/api/email-verify), [email finding](https://docs.clearout.io/developers/api/email-finder), reverse lookup, remaining credits, company-to-domain [auto-completion](https://docs.clearout.io/developers/api/autocomplete), and additional [domain](https://docs.clearout.io/developers/api/misc-domain-api) 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](https://docs.clearout.io/help-and-support). ### 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