Sending new Signal reports via API

24 March 2025

These APIs facilitate the sending of new signal reports to the GSE using standard POST requests.

The structured data API supports the sending of signals using the minimal data format (Signal, Report Date and Abuse Type) with options to supply additional attributes for Signal Type, Confidence Score and a Predictive indicator as well as Extra Data which may be supplied for enrichment purposes as adhoc simple key/value pairs.

The image and text APIs allow for new signals to be automatically detected from the text contained in images or from raw text strings and sent to the GSE. This is particularly useful if an abuse report has come in the form of a screenshot or other image or as a scam message e.g. SMS - this API removes the need for additional conversion to structured data prior to submission. For these signals the full text extracted from the image / text block is stored as Extra Data on submission.

POSThttps://signals.gse.live/report/signal

Sending new signal reports as structured data

Send one or more new signal reports as structured data.

Payload Attributes

Required attributes

Name
signal
Type
mediumstring
Description
The signal you want to share.

Name
report_date
Type
datetime
Description
Date & time the signal was reported. This must be supplied as a date and time in YYYY-MM-DD HH:MM:SS format.
eg. 2020-01-23 14:24:06

Name
abuse_type
Type
string
Description
The type of abuse this signal represents. Must be one of the following types...
If you would like to send us a different abuse type, please contact us
Loading options....

Optional attributes

Name
predictive
Type
boolean
Description
An indication that this signal was generated using an algorithm rather than confirmed report.

Name
confidence_score
Type
integer
Description
Number between 0-100. A score of 100 would indicate the highest confidence in this signal

Name
signal_type
Type
string
Description
The type of signal. If supplied, must be one of the following...
If not supplied we will attempt to detect this.
If you would like to send us a different signal type, please contact us
Loading options....

Name
extra_data
Type
object
Description
Vendor specific extra data optionally supplied to further qualify the signal if desired. This allows for additional classification of data and/or additional abuse type specific fields.
This should be supplied as a standard top level JSON object with key / value pairs. Nested object and arrays are permitted.

Response Attributes

Name
adds
Type
number
Description
The number of successfully added new signal reports based on the passed request.

Name
updates
Type
number
Description
Not used for new signal reports - always set to 0.

Name
replaces
Type
number
Description
Not used for new signal reports - always set to 0.

Name
deletes
Type
number
Description
Not used for new signal reports - always set to 0.

Name
rejected
Type
number
Description
The number of signal reports which were not able to be added from the request (usually due to validation errors)

Name
validationErrors
Type
object
Description
An object containing validation errors generated from the passed signal reports when one or more items has been rejected.

An array of validation error objects will be returned under the add property of the returned object. This array will have a validation object for each rejected object passed in the request.

Each validation object will have the following properties:

itemNumber - identifies the numerical array item index for the rejected object within the supplied request payload array. validationErrors - An object with keys representing the fields which have failed validation. The value for each of these keys is a descriptive string identifying the reason for the field validation to have failed.
It will only appear if the rejected field is > 0

Request

POST · /signal

curl -X POST https://signals.gse.live/report/signal \
  -H "API-KEY: YOUR-API-KEY-HERE" \
  -H "API-SECRET: YOUR-API-SECRET-HERE" \

Payload

[
  {
    "signal": "https://somesignal.com",
    "report_date": "2020-01-23 14:24:06",
    "abuse_type": "phishing",
    "signal_type": "url",
    "predictive": false,
    "confidence_score": "85",
    "extra_data": {"category": "internal", "collection_method": "form_submission"}
  },
  // ...
]

Response

[
  {
    "adds": 1,
    "updates": 0,
    "replaces": 0,
    "deletes": 0,
    "rejected": 2,
    "validationErrors": {"add":[{"itemNumber":0,"validationErrors":{"report_date":"Value required for report_date","abuse_type":"Value required for abuse_type"}},{"itemNumber":1,"validationErrors":{"report_date":"Value required for report_date","abuse_type":"Value required for abuse_type"}}]}
  },
  // ...
]

POSThttps://signals.gse.live/report/image/signal

Sending new signal reports as image

Send one or more new signal reports as base64 encoded images. The signal and other meta data will be extracted from each image according to the other parameters supplied and then converted to structured data to be stored as signals. The whole text detected within the image will be stored as extra_data for the signal using a key of extracted_text.

Payload Attributes

Required attributes

Name
base64_image
Type
string
Description
The image string to process for signal information in base64 encoded format

Optional attributes

Name
signal_type
Type
string
Description
If supplied, this will be used to determine which signal type to extract as the signal from the image - if no signal_pattern attribute is supplied the known format for the signal type will be used to detect the signal.
e.g. url, ip address etc.
Loading options....

Name
signal_pattern
Type
string
Description
Custom regular expression to use for detecting the signal within the image. If supplied, a signal type must also be supplied.

Response Attributes

Name
adds
Type
number
Description
The number of successfully added new signal reports based on the passed request.

Name
updates
Type
number
Description
Not used for new signal reports - always set to 0.

Name
replaces
Type
number
Description
Not used for new signal reports - always set to 0.

Name
deletes
Type
number
Description
Not used for new signal reports - always set to 0.

Name
rejected
Type
number
Description
The number of signal reports which were not able to be added from the request (usually due to validation errors)

Name
validationErrors
Type
object
Description
An object containing validation errors generated from the passed signal reports when one or more items has been rejected.

An array of validation error objects will be returned under the add property of the returned object. This array will have a validation object for each rejected object passed in the request.

Each validation object will have the following properties:

itemNumber - identifies the numerical array item index for the rejected object within the supplied request payload array. validationErrors - An object with keys representing the fields which have failed validation. The value for each of these keys is a descriptive string identifying the reason for the field validation to have failed.
It will only appear if the rejected field is > 0

