Domain Search API

This endpoint enables you to discover email addresses associated with a domain name, website, or company name.
Additionally, you have the option to obtain highly accurate and unique company data enrichment.

ℹ️

You will be charged 1 credit for every 50 emails found, and no credit will be deducted if no results are found or the company has been searched previously.

Endpoint

POST https://api.prospeo.io/domain-search

curl -X POST \
 -H "Content-Type: application/json" \
 -H "X-KEY: your_api_key" \
 -d '{"company": "intercom.com", "limit": 10}' \
 "https://api.prospeo.io/domain-search"

Parameters

Parameter	Example value	Description
`company` ^required	`intercom.com`, `https://intercom.com`, `Intercom`	The company domain, website or name. Using a domain or website is recommended for better accuracy. If submitting a company name, it needs to be between 3 to 75 characters.
`limit`	`50`	How many emails you need. The default value is `50`. You will be charged 1 credit every 50 emails. For example, 35 emails will be charged 1 credit while 65 emails will be charged 2 credits.
`email_type`	`all` (default), `generic`, `professional`	Indicates what type of email you want to get. `generic` refers to role-based emails such as `[email protected]`, while `professional` are emails of people working at the company.
`company_enrichment`	`false` (default)	Indicates if you want the company details in the response. It is `false` by default. Turning it to `true` might slow-down the response time as we gather the company details.

⚠️

We strongly encourage you to submit the company domain/website instead of the company name for faster and better processing. To find the correct domain from your company name, our system leverages AI. While this allows us to find almost any company website, it is not as accurate as using the domain name. It also means that response times are longer when submitting a company name.

Response

The response will contain a JSON object. First, check if the error property is false. If it is true, refer to the section below to handle the error message.

ℹ️

Each email is associated with its own email_anon_id. You can use this email_anon_id to verify the email address using our /email-verifier API. If an email is INVALID or CATCH_ALL, the verification will be free.

{
    "error": false,
    "response": {
        "email_list": [
            {
                "email": "[email protected]",
                "email_type": "generic",
                "first_name": null,
                "last_name": null,
				"email_anon_id": "2LIGYFNPR0",
                "verification": {
                    "status": "VALID",
                    "last_verified_at": "2024-04-26 00:14:12+00:00"
                }
            },
            {
                "email": "[email protected]",
                "email_type": "professional",
                "first_name": "John",
                "last_name": "Doe",
				"email_anon_id": "Z3PSTVN3N2",
                "verification": {
                    "status": "UNVERIFIED",
                    "last_verified_at": null
                }
            },
			...
        ],
        "company_enrichment": {
            "name": "Intercom",
            "is_catch_all": false,
            "size": "501-1000",
            "logo": "https://assets.prospeo.io/company/1S2ING60HPQCAEQSTNF9.jpg",
            "linkedin": "https://www.linkedin.com/company/intercom",
            "website": "https://www.intercom.com",
            "common_email_pattern": "{first}{last}",
            "industry": "Computer Software",
            "founded_in": 2011,
            "description": "Intercom is the only complete Customer Service solution that provides a seamless customer experience across automation and human support ...",
            "location": {
                "country": "United States",
                "country_code": "US",
                "state": "California",
                "city": "San Francisco",
                "timezone": "America/NewYork",
                "timezone_offset": "-4.0",
                "postal_code": "94105",
                "address": "55 2nd Street"
            },
			"anon_id": "OYFW4RJN5C",
        },
        "meta": {
            "search_id": "F55W0RJ5NE",
            "total_emails": 185,
            "remaining_emails": 135,
            "more_results": true,
            "domain": "intercom.com",
            "limit": 50
        }
    }
}

The email_list array will contain the email we found linked to the company. If no results are found, the email_list will be empty and you won't be charged.

Pagination: retrieve more emails

If the number of emails exceeds your request limit (default is 50), you can retrieve the remaining emails by using pagination. You'll be charged for every 50 unique emails you pull, irrespective of the limit set or the number of requests you make.

To implement pagination, follow these steps:

Check the more_results field in the meta property of the response. If more_results is true, it means there are more emails available.
If more emails are available, use the search_id (also found in the meta object) and send it to the same endpoint in a new request.

For instance, to pull more emails, you might use a curl command like this:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-KEY: your_api_key" \
  -d '{"search_id": "4G8CX024BE"}' \
  "https://api.prospeo.io/domain-search"

By invoking the /domain-search endpoint again with the search_id, the system will return the next set of emails based on your original request settings (same limit, same email_type ...).

Note: you can continue to pull results 3 hours after the initial search, then the results will expire.

Specific error codes

ℹ️

If you can't find the error message on this list, check our general error message.

Error code	Message	Meaning
`400`	`INVALID_DOMAIN_NAME`	The domain name you submitted is not reachable or does not have valid MX records.
`400`	`INVALID_COMPANY`	The company name you submitted is invalid (3-75 characters).
`400`	`CANT_FIND_DOMAIN`	We can't find which domain name this company use for sure, so instead of returning a false-positive, we return this message.
`400`	`DOMAIN_IS_WEBMAIL`	The company you submitted is a webmail (Gmail, Outlook and others)

Rate limit

The rate limits are:

1000 call per minute
50 call per second (burst allowance)

When the limit is reached, we will return a 429 error code.

ℹ️

If you need your rate limit to be increased, feel free to contact us at [email protected].

Response time

In the majority of cases, the response time to this endpoint is fast, as the emails are stored in-house. However, our algorithm sometimes will try to dig the web in real-time to find additional emails. In this case, response time might increase. The average response time is 250ms, but in the case of real-time digging, the response time might be extended to 5 seconds. Please allow enough time for the request to complete.

ℹ️

In any case, we have setup hard limits over our response time, so no fear to have: your system will never be hanging indefinitely.