Enrichment APIs Overview

The BigPicture.io enrichment APIs enable you to easily transform a domain into a detailed organization profile to connect with leads, provide audience insights, or even power sales & marketing automations.


Authenticating with the APIs are accomplished through the use of an API key. You can find your key in the BigPicture.io app under Settings.

When accessing the APIs, include your API Key within the "Authorization" header of your GET request. An example of this is shown to the right.

Sending your API key in the headers.

    curl 'https://company.bigpicture.io/v1/companies/find?domain=bigpicture.io' \
    -H 'Authorization: {API_KEY}'

Response Codes

All responses from use HTTP status codes along with additional information encoded as JSON in the response body in the message field. Generally, responses returned with a status code in the 2xx range indicate success, those in the 4xx range indicate an error usually resulting from a problem in the request or difficulty finding data, and those in the 5xx range indicate an issue on our servers.

Different errors may result in the same HTTP status code. Because of this, it is important to observe not only the response code, but also the JSON body, which will include additional details about the response, including more details around error cases.

A list of general response codes and a description of each is available below.

Code Description
200 - OK A match has been found.
202 - Accepted Occurs when email is not yet in our database or the data is stale.
400 - Bad Request There was an issue with the request, such as not including required parameters.
401 - Not Authorized You do not have access to the resource. It's usually due to forgetting to include your API key, or by reaching your quota limit.

404 - Not Found We could not find a match.
429 - Too Many Requests The request is denied because you have reached your request rate limit.
500 - Server Error Something is not working on our servers. If you see this, please send us an email at support@bigpicture.io.

Rate Limiting

All API requests are currently subject to rate limits of 600 requests per minute, apart from the streaming APIs that are set to 5 requests per minute. If you need a higher limit, email us and we can discuss it further.

Webhooks and Streaming

Our system works by doing a realtime search of various sources and doing a deep analysis of the data before returning a final result. Thus if a result is not already in our database, a realtime search can take some time before the data is ready. So there are couple different methods available for you to consider.


The default functionality is to return a 200 status with the data if it's in our database. Otherwise, if we need to do a search, we will return an empty 202 status. You can then make another request in a few minutes once we've had some time to process the data.


Webhooks are a mechanism that allow you to supply a URL to the API that we can send data to once an operation is complete.

Webhooks are defined in the request parameters using the webhookUrl field. You can also provide an optional webhookId parameter to link up requests and will be included in the final response.

When a webhook has been provided for a given request, an HTTP POST request will be sent to the URL provided once the process has completed. The payload of the POST request will be sent as JSON and include the following parameters.

Parameter Description
An optional field to help link requests.
Either a 200 code (success) or 404 (we couldn't find the data).
The type of resource - "company".
The company data

Webhook response

  "id": "Your optional webhook id",
  "status": 200,
  "type": "person",
  "body": {
    "name": "BigPicture.io",
    "description": "The easiest way to get advanced website analytics without writing any code.",
    "category": {
        "sector": "Technology",
        "industry": "Software & Computer Services",
        "subIndustry": "Internet",
        "industryGroup": "Technology"



An alternative to using webhooks is our streaming API. This API is ideal if you don’t mind long lived requests (e.g. you’re making requests to BigPicture from a messaging queue).

Requests made to the streaming API will never return a HTTP 202 status response, and can be held open for up to a 200 seconds.

The only difference between making calls to the normal and streaming API is the path - company.bigpicture.io/v1/companies/find/stream rather than company.bigpicture.io/v1/companies/find.

Stream example

        curl 'https://company.bigpicture.io/v1/companies/find/stream?domain=bigpicture.io' \
          -H 'Authorization: {API_KEY}'