# API integration

Sonar API allows you to retrieve data directly from Sonar database.\
\
The API currently provides two end points that return infographics, technographics as well as extra data for:

* Domains
* Emails

You need to retrieve the API key of your organisation to make calls with the API. The key can be found on the [integrations](http://localhost:3000/settings/integrations) page of your account.

## Enrichment methods

## Enrich a domain

<mark style="color:blue;">`GET`</mark> `https://api-public.purplesonar.com/api/v1/enrich/domain/:domain`

This endpoint returns infographic data for any domain you input.

#### Path Parameters

| Name                                     | Type   | Description                                                |
| ---------------------------------------- | ------ | ---------------------------------------------------------- |
| domain<mark style="color:red;">\*</mark> | string | Domain name of the company you would like to get data for. |

#### Query Parameters

| Name          | Type   | Description                                                                                                                                  |
| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| extra\_fields | string | <p>Comma separated list of additional fields you want to be returned by Sonar.<br><br>The only extra field we return for now is pricing.</p> |

#### Headers

| Name                                             | Type   | Description                                                                   |
| ------------------------------------------------ | ------ | ----------------------------------------------------------------------------- |
| Authentication<mark style="color:red;">\*</mark> | string | <p>Authentication token in the form of:<br>'Bearer <code>api\_key</code>'</p> |

{% tabs %}
{% tab title="200 Domain data found" %}

```
{
    "domain": "hellobonsai.com",
    "technologies": [
        "google cdn",
        "firstpromoter",
        "google analytics",
        "facebook",
        "intercom chat",
        "mixpanel",
        "customer.io",
        "google tag manager",
        "google apis",
        "jquery",
        "embed js",
        "headway",
        "stripe",
        "typeform",
        "google maps",
        "inspectlet",
        "segment",
        "highcharts",
        "google plus",
        "ably",
        "fontawesome cdn"
    ],
    "alexa_rank": 22117,
    "name": "Bonsai",
    "social_linkedin_url": "linkedin.com/company/bonsai",
    "social_facebook_url": null,
    "social_twitter_url": "/bonsaiinc",
    "year_founded": 2015,
    "employees_range": "11-50",
    "country": "United States",
    "location": "San Francisco, California, United States",
    "industry": "Information Technology And Services"
}
```

{% endtab %}

{% tab title="404 Could not find a cake matching this query." %}

```
{
    "message": "This domain hasn't been scanned yet"
}
```

{% endtab %}
{% endtabs %}

## Enrich an email

<mark style="color:blue;">`GET`</mark> `https://api-public.purplesonar.com/api/v1/enrich/email/:email`

Similarly to the domain endpoint, you can enrich an email to get the associated company's infographics and technographic

#### Path Parameters

| Name  | Type   | Description                                          |
| ----- | ------ | ---------------------------------------------------- |
| email | string | Email of the company you would like to get data for. |

#### Query Parameters

| Name          | Type   | Description                                                                                                                                  |
| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| extra\_fields | string | <p>Comma separated list of additional fields you want to be returned by Sonar.<br><br>The only extra field we return for now is pricing.</p> |

#### Headers

| Name           | Type   | Description                                                                   |
| -------------- | ------ | ----------------------------------------------------------------------------- |
| Authentication | string | <p>Authentication token in the form of:<br>'Bearer <code>api\_key</code>'</p> |

{% tabs %}
{% tab title="200 Domain data found" %}

```
{
    "domain": "hellobonsai.com",
    "technologies": [
        "google cdn",
        "firstpromoter",
        "google analytics",
        "facebook",
        "intercom chat",
        "mixpanel",
        "customer.io",
        "google tag manager",
        "google apis",
        "jquery",
        "embed js",
        "headway",
        "stripe",
        "typeform",
        "google maps",
        "inspectlet",
        "segment",
        "highcharts",
        "google plus",
        "ably",
        "fontawesome cdn"
    ],
    "alexa_rank": 22117,
    "name": "Bonsai",
    "social_linkedin_url": "linkedin.com/company/bonsai",
    "social_facebook_url": null,
    "social_twitter_url": "/bonsaiinc",
    "year_founded": 2015,
    "employees_range": "11-50",
    "country": "United States",
    "location": "San Francisco, California, United States",
    "industry": "Information Technology And Services"
}
```

{% endtab %}

{% tab title="404 Could not find a cake matching this query." %}

```
{
    "message": "This domain hasn't been scanned yet"
}
```

{% endtab %}
{% endtabs %}

## Lookup methods

## Lookup technologies for a domain

<mark style="color:blue;">`GET`</mark> `https://api-public.purplesonar.com/api/v1/domains/:domain/technologies`

This endpoint returns all current and past technologies for a given domain.\
\
The first\_seen\_at parameter is returning null when the first detection does not result from a signal. This could happen when we add a technology and scan a website against that technology for the first time, or when a page was previously hidden behind a paywall so that we couldn't scan it in the past.

#### Path Parameters

| Name                                     | Type   | Description                                                |
| ---------------------------------------- | ------ | ---------------------------------------------------------- |
| domain<mark style="color:red;">\*</mark> | String | Domain name of the company you would like to get data for. |

#### Headers

| Name                                             | Type   | Description                                                                   |
| ------------------------------------------------ | ------ | ----------------------------------------------------------------------------- |
| Authentication<mark style="color:red;">\*</mark> | String | <p>Authentication token in the form of:<br>'Bearer <code>api\_key</code>'</p> |

{% tabs %}
{% tab title="200: OK " %}

```javascript
[
    {
        "name": "Google Optimize",
        "category": "Marketing",
        "is_live": false,
        "last_seen_at": "2021-08-31",
        "first_seen_at": "2021-08-15"
    },
    {
        "name": "Google Tag Manager",
        "category": "Tag manager",
        "is_live": true,
        "last_seen_at": "2022-07-10",
        "first_seen_at": null
    },
    {
        "name": "Google CDN",
        "category": "Content Delivery Network (CDN)",
        "is_live": true,
        "last_seen_at": "2022-07-27",
        "first_seen_at": null
    },
    {
        "name": "FirstPromoter",
        "category": "Affiliates & partner management",
        "is_live": true,
        "last_seen_at": "2022-07-27",
        "first_seen_at": null
    },
    {
        "name": "Customer.io",
        "category": "Emailing",
        "is_live": false,
        "last_seen_at": "2021-10-26",
        "first_seen_at": null
    },
    {
        "name": "Embed JS",
        "category": "Javascript frameworks",
        "is_live": true,
        "last_seen_at": "2022-07-27",
        "first_seen_at": null
    },
    {
        "name": "jQuery",
        "category": "Javascript frameworks",
        "is_live": false,
        "last_seen_at": "2021-10-26",
        "first_seen_at": null
    },
    {
        "name": "Google Analytics",
        "category": "Analytics",
        "is_live": true,
        "last_seen_at": "2022-07-27",
        "first_seen_at": null
    },
    {
        "name": "Webflow",
        "category": "Content Management System (CMS)",
        "is_live": true,
        "last_seen_at": "2022-07-27",
        "first_seen_at": null
    },
    {
        "name": "BlueSnap",
        "category": "Payment",
        "is_live": true,
        "last_seen_at": "2022-07-27",
        "first_seen_at": null
    },
    {
        "name": "Segment",
        "category": "Analytics",
        "is_live": true,
        "last_seen_at": "2022-07-27",
        "first_seen_at": null
    },
    {
        "name": "Mixpanel SDK",
        "category": "Analytics",
        "is_live": false,
        "last_seen_at": "2021-12-30",
        "first_seen_at": null
    },
    {
        "name": "Facebook",
        "category": "Social",
        "is_live": false,
        "last_seen_at": "2020-08-05",
        "first_seen_at": null
    },
    {
        "name": "Google APIs",
        "category": "Utility",
        "is_live": true,
        "last_seen_at": "2022-07-27",
        "first_seen_at": null
    },
    {
        "name": "Inspectlet",
        "category": "Analytics",
        "is_live": false,
        "last_seen_at": "2021-08-31",
        "first_seen_at": null
    },
    {
        "name": "Reddit pixel",
        "category": "Social",
        "is_live": true,
        "last_seen_at": "2022-07-10",
        "first_seen_at": "2020-07-28"
    },
    {
        "name": "Hotjar",
        "category": "Session recording",
        "is_live": false,
        "last_seen_at": "2021-03-06",
        "first_seen_at": "2020-11-13"
    },
    {
        "name": "VWO",
        "category": "Session recording",
        "is_live": false,
        "last_seen_at": "2021-03-06",
        "first_seen_at": null
    },
    {
        "name": "Ably",
        "category": "Utility",
        "is_live": true,
        "last_seen_at": "2022-07-27",
        "first_seen_at": null
    },
    {
        "name": "Google Places",
        "category": "Maps",
        "is_live": true,
        "last_seen_at": "2022-07-27",
        "first_seen_at": null
    },
    {
        "name": "Crazy Egg",
        "category": "Analytics",
        "is_live": false,
        "last_seen_at": "2020-10-27",
        "first_seen_at": "2020-10-11"
    },
    {
        "name": "Intercom chat",
        "category": "Live chat",
        "is_live": true,
        "last_seen_at": "2022-07-27",
        "first_seen_at": null
    },
    {
        "name": "Cloudflare WAF",
        "category": "Security",
        "is_live": true,
        "last_seen_at": "2022-07-27",
        "first_seen_at": null
    },
    {
        "name": "Mixpanel",
        "category": "Analytics",
        "is_live": true,
        "last_seen_at": "2022-07-27",
        "first_seen_at": null
    },
    {
        "name": "Headway",
        "category": "Product management",
        "is_live": true,
        "last_seen_at": "2022-07-27",
        "first_seen_at": null
    },
    {
        "name": "Stripe",
        "category": "Payment",
        "is_live": true,
        "last_seen_at": "2022-07-27",
        "first_seen_at": null
    },
    {
        "name": "Typeform",
        "category": "Marketing",
        "is_live": true,
        "last_seen_at": "2022-07-27",
        "first_seen_at": null
    },
    {
        "name": "Google Maps",
        "category": "Maps",
        "is_live": true,
        "last_seen_at": "2022-07-27",
        "first_seen_at": null
    },
    {
        "name": "Highcharts",
        "category": "Utility",
        "is_live": true,
        "last_seen_at": "2020-04-23",
        "first_seen_at": null
    },
    {
        "name": "Google Plus",
        "category": "Social",
        "is_live": true,
        "last_seen_at": "2020-05-12",
        "first_seen_at": null
    },
    {
        "name": "FontAwesome CDN",
        "category": "Content Delivery Network (CDN)",
        "is_live": true,
        "last_seen_at": "2022-07-27",
        "first_seen_at": null
    }
]
```

{% endtab %}
{% endtabs %}

## Extra fields

For the enrichment endpoints, we return extra optional fields on demand if the `extra_fields` parameter exists in the url.

We only return the extra pricing field for now.\
\
For example, if you add the pricing extra\_field below:

```
https://api-public.purplesonar.com/api/v1/domains/:domain?extra_fields=pricing
```

Sonar will append the returned response with a pricing object as follow:

```
"pricing": {
        "pricing_page": "https://www.acme.com/pricing/",
        "subscription": {
            "has_trial": true,
            "has_annual_plan": null,
            "has_monthly_plan": true
        }
    }
```

{% hint style="warning" %}
Note that every key in the pricing object can be null (like 'subscription').

New keys might also be added overtime.
{% endhint %}