NAV
shell

Introduction

The Squirrel API brings all the functionality from squirrel to an REST API.

We allow users to search for a single product code ( ASIN, UPC, EAN or SKU) and the API will retrieve the matched product(s) around the globe ( over 10 countries ).

Knowing the product codes, or the product ID within the API, the user will easily access all the retailer’s offers, with the ability to have their own reseller id to get commission-worthy links.

The response from the API will provide the product details, such as recommended retail price, live price, product image and product description in various counties.

This all runs from the Squirrel portal, allowing you to enter your affiliate network details and select the retailers you wish to work with.

Squirrel API also allow you to search for the product name, retailer URL or even by Make & Model.

Authentication

Squirrel API uses a Bearer token to allow access to the API. You can send your auth token like this:

Authorization: Bearer [YOUR_ACCESS_TOKEN]

To get your Bearer token you need to login to your Squirrel account and navigate to API info

Server Info

API endpoint: https://api.getsquirrel.co/api/v2
Limits: - Requests are limited to 1 Request per second - On a single product search request, 10 product codes can be sent

Products

Search by Code

  curl --location --request POST 'https://api.getsquirrel.co/api/v2/products/search' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
--form 'code="B07ZPC9QD4"' 

The above command returns JSON structured like this:

[
  {
    "data": {
      "B07ZPC9QD4": [
        {
          "name": "Apple AirPods Pro",
          "squirrel_id": 2686508,
          "price": 95,
          "rrp": 249,
          "offer_url": "https://www.ebay.co.uk/itm/284378464855?hash=item4236470257%3Ag%3AaNYAAOSwFv1g9uOB&mkevt=1&mkcid=1&mkrid=710-53481-19255-0&campid=5338111205&customid=bestsquirreldeals&toolid=10049",
          "retailer": {
            "id": 14,
            "name": "eBay UK",
            "logo_url": "https://squirrels.getsquirrel.co/assets/images/retailers/ebayuk-compressor.png"
          },
          "image": "https://squirrels.getsquirrel.co/assets/images/products/149650-apple-airpods-pro.5,0",
          "last_updated": null,
          "last_updated_timestamp": null,
          "all_offers": [
            {
              "id": 47647714,
              "price": 95,
              "offer_url": "https://www.ebay.co.uk/itm/284378464855?hash=item4236470257%3Ag%3AaNYAAOSwFv1g9uOB&mkevt=1&mkcid=1&mkrid=710-53481-19255-0&campid=5338111205&customid=bestsquirreldeals&toolid=10049",
              "retailer": {
                "id": 14,
                "name": "eBay UK",
                "logo_url": "https://squirrels.getsquirrel.co/assets/images/retailers/ebayuk-compressor.png"
              }
            },
            {
              "id": 46018224,
              "price": 189.97,
              "offer_url": "https://track.webgains.com/click.html?wgcampaignid=206781&wgprogramid=272145&product=1&wglinkid=2775635&productname=Apple+AirPods+Pro+-+White+Active+Noise+Cancelling&wgtarget=https://www.laptopsdirect.co.uk/apple-airpods-pro-white-mwp22zm-a/version.asp&clickref=bestsquirreldeals",
              "retailer": {
                "id": 10839,
                "name": "Laptops Direct UK",
                "logo_url": "https://squirrels.getsquirrel.co/assets/images/retailers/laptopsdirect.png"
              }
            },
            {...}
          ],
          "top_offer": {
            "id": 47647714,
            "price": 95,
            "offer_url": "https://www.ebay.co.uk/itm/284378464855?hash=item4236470257%3Ag%3AaNYAAOSwFv1g9uOB&mkevt=1&mkcid=1&mkrid=710-53481-19255-0&campid=5338111205&customid=bestsquirreldeals&toolid=10049",
            "retailer": {
              "id": 14,
              "name": "eBay UK",
              "logo_url": "https://squirrels.getsquirrel.co/assets/images/retailers/ebayuk-compressor.png"
            }
          },
          "description": "Apple AirPods Pro MWP22 with Wireless Charging Case - White",
          "product_codes": {
            "ASIN": "B07ZPML7NP",
            "EAN": [
              "190199247000",
              "0190199247000",
              "00190199247000"
            ],
            "SKU": [
              "0190199247000"
            ],
            "UPC": [
              "190199246850",
              "0190199246850",
              "00190199246850"
            ],
            "MPN": [
              "MWP22ZM/A"
            ]
          },
          "country": "GB"
        }
      ]
    }
  }
]

