Introduction
This is the official documentation for the Scamadviser API.
The API allows you to access various features and data provided by Scamadviser.
Versioning
We use API versioning to be apply to update and add functionality in newer API versions. The API version is specified in the API endpoint after the domain (e.g. https://api.scamadviser.cloud/v2/trust/batch/create).
API Access
The API can be accessed by passing along an API key. API keys can be obtained via our Product Team. Our Terms of service do apply to the usage of the API.
Depending on your API key you will have access to certain endpoints. Each API key is also assigned a result-mapper which determines the format and fields of the response.
Usage Limits
API keys have usage limits assigned to them. The limits are based on the number of API calls per month. You will receive an error response if you exceed your allocated quota. You are notified via e-mail when you are approaching your limit. Please contact our Product Team for more information about your quota.
Best Practices
- Always use our cache endpoint first before doing a full scan.
- For larger datasets, consider using the Batch API to submit multiple domains for processing in a single request.
- Always handle error responses gracefully and implement retry logic for transient errors.
Trust API
Single cache API
As the single endpoint takes upto 25 seconds to return a result, you should always start with calling the cache endpoint first. When that endpoint returns a status 404, we have no data in cache and the normal endpoint may be called.
When this endpoint returns a status 503, the data in the cache is older than 30 days and a new scan can be started by calling the normal endpoint.
Single API
The Single API endpoint is used to request our Trust data of a single url. Calling this endpoint go through a number of steps depending on a number of request parameters and if data is currently available and not stale:
If the domain of the url is blocked in our blocklist we return an status 404-error message and do nothing.
If we recently scanned the url (less then 24 hours ago) we return a status 200 with the cached data immediately.
If no recent cache, then we first do a DNS check to see if the domain of the url is registered somewhere. If it's not registered we return either the data we previously gathered if we scanned the domain before with 503 HTTP status (old data) or no data with a 404 HTTP status (not found).
If there is a DNS record, we do a network check to see if the url is currently available for us. The network check follows redirects. If the requested url is a redirect we will return data for the final url that we are redirected to and store a reference of the requested url to track all the redirects.
If the url is currently not available (to us), then we return either the data we previously gathered if we scanned the domain before with 503 HTTP status (old data) or no data with a 404 HTTP response (not found).
If the network check passed we trigger the data collection process and poll the cache for the domain data. We return the data as soon as it becomes available in the cache. The polling process will timeout after 25 seconds at which point we return all the currently available data from the data store. The cache will eventually be updated by the data collection process so that newer scans will provide the most recent data.
Finally, if we have any data available we map it with the mapper assigned the the API key that initialized the request and return the JSON object.
Batch Processing (Batch API)
Using the Single API for larger dataset of domains can be a bit cumbersome because you will have to request each domain individually. The Batch API give you the ability to submit multiple domains for processing to the API. The Batch API is for domains only via our API version 2
Calling the Batch API with a list of domains will create a new batch the batch. It stores the API key that created the batch as well as a batch name for easy reference and optionally an email address to which a notification will be sent after the batch is completely processed.
The API response contains a URL for requested the current status of the batch.
After the batch has been processed completely the system generates a JSON and a CSV file that contains the mapped domain objects for all the domains in the batch.
Mutations (API v2)
Domain mutation are used to adjust the calculated trust score. We provide several REST endpoints for managing mutation data.
Mutations to domains will also update URL trust data that belong to the mutated domain.
A domain mutation can be added or replaced. A replacement Domain Mutation deletes all existing domain mutations for the given domain(s) before adding new domain mutations of the same Trusted Source for the same Domain.
Data Feed (API v2)
We offer a complete data set via a feed:
- Every 5 minutes an update file in generated with the most recent changes.
- These are aggregated every hour to an hour file and every 24 hours to a daily file.
- Each file contains new and updated websites scanned and includes an MD5 checksum.
- All domain information can be included including among others:
- The domain name
- The trust score (0 - 100)
- The reasons why a certain trust score was given.
- All WHOIS data
- The aggregated consumer reviews
- Technologies used
- Etcetera
- The file format is JSON and is stored for 180 days
Using the API v2 endpoints will give you access to download these files.