Classify activities and alerts

​

Activity classification compared with alert classification

​

How activity classification works

• Every operation is recorded in the audit log, with the actor, timestamp, and outcome. This includes tag changes and any feedback sent to the monitoring provider.
• An optional comment can be attached to either operation and is stored as part of the audit trail.
• Access is validated against your account. If a tag or record ID does not exist, or belongs to another account, the API returns 404. The response does not indicate whether the record exists. This prevents information disclosure.
• Provider feedback never blocks the operation. Where feedback is sent to the monitoring provider, a delivery failure does not roll back the tag or status change.

• Tags applied to an alert cascade to its associated activity. The activity inherits the alert’s tags.
• manualStatus is required. Tags are optional. Tags are supplementary and record why a decision was made.
• The FALSE_POSITIVE and IN_REVIEW outcomes apply to alerts only. They are review states for the alert, not the underlying activity, and do not cascade to the activity.
• Removing a tag from an alert does not remove it from the activity. Activity tags must be removed separately.
• Tag intent cannot be mixed. A request must not combine FALSE_POSITIVE- or IN_REVIEW-category tags with tags of any other category; the request is rejected with 400. Duplicate tag IDs are removed automatically.
• Feedback is sent automatically to the monitoring provider as part of resolving the alert.

• Tags are required. An activity has no status field: applying a tag is itself the classification, so a request must include at least one.
• Activities carry TRUE_POSITIVE classifications only. FALSE_POSITIVE and IN_REVIEW are alert concepts and cannot be applied directly to an activity. To undo a TRUE_POSITIVE classification, remove the tag — no “false positive” tag is stored in its place.
• Tags applied directly to an activity do not cascade to any alert. (This is the reverse of alert resolution, where tags cascade down to the activity.)
• The request is atomic and idempotent. If any activity or tag ID is invalid, the entire request fails and no tags are applied. Re-applying a tag an activity already has updates the existing classification rather than creating a duplicate. However, feedback is re-sent to your monitoring provider on every request, even if the tags have not changed.
• Feedback reflects the tags on the activity. A TRUE_POSITIVE classification signals the activity as fraudulent to the monitoring provider; removing all TRUE_POSITIVE classifications signals it as not fraudulent. Feedback is triggered only when the activity’s tags are updated.
• FrankieOne always saves the classification to its data stores, even if feedback delivery to the provider fails. On the FrankieOne side, tags can be applied and removed. Feedback delivered to the provider is immutable at the provider end.
• A request must not combine a FALSE_POSITIVE category tag with any other category. Violations are rejected with 422.

​

Classify an activity

​

Before you begin

• The entity exists: Activities are tied to an entity that already exists in the FrankieOne platform.
• The activities exist: You classify activities that were previously submitted through Evaluate an activity. You need their activity IDs.
• The tags exist and are in the ACTIVITY domain: Each tag must exist, be accessible to your account, and have the domain ACTIVITY. See Tags and Reasons reference for the full list of available tags.
• X-Frankie-Username is optional: If provided, it identifies the actor in the audit log.

​

Endpoint

​

Request body

​

Example request

curl -X POST \
  'https://api.uat.frankie.one/v2/activities/classify' \
  -H 'accept: application/json' \
  -H 'api_key: YOUR_API_KEY' \
  -H 'X-Frankie-CustomerID: YOUR_CUSTOMER_ID' \
  -H 'X-Frankie-Username: example@frankieone.com' \
  -H 'Content-Type: application/json' \
  -d '{
    "entityId": "{{entityId}}",
    "activityIds": [
      "{{activityId}}",
      "{{activityId}}"
    ],
    "tagIds": [
      "{{tagId}}"
    ],
    "comment": {
      "text": "Confirmed romance scam pattern after manual review.",
      "entityId": "{{entityId}}",
      "entityType": "INDIVIDUAL"
    }
  }'

​

Example response

{
  "requestId": "01HN9XHZN6MGXM9JXG50K59Q85",
  "mappings": [
    {
      "objectId": "01JN2YRZK8ABCD1234EXAMPLE",
      "objectType": "ACTIVITY",
      "tags": [
        {
          "mappingId": "12345678-1234-1234-1234-123456789012",
          "tagId": "12345678-1234-1234-1234-123456789012",
          "label": "ROMANCE_SCAM",
          "category": "FRAUD",
          "type": "SYSTEM",
          "domain": "ACTIVITY"
        }
      ]
    }
  ]
}

​

Related pages

• Resolve alerts and re-evaluate — set the manual outcome of a flagged result and re-run the workflow.
• Evaluate an activity — submit an activity for monitoring before you classify it.
• Reviewing activities — review activity history and classify activities in the FrankieOne Portal.