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.

Authentication

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 100 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.

Default

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

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
id
string
An optional field to help link requests.
status
integer
Either a 200 code (success) or 404 (we couldn't find the data).
type
string
The type of resource - "company".
body
object
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"
    },
    ...
  }
}

  

Streaming

If you want to wait until the data is ready, you can include the stream parameter in your request. We will keep the request open for up to 200 seconds while we do a realtime lookup.

Stream example

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