Endpoint that allows to search for a product by code or URL

HTTP Request

POST https://api.getsquirrel.co/api/v2/products/search

Query Parameters

Parameter Type Description
squirrel_id integer An numerical value representing the Squirrel ID representing a product on our DB, this value can get access on a previous API response or on the Squirrel Dashboard.
code string Alphanumerical code to search the DB, can be EAN, UPC, SKU or ASIN ( when available ). To search for multiple products, send the codes separated by the symbol ' | '.
urls string Well-formed URLs can be sent to retrieve products, it is mandatory that each URL starts with "http" or "https". To search for multiple products, send the urls separated by the symbol ' | '.
country string ISO code of the country to filter the results. When empty, all existant countries will be returned.
To send multiple countries, use comma separated values, ex.: "UK,US,AU"
show_with_offers_only boolean If you only want products with offers, send 'true'.
search_live_apis boolean deprecated Allow the API to search live our Partners APIs ( like Amazon ). This will make the response slower. By default, the API will not look into Partner's API in realtime, it will store the request on the DB and fetch products and offers offline.
cache_ttl integer Use this parameter to reduce the amount of seconds the result is cached on Squirrel's end. Sending '0' will force the cache to be refreshed. ( you'll get a response with a "check later" message )

Responses

Squirrel API always give a response in milliseconds, to make sure your client application doesn't hang waiting for a response. If the request is not new for Squirrel you'll get the cached version of the response. When the cache ttl ( default 120 minutes ) is hit, the response will be refreshed in the backend, and stored in the caching system to be ready for the next time you execute the same request.

For each request, and after it gets cached, you'll get the product information - for each requested product, and each country - with the following fields:

Generic information

Property Description
monthly_quota The total amount of requests you can make every 30 days
current_usage The amount of requests made since the renewal of your subscription
error True/ False value to indicate if the data object contains error information
data Object with the Product Information ( see description below )
request_ids Object that contains the ids ( an hash ) for each cached response, each code/ URL/ term will have one

Product Information

Property Description
name The product name for the country
squirrel_id The unique ID for that product on your account. This is the same squirrel_id you can use on the widget to display this product in a webpage, or to use on "little squirrel"
price The price of the product, in that country. This is the price for the Best offer.
rrp The Recommended retail price - this is the price the manufacturer recommends as a retailer price.
offer_url The monetizable URL to be used for the best offer for this product. It already has your tracking ids and your affiliate tracking ids for the selected retailer.
retailer An Retailer object with the information about the retailer for the best offer ( see Retailer object description below )
image Product image URL
all_offers An array of Offers objects ( see Offer object description below ), this value can be empty when no offers match the requested product in the requested country
used_offers An array of Offers objects, this array contains only offers that were flagged as "Used"
refurbished_offers An array of Offers objects, this array contains only offers that were flagged as "Refurbished"
top_offer The best selected Offer object ( see Offer object description below ), this value can be empty when no offers match the requested product in the requested country
no_affiliate_offers This property contains all the offers we have for this product but you don't have the retailer activated. Check your Squirrel account to activate them.
description The product description, this information is retrieved from random retailers, might not be very accurate.
product_codes All the codes for the requested product in the provided country ( ASIN, EAN, SKU, UPC, MPN )
country The ISO-2 code for the country the above information is related to

Offer Object

