Contributions
Contribution: a piece of data that describes a fraud event on the Exchange.
Contributions are submitted by the users of approved member companies, and are stored on the Exchange.
A peer or its user that has contributed at least a single fraud event is considered a contributor.
Operations
Submitting contributions
Once a contribution has been submitted, the peer’s list of contributions is updated, and their token balance is increased by the reward in force. A record that the peer already holds is not stored again and is not rewarded again (see Tokens, rewards and limits: Uploading fraud events).
When preparing a contribution for upload, the contributor must specify, whether they are the original source of the fraud event data. To do so, they must leave the sourcePeerId field out. However, if the original source differs from the uploader, the sourcePeerId value must be the peerId of that company on the Exchange. The company must be a member; a name that is not a member is refused with code 70. A company whose contributions are privileged can name only itself. In such cases, the reward is split between the contributor and the original source according to the reward split rules.
For complete instructions on how to submit a contribution, see Submitting a contribution.
For information on the token balance and rewards, see Tokens, rewards and limits.
Retrieving contributions
In order for peers to keep their own records updated with the latest fraud event data, they can retrieve contributions in a number of ways.
Flagging contributions
If a peer finds that a contribution is wrong (a "false positive"), they can flag that contribution. Once a contribution is flagged, the ID of the peer that flagged it is saved with the contribution as flagger value, and the flagging peer is rewarded (see Tokens, rewards and limits: Flagging fraud events). A contribution can be flagged once. A flagged contribution stays available for download until its expiry date.
API data structures
Retrieving contributions
When retrieving contributions, the following data is returned in the body of the response. The fields from id to sourcePeerId describe one contribution in data.contributions. The counters from self to contributionsNotReturnedCost are in data.details:
Response body
| Field | Value Type | Description |
|---|---|---|
id | string | The unique identifier of a fraud event. A single phone number or IP address is returned as a range of itself, e.g. 127.0.0.1-127.0.0.1. |
fraudType | string(enum) | The type of the fraud event. Can be one of the following:
|
origination | string | The two-letter code of the country the fraud event originated from (Alpha-2, ISO 3166). |
destination | string | The two-letter code of the country the fraud event was identified as such (Alpha-2, ISO 3166). |
expiryDate | string | The exact time and date until which the event is considered relevant (ISO 8601: YYYY-MM-DDTHH:MM:SSZ). The expiryDate is set 60 days after the timestamp value, for every fraud type. |
fraudStatus | string(enum) | The status of the fraud event. Can be one of the following:
|
confidenceIndex | number($double) | Reserved. Always null. |
isPrivileged | boolean | The definition of whether a contribution is privileged. |
peerId | string | The unique identifier of the peer that contributed the data. |
flagger | string | The unique identifier of the peer that flagged the data. If a contribution hasn't been flagged at the time of observing, the field returns null. |
timestamp | string | The exact time and date of when a contribution has been submitted (ISO 8601: YYYY-MM-DDTHH:MM:SSZ). |
flagTimestamp | string | The exact time and date of when a contribution has been flagged (ISO 8601: YYYY-MM-DDTHH:MM:SSZ). If a contribution hasn't been flagged at the time of observing, the field returns null. |
self | integer($int32) | In details. Out of all the retrieved contributions, the number of contributions that have been submitted by the requesting peer. |
old | integer($int32) | Out of all the retrieved contributions, the number of contributions of other peers that the requesting peer has retrieved before. |
new | integer($int32) | Out of all the retrieved contributions, the number of contributions that the requesting peer retrieves for the first time. |
newWithConfidenceIndex | integer($int32) | Reserved. Always 0. |
creditsSpent | integer($int64) | The total amount of tokens spent on the retrieved contributions. |
balanceLeft | integer($int64) | The remaining token balance after retrieving contributions. |
contributionsNotReturned | integer($int32) | The number of contributions that met the filter requirements but have not been returned, because the token balance does not cover them. |
contributionsNotReturnedCost | integer($int64) | The total cost of all the contributions that have not been returned but met the filter requirements, i.e., the amount of tokens that were not available on the user's balance at the time of the retrieval. |
assetDefinitionId | string | The unique identifier of a contribution record on the Exchange. |
sourcePeerId | string | The unique identifier of the original source that contributed the data. May be different from the peerId. For details, see Tokens, rewards and limits: Reward split. |
Assembling contributions
When assembling a contribution to then submit it, the following data must be specified in the body of the request:
Request body
| Field | Value Type | Description |
|---|---|---|
id | string | Unique identifier of a fraud event. Or a range of fraud identifiers. Example: 203.0.113.9 OR 203.0.113.9-203.0.113.20 OR +447700900201 OR +447700900201-+447700900209 OR 356938035643809 OR name@example.com OR https://scam.example.com/ The identifier must fit the fraud type: an IPv4 address for IPFraud, a 15-digit IMEI with a correct check digit for StolenDevice, an email address or a URL for Scam, a phone number for every type except IPFraud and StolenDevice. A range must not run backwards. |
fraudType | string(enum) | The type of the fraud event. Can be one of the following:
|
origination | string | The two-letter code of the country the fraud event originated from (Alpha-2, ISO 3166). May be an empty string, or left out, for Scam and for numbers of international networks (+882, +883). For every other entry it is required. |
destination | string | The two-letter code of the country the fraud event was identified as such (Alpha-2, ISO 3166). May be an empty string, or left out, for Scam. For every other entry it is required. |
sourcePeerId | string | The unique identifier of the original source that contributed the data. May be different from the peerId and is an optional field. It must be the peerId of a member company. For details, see Tokens, rewards and limits: Reward split. |