Dispute API
The Dispute Verdict API allows Bolster customers to dispute the verdict (disposition) of one or more URLs on the Bolster platform. When a URL has been scanned, and you believe the disposition is incorrect, you can use this API to submit a dispute for review.
Important Notes
- The dispute will be submitted under the brand associated with your API key. Unlike the platform UI, you cannot select a different brand when disputing via the API.
- The URL must have been scanned at least once in the last 90 days and must be present in the Bolster scanning records. URLs that have not been scanned cannot be disputed.
- The API always disputes the latest scan record of the URL. If a URL has been scanned multiple times, the most recent record will be updated.
- Each URL goes through multiple validations before being disputed. The API response includes a per-URL status with the reason if a URL was skipped or invalid.
Step 1: Locate Your API Key
Before using the Dispute Verdict API, you need your Bolster API Key. Follow these steps to find it:
- Click on the user dropdown in the top-right corner of the page.
- Select Profile Information from the dropdown menu.
- Copy the API key displayed on your profile screen.
Step 2: Initiate Request Through API
Endpoint:/api/neo/v1/dispute-verdict
API Host:https://developers.bolster.ai
To make a Dispute Verdict request, use the following details.
Request Format
curl --location 'https://developers.bolster.ai/api/neo/v1/dispute-verdict' \
--header 'Content-Type: application/json' \
--data '{
"apiKey": "<your_api_key>",
"urls": [
"http://sample-phish.com/",
"http://example-scam.net/login",
"http://brand-asset.com/",
"http://already-phish.com/",
"http://different-brand.com/",
"http://url-not-found.com/",
"not-a-valid-url",
"brand-asset.com"
],
"disposition": "phish",
"comment": "These URLs are impersonating our brand."
}'Request Parameters
- apiKey (required): Your user API key.
- urls (required): List of URLs to dispute, formatted as an array of strings. Maximum 20 URLs per request.
- disposition (required): The disposition you believe is correct. Must be one of: phish, scam, suspicious, clean.
- comment (required): Justification for the dispute. Maximum 1000 characters.
Response
The API returns a per-URL status for each URL in the request. Each URL is individually validated and processed.
Response Fields
| Field | Description |
|---|---|
| success | Whether the request was processed successfully. |
| total | Total number of URLs submitted. |
| disputed | Number of URLs successfully disputed. |
| skipped | Number of URLs skipped due to validation. |
| invalid | Number of URLs that could not be normalized or are malformed. |
| duplicate | Number of duplicate URLs after normalization. |
| results | An array of per-URL result objects. Each object contains the validation outcome for a URL. See Per-URL Result Fields below. |
Per-URL Result Fields
Each object in the results array contains the following fields:
| Field | Description |
|---|---|
| url | The original URL as submitted in the request. |
| normalizedUrl | The URL after normalization (e.g., protocol and trailing slash added). |
| status | One of: disputed, skipped, invalid, duplicate. |
| success | true if the URL was disputed, false otherwise. |
| message | Human-readable reason for the status. |
Successful Response (Status Code: 200)
The following example shows a response where some URLs were disputed, some were skipped, one was invalid, and one was a duplicate:
{
"success": true,
"total": 8,
"disputed": 2,
"skipped": 4,
"invalid": 1,
"duplicate": 1,
"results": [
{
"url": "http://sample-phish.com/",
"normalizedUrl": "http://sample-phish.com/",
"status": "disputed",
"success": true,
"message": "Dispute submitted successfully."
},
{
"url": "http://example-scam.net/login",
"normalizedUrl": "http://example-scam.net/login",
"status": "disputed",
"success": true,
"message": "Dispute submitted successfully."
},
{
"url": "http://brand-asset.com/",
"normalizedUrl": "http://brand-asset.com/",
"status": "skipped",
"success": false,
"message": "URL is a brand asset and cannot be disputed."
},
{
"url": "http://already-phish.com/",
"normalizedUrl": "http://already-phish.com/",
"status": "skipped",
"success": false,
"message": "URL is already phish and cannot be disputed."
},
{
"url": "http://different-brand.com/",
"normalizedUrl": "http://different-brand.com/",
"status": "skipped",
"success": false,
"message": "URL is not associated with your brand and cannot be disputed."
},
{
"url": "http://url-not-found.com/",
"normalizedUrl": "http://url-not-found.com/",
"status": "skipped",
"success": false,
"message": "No scan record found for this URL in the last 90 days. Please scan it first before disputing."
},
{
"url": "not-a-valid-url",
"normalizedUrl": "not-a-valid-url",
"status": "invalid",
"success": false,
"message": "URL could not be normalized or is invalid."
},
{
"url": "brand-asset.com",
"normalizedUrl": "http://brand-asset.com/",
"status": "duplicate",
"success": false,
"message": "Normalized duplicate URL."
}
]
}URL Validation Reasons
A URL may be skipped for the following reasons:
| Message | Reason |
|---|---|
| URL is not associated with your brand and cannot be disputed. | The URL belongs to a different brand. |
| URL is a brand asset and cannot be disputed. | The URL is registered as a brand asset. |
| URL is already {disposition} and cannot be disputed. | The URL already has the same disposition you are trying to dispute. |
| No scan record found for this URL in the last 90 days. Please scan it first before disputing. | No scan record found for this URL in the last 90 days. |
| URL could not be normalized or is invalid. | The URL format is invalid or cannot be parsed. |
| Normalized duplicate URL. | After normalization, this URL is a duplicate of another URL in the same request. |
Error Responses
If the request payload is invalid, the API returns an error response before processing any URLs.
Status Code: 401
{
"error": {
"statusCode": 401,
"name": "Error",
"message": "Invalid API key or API key not enabled."
}
}Status Code: 400
The following 400 errors may be returned:
Invalid disposition:
{
"error": {
"statusCode": 400,
"name": "Error",
"message": "Invalid disposition. Must be one of: phish, scam, suspicious, clean."
}
}Missing comment:
{
"error": {
"statusCode": 400,
"name": "Error",
"message": "comment is a required argument"
}
}Comment too long:
{
"error": {
"statusCode": 400,
"name": "Error",
"message": "Comment cannot exceed 1000 characters."
}
}Too many URLs:
{
"error": {
"statusCode": 400,
"name": "Error",
"message": "Maximum 20 URLs allowed to be disputed at once."
}
}Support
If you have any questions or encounter any issues while using the Dispute Verdict API, please contact our support team at support@bolster.ai.