Request

POST · /image

curl -X POST https://signals.gse.live/report/image \
  -H "API-KEY: YOUR-API-KEY-HERE" \
  -H "API-SECRET: YOUR-API-SECRET-HERE" \

Payload

[
  {
    "base64_image": "A435435456FFE2345",
    "signal_type": "url",
    "signal_pattern": "[a-z]+[0-9]"
  },
  // ...
]

Response

[
  {
    "adds": 1,
    "updates": 0,
    "replaces": 0,
    "deletes": 0,
    "rejected": 2,
    "validationErrors": {"add":[{"itemNumber":0,"validationErrors":{"report_date":"Value required for report_date","abuse_type":"Value required for abuse_type"}},{"itemNumber":1,"validationErrors":{"report_date":"Value required for report_date","abuse_type":"Value required for abuse_type"}}]}
  },
  // ...
]

POSThttps://signals.gse.live/report/text/signal

Sending new signal reports as text

Send one or more new signal reports as unprocessed text blocks. The signal and other meta data will be extracted from each text block according to the other parameters supplied and then converted to structured data to be stored as signals. The whole text passed will be stored as extra_data for the signal using a key of extracted_text.

Payload Attributes

Required attributes

Name
text
Type
string
Description
The text string to process for signal information

Optional attributes

Name
signal_type
Type
string
Description
If supplied, this will be used to determine which signal type to extract as the signal from the image - if no signal_pattern attribute is supplied the known format for the signal type will be used to detect the signal.
e.g. url, ip address etc.
Loading options....

Name
signal_pattern
Type
string
Description
Custom Regular expression for detecting the signal within the text. If supplied, a signal type must also be supplied.

Response Attributes

Name
adds
Type
number
Description
The number of successfully added new signal reports based on the passed request.

Name
updates
Type
number
Description
Not used for new signal reports - always set to 0.

Name
replaces
Type
number
Description
Not used for new signal reports - always set to 0.

Name
deletes
Type
number
Description
Not used for new signal reports - always set to 0.

Name
rejected
Type
number
Description
The number of signal reports which were not able to be added from the request (usually due to validation errors)

Name
validationErrors
Type
object
Description
An object containing validation errors generated from the passed signal reports when one or more items has been rejected.

An array of validation error objects will be returned under the add property of the returned object. This array will have a validation object for each rejected object passed in the request.

Each validation object will have the following properties:

itemNumber - identifies the numerical array item index for the rejected object within the supplied request payload array. validationErrors - An object with keys representing the fields which have failed validation. The value for each of these keys is a descriptive string identifying the reason for the field validation to have failed.
It will only appear if the rejected field is > 0

Request

POST · /text

curl -X POST https://signals.gse.live/report/text \
  -H "API-KEY: YOUR-API-KEY-HERE" \
  -H "API-SECRET: YOUR-API-SECRET-HERE" \

Payload

[
  {
    "text": "a text block with an embedded signal https://example.com contained within it.",
    "signal_type": "url",
    "signal_pattern": "[a-z]+[0-9]"
  },
  // ...
]

Response

[
  {
    "adds": 1,
    "updates": 0,
    "replaces": 0,
    "deletes": 0,
    "rejected": 2,
    "validationErrors": {"add":[{"itemNumber":0,"validationErrors":{"report_date":"Value required for report_date","abuse_type":"Value required for abuse_type"}},{"itemNumber":1,"validationErrors":{"report_date":"Value required for report_date","abuse_type":"Value required for abuse_type"}}]}
  },
  // ...
]

GEThttps://signals.gse.live/report/signal

List all of the signals you have sent

Return all of the imported signals you have uploaded via your account.

Request Attributes

Required attributes

Name
limit
Type
integer
Description
Limit the number of results to the supplied number

Name
offset
Type
integer
Description
Offset the results by the supplied number
Defaults to 0

Name
sort
Type
string
Description
Sort the results by supplying a column name and direction. eg signal|desc

Response Attributes

Name
signal
Type
string
Description
The signal you want to share.

Name
report_date
Type
datetime
Description
Date & time the signal was reported.

Name
abuse_type
Type
string
Description
The type of abuse this signal represents. Must be one of the following types...
e.g. phishing, malware
If you would like to send us a different abuse type, please contact us
Loading options....

Name
signal_type
Type
string
Description
The type of signal. If supplied, must be one of the following.
e.g. url,hostname
If not supplied we will attempt to detect this. If you would like to send us a different signal type, please contact us
Loading options....

Name
predictive
Type
boolean
Description
An indication that this signal was generated using an algorithm rather than confirmed report.

Name
confidence_score
Type
integer
Description
Number between 0-100. A score of 100 would indicate the highest confidence in this signal

Name
extra_data
Type
object
Description
Vendor specific extra data optionally supplied to further qualify the signal if desired. This allows for additional classification of data and/or additional abuse type specific fields.
This should be formatted as a standard top level JSON object with key / value pairs. Nested object and arrays are permitted.

Request

GET · /signal

curl -X GET https://signals.gse.live/report/signal \
-H "API-KEY: YOUR-API-KEY-HERE" \
-H "API-SECRET: YOUR-API-SECRET-HERE" \ \
-d limit=[[value]] \
-d offset=[[value]] \
-d sort=[[value]] \

Response

[
  {
    "signal": "https://somesignal.com",
    "report_date": "2020-01-23 14:24:06",
    "abuse_type": "phishing",
    "signal_type": "phishing",
    "predictive": false,
    "confidence_score": "85",
    "extra_data": {"category": "internal", "collection_method": "form_submission"}
  },
  // ...
]

Prev Next