Property Description
id Internal offer id
price The numeric value of the price, the prices do not contain any currency information since they are attached to a country
offer_url The monetizable URL to be used for this offer
offer_url_clean The direct link to the product page on the selected retailer ( this could be empty/ null due to lack of information from the retailer )
retailer An Retailer object with the information about the retailer for the current offer ( see Retailer object description below )
retailer_id Internal ID for the retailer
affiliate_network_id Internal ID for the affiliate network
api_id Internal ID for the api where this offer was fetched from
rrp The Recommended retail price - this is the price the manufacturer recommends as a retailer price.
image_url An URL for an image provided by the retailer, could be different from the image Squirrel provides.
max_price The highest price Squirrel registered for this retailer for this product on the 90 days prior to the request
min_price The lowest price Squirrel registered for this retailer for this product on the 90 days prior to the request.
in_stock_status A boolean value to provide information if the product is in stock or not. By defaul, Squirrel removes the offers out of stock, you can change this setting on your account.

Retailer Object

Property Description
id Internal Squirrel id for the retailer
name Name of the retailer on the Squirrel Database
logo_url Squirrel's image url for the retailer


Responses when there isn't product information

[ ] - When the product doesn't match any value on Squirrel's Database.

You can get a message instead of an empty array or the product information, these are the possible messages and the scenarios when they could be seen:

"Squirrel is looking for this product and adding it to the DB."
- Squirrel doesn't know that product, it is being added to the Database to find prices/ codes/ cross-country matches.

"We are almost there, please check again later! Current status: [STATUS]"
Squirrel is processing the request. Different possible status:
- Pending: The request wasn't picked up yet.
- Rejected: The product was rejected by Squirrel because the code is invalid.
- PendingSearch: Squirrel is fetching this product on all retailers.
- Excessive Results: Squirrel got too many results for the specified code, and wasn't able to do a valid match, please use a different code for the same product.
- Not Found: Squirrel wasn't able to find any match for the provided code. Please try adding more retailers to your Squirrel account to increase the search area for Squirrel.

"We are refreshing our cache with the latest response for you."
- It's a new request, and Squirrel will fulfill it in the backend.
- The Squirrel cache was forced to be refreshed.

Search by text

  curl --location --request POST 'https://api.getsquirrel.co/api/v2/terms/search' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
--form 'term="Apple iphone 14"' 

The above command returns JSON structured like this:

[
    {
        "name": "Apple iPhone 14 (128 GB) - Blue",
        "squirrel_id": null,
        "rrp": 849,
        "image": "https://m.media-amazon.com/images/I/31VjlrbE3bL._SL160_.jpg",
        "description": "",
        "product_codes": {
            "EPID": "",
            "ASIN": [
                "B0BDJHR5DD"
            ],
            "EAN": [
                "0194253409571"
            ],
            "UPC": [
                "194253409571"
            ],
            "SKU": [],
            "MPN": [
                "MPVN3ZD/A"
            ]
        },
        "country": "GB"
    },
    {
        "name": "Apple iPhone 14 Plus (128 GB) - Starlight",
        "squirrel_id": null,
        "rrp": 949,
        "image": "https://m.media-amazon.com/images/I/31XbWVKOFWL._SL160_.jpg",
        "description": "",
        "product_codes": {
            "EPID": "",
            "ASIN": [
                "B0BDHYZ6ZN"
            ],
            "EAN": [
                "0194253373704"
            ],
            "UPC": [
                "194253373704"
            ],
            "SKU": [],
            "MPN": [
                "MQ4Y3ZD/A"
            ]
        },
        "country": "GB"
    },
    {
        "name": "Apple iPhone 14 Pro (128 GB) - Deep Purple",
        "squirrel_id": null,
        "rrp": 1099,
        "image": "https://m.media-amazon.com/images/I/31MX9scnEzL._SL160_.jpg",
        "description": "",
        "product_codes": {
            "EPID": "",
            "ASIN": [
                "B0BDJ279KF"
            ],
            "EAN": [
                "0194253402169"
            ],
            "UPC": [
                "194253402169"
            ],
            "SKU": [],
            "MPN": [
                "MQ0G3ZD/A"
            ]
        },
        "country": "GB"
    },
    {
        "name": "Apple iPhone 14 Pro Max (128 GB) - Silver",
        "squirrel_id": null,
        "rrp": 1199,
        "image": "https://m.media-amazon.com/images/I/31O8D6p7sfL._SL160_.jpg",
        "description": "",
        "product_codes": {
            "EPID": "",
            "ASIN": [
                "B0BDHTRL5X"
            ],
            "EAN": [
                "0194253380177"
            ],
            "UPC": [
                "194253380177"
            ],
            "SKU": [],
            "MPN": [
                "MQ9Q3ZD/A"
            ]
        },
        "country": "GB"
    }
]

