> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Classify activities and alerts

> This guide explains the two classification operations in the Transaction and Activity Monitoring API: classifying an activity by applying tags to it, and resolving an alert by setting its manual status together with the tags. It is written for developers and for fraud or compliance teams building against the API.

## Activity classification compared with alert classification

These are two separate operations. Use the one that matches your intent. Applying a tag to an activity is not the same as resolving the alert that the activity raised.

| Operation                | What you act on                                                        | What it records                                                                                                                                             |
| ------------------------ | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Classify an activity** | The activity itself                                                    | Applies one or more `ACTIVITY`-domain tags (for example, a fraud typology) and sends feedback to the monitoring provider. Does not set a resolution status. |
| **Resolve an alert**     | A flagged [Process Result (PRO)](/v2/docs/tm/concepts-and-definitions) | To resolve an alert and set its manual status, see [Resolve alerts and re-evaluate](/v2/docs/tm/implementation-resolve-reevaluate).                         |

### How activity classification works

Some rules apply to both operations; others are specific to resolving an alert or to classifying an activity. Tags are applied from the FrankieOne-managed catalogue — you cannot create, rename, or delete catalogue tags through this API, and only active tags can be applied.

<Note>
  The rules below cover both operations for reference. The endpoint on this page is **Classify an activity** only. For the alert resolution endpoint, see [Resolve alerts and re-evaluate](/v2/docs/tm/implementation-resolve-reevaluate).
</Note>

When you classify an activity, FrankieOne sends the outcome to the monitoring provider.

**Applies to both**

* **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.

**Alert resolution only**

* **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.

**Activity classification only**

* **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

Applying tags labels the activity itself — for example, marking it as a known fraud typology. The tags in `tagIds` are applied to every activity listed in `activityIds`.

### 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](/v2/docs/tm/implementation-evaluate-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](/v2/docs/tm/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

`POST /v2/activities/classify`

### Request body

<ParamField body="entityId" type="string" required>
  The entity that owns the activities being classified, as a UUID.
</ParamField>

<ParamField body="activityIds" type="string[]" required>
  The activities to classify, as ULIDs. Minimum one. Every ID must exist and belong to `entityId`.
</ParamField>

<ParamField body="tagIds" type="string[]" required>
  The tags to apply, as UUIDs. Minimum one. Every tag must exist, be accessible to your account, and have the domain `ACTIVITY`. The first tag is treated as the primary.

  <Note>
    **Tag ordering matters:** The first tag in `tagIds` is treated as the primary classification by the monitoring provider. Order your tags accordingly.
  </Note>
</ParamField>

<ParamField body="comment" type="object">
  An optional comment recorded in the audit log for this classification.

  <Expandable title="comment properties">
    <ParamField body="text" type="string">
      The comment text.
    </ParamField>

    <ParamField body="entityId" type="string">
      The entity the comment relates to, as a UUID.

      <Note>
        The `entityId` inside the comment does not need to match the top-level `entityId`. The system uses the top-level `entityId` for the classification. Set the comment's `entityId` to the same value unless you have a specific reason not to.
      </Note>
    </ParamField>

    <ParamField body="entityType" type="string">
      The entity type — for example, `INDIVIDUAL` or `ORGANIZATION`.
    </ParamField>
  </Expandable>
</ParamField>

### Example request

```bash theme={null}
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

A `201 Created` response confirms that every activity was tagged and, where configured, feedback was sent to the monitoring provider. The `mappings` array groups the applied tags by activity.

```json theme={null}
{
  "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"
        }
      ]
    }
  ]
}
```

Within each activity, tags are returned newest first (by the time the mapping was created).

For error response structures and common status codes, see [Error handling](/v2/docs/tm/implementation-error-handling).

## Related pages

* [Resolve alerts and re-evaluate](/v2/docs/tm/implementation-resolve-reevaluate) — set the manual outcome of a flagged result and re-run the workflow.
* [Evaluate an activity](/v2/docs/tm/implementation-evaluate-activity) — submit an activity for monitoring before you classify it.
* [Reviewing activities](/v2/docs/tm/features-reviewing-activities) — review activity history and classify activities in the FrankieOne Portal.