Retrieving contributions
NOTE
You must be signed in for this operation. See Authorizing an account.
When downloading fraud events (retrieving contributions) it is possible to filter the results generated in the response in various ways, using the request parameters.
Request parameters can be used in any combination to tailor response results to your specific needs.
Since request parameters are optional, specifying no parameters when sending a request will result in a response containing every contribution that has not expired, and the ones you have not retrieved before are charged. Set size or fetch-mode to limit the cost.
For more information, see API reference > Query contributions.
To retrieve contributions, send the following request:
GET /data/api/v1/contribution-management/contribution?size=<n>&from=<time>&to=<time>&ft=<type>&org=<country>&dst=<country>&fetch-mode=<mode>// size
GET /data/api/v1/contribution-management/contribution?size=10
// from & to
GET /data/api/v1/contribution-management/contribution?from=2024-08-01T00:00:00Z&to=2024-08-31T23:59:59Z
// ft
GET /data/api/v1/contribution-management/contribution?ft=Wangiri
// several fraud types
GET /data/api/v1/contribution-management/contribution?ft=Wangiri&ft=IRSF
// org
GET /data/api/v1/contribution-management/contribution?org=US
// dst
GET /data/api/v1/contribution-management/contribution?dst=GA
// fetch-mode
GET /data/api/v1/contribution-management/contribution?fetch-mode=NEW
// combination
GET /data/api/v1/contribution-management/contribution?size=2&ft=StolenDevice&org=US&fetch-mode=NEWNOTE
Fraud type names are case-sensitive. A name that is not in the list of fraud types, such as wangiri, is ignored, and the request is served without that filter.
To keep your records up to date, request fetch-mode=NEW on a schedule: it returns only the contributions that other companies uploaded and that you have not retrieved yet.
The modes of fetch-mode:
| Mode | Returns | Charged |
|---|---|---|
DEFAULT | Your own contributions, the ones you retrieved before, and the ones you have not retrieved yet. | The ones you have not retrieved yet. |
NEW | Only contributions uploaded by other companies that you have never retrieved. A contribution that another company uploaded with your company as its source counts here too. | All of them. |
OLD | Only your own contributions and the ones you retrieved before. | Nothing. |
SELF | Only contributions your company uploaded itself. The ft filter is not applied in this mode. | Nothing. |
A flagged contribution is returned until its expiry date, with fraudStatus set to Flagged.
For what a request costs, see API reference > Query contributions.
Expected result
The response to the GET request contains the list of the contributions in data.contributions, filtered according to the parameters set in the request, if any. The counters of the request, such as new and creditsSpent, are in data.details.
{
status: {
code: integer($int32),
name: 'string'
},
data: {
contributions: [
{
id: 'string', //127.0.0.1-127.0.0.2 OR +14155552671-+14155552672 OR 107615702016566 OR name@example.com OR https://www.address.com/
fraudType: 'string',
origination: 'string',
destination: 'string',
expiryDate: 'string', //ISO 8601: YYYY-MM-DDTHH:MM:SSZ
fraudStatus: 'string(enum)', //'Active' OR 'Flagged'
confidenceIndex: number($double), //Reserved. Always null
isPrivileged: boolean,
peerId: 'string',
flagger: 'string',
timestamp: 'string', //ISO 8601: YYYY-MM-DDTHH:MM:SSZ
flagTimestamp: 'string', //ISO 8601: YYYY-MM-DDTHH:MM:SSZ
assetDefinitionId: 'string',
sourcePeerId: 'string'
}
],
details: {
self: integer($int32), //The number of returned contributions that have been submitted by the requesting peer
old: integer($int32), //The number of returned contributions that the requesting peer has retrieved before
new: integer($int32), //The number of returned 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 tokens balance after retrieving contributions
contributionsNotReturned: integer($int32), //The number of contributions that met the filters but were not returned, because the balance does not cover them
contributionsNotReturnedCost: integer($int64) //The total cost of the contributions that were not returned
}
}
}{
status: {
code: 0,
name: 'Ok'
},
data: {
contributions: [
{
id: '127.0.0.1-127.0.0.1',
fraudType: 'IPFraud',
origination: 'UA',
destination: 'GB',
expiryDate: '2024-09-30T11:35:41Z',
fraudStatus: 'Active',
confidenceIndex: null,
isPrivileged: false,
peerId: 'test',
flagger: null,
timestamp: '2024-08-31T11:35:41Z',
flagTimestamp: null,
assetDefinitionId: '0192f3a1-7c2e-7b41-9d0a-4f6c2a8e5b10',
sourcePeerId: 'test'
},
{
id: '127.0.0.2-127.0.0.2',
fraudType: 'IPFraud',
origination: 'UA',
destination: 'GB',
expiryDate: '2024-09-29T17:07:33Z',
fraudStatus: 'Flagged',
confidenceIndex: null,
isPrivileged: false,
peerId: 'test',
flagger: 'example_mobile',
timestamp: '2024-08-30T17:07:33Z',
flagTimestamp: '2024-09-15T10:05:24Z',
assetDefinitionId: '0192f3a1-7c2e-7b41-9d0a-4f6c2a8e5b11',
sourcePeerId: 'test'
}
],
details: {
self: 0,
old: 0,
new: 2,
newWithConfidenceIndex: 0,
creditsSpent: 2,
balanceLeft: 50,
contributionsNotReturned: 1,
contributionsNotReturnedCost: 1
}
}
}