HTTP Request

POST https://api.getsquirrel.co/api/v2/terms/search

Query Parameters

Parameter Type Description
term string Text to search the API.
country string ISO code of the country to filter the results. If this field is empty, the results will be for UK.

Response

Product Information

Property Description
name The product name for the country
squirrel_id The unique ID for that product on your account. This is the same squirrel_id you can use on the widget to display this product in a webpage, or to use on "little squirrel"
rrp The Recommended retail price - this is the price the product was put on the market
image Product image URL
description The product description, this information is retrieved from random retailers, might not be very accurate.
product_codes All the codes for the requested product in the provided country ( ASIN, EAN, SKU, UPC, MPN )
country The ISO-2 code for the country the above information is related to

Webhooks

Squirrel provides to the Squirrel Expert plan subscribers the ability to receive product updates via a webhook functionality. Contact a team member to have this setup on your account.

Endpoints

With the following endpoints, the user can check for a webhook and activate it or disable it.

Use the request_id you got from the response on any other endpoint to the webhooks endpoints

GET https://api.getsquirrel.co/api/v2/webhooks/{request_id}
This endpoint will reply with the information on the specified webhook

Parameter Type Description
with_data boolean Request the response to have the content of the webhook
Property Description
squirrel_id The Squirrel ID the webhook provides information on
request_hash The request id
created_at The date when the webhook was created on the system
last_webhook_at The most recent date the webhook was sent to the client
active The status of the webhook ( If active = 1, the webhook is active and will be sent when a update occurs. If active = 0 this webhook is paused )
content When requested, this property will have the content of the webhook

DELETE https://api.getsquirrel.co/api/v2/webhooks/{request_id}
Disables/ pause a webhook

PUT https://api.getsquirrel.co/api/v2/webhooks/{request_id}
Reactivates a webhook

Countries

The Countries endpoint will return all the supported countries by the Squirrel API.

List

  curl --location --request GET 'https://api.getsquirrel.co/api/v2/utils/countries' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' 

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "iso": "GB",
    "name": "United Kingdom"
  },
  {
    "id": 2,
    "iso": "US",
    "name": "United States"
  },
  {
    "id": 13,
    "iso": "AU",
    "name": "Australia"
  },
  {
    "id": 38,
    "iso": "CA",
    "name": "Canada"
  },
  {
    "id": 73,
    "iso": "FR",
    "name": "France"
  },
  {
    "id": 80,
    "iso": "DE",
    "name": "Germany"
  },
  {
    "id": 99,
    "iso": "IN",
    "name": "India"
  },
  {
    "id": 105,
    "iso": "IT",
    "name": "Italy"
  },
  {
    "id": 150,
    "iso": "NL",
    "name": "Netherlands"
  },
  {
    "id": 199,
    "iso": "ES",
    "name": "Spain"
  },
  {
    "id": 205,
    "iso": "SE",
    "name": "Sweden"
  }
]

Show all supported countries. Code and Id.

HTTP Request

GET https://api.getsquirrel.co/api/v2/utils/countries

Query Parameters

No parameters

Statistics

Impressions

  curl --location 'https://api.getsquirrel.co/api/v2/stats/impressions' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
--form 'page="1"' \
--form 'per_page="5"' \
--form 'start_date="2023-01-01"' \
--form 'end_date="2023-01-31"' 

The above command returns JSON structured like this:

{
  "total_results": 17969,
  "page": 1,
  "total_pages": 3594,
  "stats": [
    {
      "date": "2023-01-01",
      "count": "1",
      "squirrel_id": "2687282",
      "url": "https://www.bestsquirreldeals.com/pc-and-video-games-deals/150436-farpoint",
      "render_type": ""
    },
    {
      "date": "2023-01-01",
      "count": "1",
      "squirrel_id": "4340492",
      "url": "https://www.bestsquirreldeals.com/pc-and-video-games-deals/150436-farpoint",
      "render_type": ""
    },
    {
      "date": "2023-01-01",
      "count": "1",
      "squirrel_id": "12861893",
      "url": "https://www.bestsquirreldeals.com/pc-and-video-games-deals/150436-farpoint",
      "render_type": ""
    },
    {
      "date": "2023-01-01",
      "count": "1",
      "squirrel_id": "12856113",
      "url": "https://getsquirrel.co/",
      "render_type": ""
    },
    {
      "date": "2023-01-01",
      "count": "1",
      "squirrel_id": "4340492",
      "url": "https://getsquirrel.co/",
      "render_type": ""
    }
  ]
}

This endpoint will provide the raw data for all the Impressions of Squirrels on your account.

HTTP Request

POST https://api.getsquirrel.co/api/v2/stats/impressions

Query Parameters

Property Description
start_date The start date for the interval of data to get statistics. ( date format: YYYY-MM-DD, example: 2023-01-01 )
end_date End of the date interval to query the stats ( max interval 31 days )
page The page number to retrieve from the total_pages
per_page Amount of results per page ( max value: 1,000 )

Response

Meta information

Property Description
total_results The amount of results the performed query returned
page The retrieved page
total_pages The amount of pages generated to be queried considering the amount of results and the per_page parameter

Stats

