Skip to content

Flagging a contribution ​

NOTE

You must be signed in for this operation. See Authorizing an account.

To flag a contribution, perform the following steps:

  1. Retrieve the contribution(s) that you would like to flag by sending the following request:

    http
    GET /data/api/v1/contribution-management/contribution/{id} //{id} is a fraud identifier or a range of them
    http
    GET /data/api/v1/contribution-management/contribution/203.0.113.9
    json5
    {
      status: {
        code: integer($int32),
        name: 'string'
      },
      data: [
        {
          id: 'idRange', //203.0.113.9-203.0.113.20 OR +447700900201-+447700900209 OR 356938035643809
          fraudType: 'string',
          origination: 'string',
          destination: 'string',
          expiryDate: 'string', //ISO 8601: YYYY-MM-DDTHH:MM:SSZ
          fraudStatus: 'string(enum)', //always 'Active' in this response
          confidenceIndex: number($double),
          isPrivileged: boolean,
          peerId: 'string',
          flagger: 'string',
          timestamp: 'string', //ISO 8601: YYYY-MM-DDTHH:MM:SSZ
          flagTimestamp: 'string',
          assetDefinitionId: 'string',
          sourcePeerId: 'string'
        }
      ]
    }
    json5
    {
      status: {
        code: 0,
        name: 'Ok'
      },
      data: [
        {
          id: '203.0.113.9-203.0.113.9',
          fraudType: 'IPFraud',
          origination: 'SE',
          destination: 'GB',
          expiryDate: '2026-12-13T12:46:54Z',
          fraudStatus: 'Active',
          confidenceIndex: null,
          isPrivileged: false,
          peerId: 'example_telecom',
          flagger: null,
          timestamp: '2026-11-13T12:46:54Z',
          flagTimestamp: null,
          assetDefinitionId: '01a1d4f2-5756-7d87-af12-aabd44a70ac9',
          sourcePeerId: 'example_telecom'
        }
      ]
    }

    NOTE

    If the {id} corresponds to a phone number or an IP address, it can be represented as a single value.

    This request is free of charge. It returns active contributions only: a contribution that has expired or is already flagged cannot be flagged. For how the {id} is matched, see API reference > Look up an identifier.

  2. Assemble a contribution flag by sending the following request (use the assetDefinitionId values retrieved in Step 1 for this request):

    http
    PATCH /data/api/v1/contribution-management/contribution/flag/assemble
    json5
    {
      assetDefinitionIds: ['string'] //The `assetDefinitionId` values retrieved in Step 1
    }
    json5
    {
      assetDefinitionIds: ['01a1d4f2-5756-7d87-af12-aabd44a70ac9']
    }
    json5
    {
      status: {
        code: integer($int32),
        name: 'string'
      },
      data: 'transactionHex'
    }
    json5
    {
      status: {
        code: 0,
        name: 'Ok'
      },
      data: '0100f857f2d4a1010000386578616d706c655f6d6f62696c651461646d696e0004080d0801386578616d706c655f6d6f62696c651461646d696e0d0244666c61675f636f6e747269627574696f6e0d01f0313739343537343031342c30316131643466322d353735362d376438372d616631322d61616264343461373061633923636f6e747269627574696f6e01005c26050000000001238a802a00'
    }
  3. Sign the transactionHex string (see Signing transactions) retrieved from the response.

  4. Submit the assembled and signed contribution flag by sending the following request. The body is the signed Hex string as plain text, without quotes:

    http
    PATCH /data/api/v1/contribution-management/contribution/flag
    text
    transactionHex(signed)
    text
    01040080744af44c23360d55f145fd7a0229a39562aa8994d440f5f01337b46196429fa70101d3c0726d4343cc168d530018ab5121b5b824eea6b7a37caf3274b46328bffca6ab3214b06e0c83bf6945d66bce2d3afb8732f30e30ae128aa94d74a43583010ff857f2d4a1010000386578616d706c655f6d6f62696c651461646d696e0004080d0801386578616d706c655f6d6f62696c651461646d696e0d0244666c61675f636f6e747269627574696f6e0d01f0313739343537343031342c30316131643466322d353735362d376438372d616631322d61616264343461373061633923636f6e747269627574696f6e01005c26050000000001238a802a00
    json5
    {
      status: {
        code: integer($int32),
        name: 'string'
      },
      data: {
        rewarded: integer($int64)
      }
    }
    json5
    {
      status: {
        code: 0,
        name: 'Ok'
      },
      data: {
        rewarded: 10
      }
    }

Expected result ​

The contribution’s fraudStatus value is set to Flagged, and the submitting peer is rewarded with tokens.

For details, see the following:

NOTE

Flagging a contribution uploaded by the same peer, or one that names it as the original source, does not provide token rewards.

A contribution can be flagged once. Sending the same signed transaction again returns the first response and adds no tokens.