Skip to content

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:

http
GET /data/api/v1/contribution-management/contribution?size=<n>&from=<time>&to=<time>&ft=<type>&org=<country>&dst=<country>&fetch-mode=<mode>
http
// 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=NEW

NOTE

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:

ModeReturnsCharged
DEFAULTYour own contributions, the ones you retrieved before, and the ones you have not retrieved yet.The ones you have not retrieved yet.
NEWOnly 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.
OLDOnly your own contributions and the ones you retrieved before.Nothing.
SELFOnly 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.

json5
{
  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
    }
  }
}
json5
{
  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
    }
  }
}