Property Description
date The day the event occurred ( date format: YYYY-MM-DD, example: 2023-01-01 )
count The amount of times that event happened
squirrel_id The unique ID for that product on your account. This is the same squirrel_id you can use on the widget to display this product in a webpage, or to use on "little squirrel"
url The URL referrer where the event occurred ( this information depends on a large number of factors, Sometimes you might just see your domain here ( for example AMP pages dont allow widgets to collect this data )
render_type This is the type of impression, possible values: '' ( empty, the default ), 'tbc' ( when the impression happened without offers )

Clicks

  curl --location 'https://api.getsquirrel.co/api/v2/stats/clicks' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
--form 'page="1"' \
--form 'per_page="5"' \
--form 'start_date="2023-01-01"' \
--form 'end_date="2023-01-31"' 

The above command returns JSON structured like this:

{
  "total_results": 7,
  "page": 1,
  "total_pages": 2,
  "stats": [
    {
      "date": "2023-01-05",
      "count": "1",
      "squirrel_id": "2685401",
      "url": "https://www.bestsquirreldeals.com/electronics-and-photo-deals/143157-sony-a9",
      "offer_type": "default",
      "retailer": "Amazon UK"
    },
    {
      "date": "2023-01-05",
      "count": "1",
      "squirrel_id": "2693196",
      "url": "https://www.bestsquirreldeals.com/electronics-and-photo-deals/156521-sigma-85mm-f1-4-dg-dn",
      "offer_type": "default",
      "retailer": "Wex Photo Video"
    },
    {
      "date": "2023-01-05",
      "count": "1",
      "squirrel_id": "2693196",
      "url": "https://www.bestsquirreldeals.com/electronics-and-photo-deals/156521-sigma-85mm-f1-4-dg-dn",
      "offer_type": "default",
      "retailer": "Very.co.uk"
    },
    {
      "date": "2023-01-05",
      "count": "1",
      "squirrel_id": "2693196",
      "url": "https://www.bestsquirreldeals.com/electronics-and-photo-deals/156521-sigma-85mm-f1-4-dg-dn",
      "offer_type": "default",
      "retailer": "Wex Photo Video"
    },
    {
      "date": "2023-01-14",
      "count": "1",
      "squirrel_id": "2711615",
      "url": "https://www.bestsquirreldeals.com/electronics-and-photo-deals/camera-and-photo-price/digital-cameras/307357-olympus-om-d-e-m5-mark-iii-micro-four-thirds-syste",
      "offer_type": "default",
      "retailer": "Clifton Cameras"
    }
  ]
}

This endpoint will provide the raw data for all the Impressions of Squirrels on your account.

HTTP Request

POST https://api.getsquirrel.co/api/v2/stats/impressions

Query Parameters

Property Description
start_date The start date for the interval of data to get statistics. ( date format: YYYY-MM-DD, example: 2023-01-01 )
end_date End of the date interval to query the stats ( max interval 31 days )
page The page number to retrieve from the total_pages
per_page Amount of results per page ( max value: 1,000 )

Response

Meta information

Property Description
total_results The amount of results the performed query returned
page The retrieved page
total_pages The amount of pages generated to be queried considering the amount of results and the per_page parameter

Stats

Property Description
date The day the event occurred ( date format: YYYY-MM-DD, example: 2023-01-01 )
count The amount of times that event happened
squirrel_id The unique ID for that product on your account. This is the same squirrel_id you can use on the widget to display this product in a webpage, or to use on "little squirrel"
url The URL referrer where the event occurred ( this information depends on a large number of factors, Sometimes you might just see your domain here ( for example AMP pages dont allow widgets to collect this data )
offer_type This is the type of the clicked offer, possible values: 'default' ( a normal retailer offer ), 'tbc' ( when the click happened on a "Check Price Here" offer ), 'tds' ( when using the TDS plugin, the click was on a Mobile deal offer )
retailer The clicked offer's retailer name

Squirrel Notify Alerts

You can set up email and webhook alerts to track when a price drops for a specific Squirrel.

The Squirrel API allows you to manage your Squirrel Notify system.
Via the API you're able to create, deactivate or check the status of an alert

Alert Object

Property Description
id Internal offer id
name Name of the user that requested the alert
squirrel_id Squirrel associated with the request
squirrel_page_url URL of the page where the alert was requested
country ISO of the alert's country
alert_type_id Type of alert ( Possible values: 1 - Back In Stock, 2 - Price drop )
alert_method_id Method to fulfill the alert when triggered ( Possible values: 1 - Email, 2 - Webhook)
alert_method_value Target value of the alert (for example: 350.00 (when the alert is for price))
created_at Date the alert was created
updated_at Date when the alert was last updated
active Alert status ( 1 - Active, 0 - Inactive )
retailer Retailer object for when the alert is targeted to a particular retailer

Create an alert

HTTP Request

POST https://api.getsquirrel.co/api/v2/alerts

Query Parameters

Parameter Type Description
squirrel_id integer An numerical value representing the Squirrel ID representing a product on our DB, this value can get access on a previous API response or on the Squirrel Dashboard.
country string ISO code of the country.
alert_type_id integer Type of alert ( Possible values: 1 - Back In Stock, 2 - Price drop )
alert_method_id integer Method to fulfill the alert when triggered ( Possible values: 1 - Email, 2 - Webhook)
value_type string Type of the value for the alert ( Possible values: percentage, price )
alert_value string Value for the alert ( example: 10 ( 10% for when 'value_type' is 'percentage')
retailer_id integer ID of the retailer to target the alert (if empty, any retailer available for the squirrel will be targeted)
user_name string Name of the targeted user
user_email string If 'alert_method_id' is email, this is the email that will be used to alert the user
first_email integer Option for the Squirrel system to send an email to the user when the alert is created (1 - Send, 0 - Ignore)

Query Parameters

An alert object

Check an alert

GET https://api.getsquirrel.co/api/v2/alerts/{alert_id}

Delete an alert

DELETE https://api.getsquirrel.co/api/v2/alerts/{alert_id}

Errors

The Squirrel API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid ( A message is returned with the problem explantion ).
401 Unauthorized -- Your API key is wrong.
404 Not Found -- The method doesn't exist.
429 Too Many Requests -- You're making too many requests and going over your RPS ( Requests per second ) allowance ( 1 by default )
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.