Skip to content

Query contributions​

GET
/data/api/v1/contribution-management/contribution

Returns the records that match the filters, latest upload first, and charges the company for the records it sees for the first time.

What is returned: active and flagged records that have not expired. A privileged record is returned only to its own company and to the companies it has approved.

What is charged, with fetch-mode=DEFAULT:

  • Own records are free and counted in details.self.
  • Records bought before are free and counted in details.old.
  • Records of a privileged company that approved the caller's company are free and counted in details.new.
  • Every other record is bought and counted in details.new. The price is per identifier: a range costs the price times the number of values in it. Email addresses and URLs cost nothing.
  • A record the balance does not cover is not returned. It is counted in details.contributionsNotReturned and its cost is added to details.contributionsNotReturnedCost.

Companies on the TRIAL and PAID subscriptions are not charged.

The counters of the answer are in details.

Repeat ft, org and dst to pass several values, for example ?ft=Wangiri&ft=IRSF.

Authorizations​

bearerAuth

The accessToken of a sign-in or refresh answer. Valid for 5 minutes.

Type
HTTP (bearer)

Parameters​

Query Parameters

size

The most records to return. Without it all matching records are returned.

Type
integer
Example50
Format
"int32"
Minimum
0
from

Return records uploaded at or after this time. An ISO 8601 date-time with an offset or Z. Encode a + of the offset as %2B.

Type
string
Example"2026-01-01T00:00:00Z"
Format
"date-time"
to

Return records uploaded at or before this time. An ISO 8601 date-time with an offset or Z. Encode a + of the offset as %2B.

Type
string
Example"2026-01-31T23:59:59Z"
Format
"date-time"
ft

Return only records of these fraud types. Repeat the parameter for several types. Without it all types are returned. Names that are not fraud types are ignored. Not applied with fetch-mode=SELF.

Type
array
Example"Wangiri""IRSF"
org

Return only records with one of these origination countries (ISO 3166-1 alpha-2). Repeat the parameter for several countries.

Type
array
Example"GB""IS"
dst

Return only records with one of these destination countries (ISO 3166-1 alpha-2). Repeat the parameter for several countries.

Type
array
Example"NZ""FJ"
fetch-mode

Which records to return.

  • DEFAULT: own records, records bought before, and records not seen before, which are bought.
  • NEW: only records that other companies uploaded and that the company has never bought. They are bought. A record another company uploaded with the caller's company as its source is included.
  • OLD: only own records and records bought before. Nothing is charged.
  • SELF: only records the company uploaded itself. Records that name it as the source are not included, and ft is not applied. Nothing is charged.
Type
string
Valid values
"DEFAULT""NEW""OLD""SELF"
Example"DEFAULT"
Default
"DEFAULT"
confidence-score

Reserved. Ignored; always empty.

Type
boolean
Examplefalse
Default
false

Responses​

The matching records and what the query cost.

application/json
JSON
{
  
"status": {
  
  
"code": 0,
  
  
"name": "Ok"
  
},
  
"data": {
  
  
"contributions": [
  
  
  
{
  
  
  
  
"id": "+447700900301-+447700900301",
  
  
  
  
"fraudType": "Wangiri",
  
  
  
  
"origination": "IS",
  
  
  
  
"destination": "NZ",
  
  
  
  
"expiryDate": "2026-03-16T10:00:00Z",
  
  
  
  
"fraudStatus": "Active",
  
  
  
  
"confidenceIndex": null,
  
  
  
  
"isPrivileged": false,
  
  
  
  
"peerId": "example_vendor",
  
  
  
  
"flagger": null,
  
  
  
  
"timestamp": "2026-01-15T10:00:00Z",
  
  
  
  
"flagTimestamp": null,
  
  
  
  
"assetDefinitionId": "00000000-0000-7000-8000-000000000001",
  
  
  
  
"sourcePeerId": "example_vendor"
  
  
  
}
  
  
],
  
  
"details": {
  
  
  
"self": 0,
  
  
  
"old": 0,
  
  
  
"new": 1,
  
  
  
"newWithConfidenceIndex": 0,
  
  
  
"creditsSpent": 1,
  
  
  
"balanceLeft": 19,
  
  
  
"contributionsNotReturned": 0,
  
  
  
"contributionsNotReturnedCost": 0
  
  
}
  
}
}

Samples​

Powered by VitePress OpenAPI